OAuth2

v2.0.0

OAuth2 v2.0.0 OAuth2.Client View Source

This module defines the OAuth2.Client struct and is responsible for building and establishing a request for an access token.

Notes

  • If a full url is given (e.g. "http://www.example.com/api/resource") then it will use that otherwise you can specify an endpoint (e.g. "/api/resource") and it will append it to the Client.site.

  • The headers from the Client.headers are appended to the request headers.

Examples 

client = OAuth2.Client.new(token: "abc123")

case OAuth2.Client.get(client, "/some/resource") do
  {:ok, %OAuth2.Response{body: body}} ->
    "Yay!!"
  {:error, %OAuth2.Response{body: body}} ->
    "Something bad happen: #{inspect body}"
  {:error, %OAuth2.Error{reason: reason}} ->
    reason
end

response = OAuth2.Client.get!(client, "/some/resource")

response = OAuth2.Client.post!(client, "/some/other/resources", %{foo: "bar"})

Link to this section Summary

Types

authorize_url()
body()
client_id()
client_secret()
headers()
param()
params()
redirect_uri()
ref()
request_opts()
serializers()
site()
strategy()
t()
token()
token_method()
token_url()

Functions

authorize_url!(client, params \\ [])

Returns the authorize url based on the client configuration.

basic_auth(client)

Adds authorization header for basic auth.

delete(client, url, body \\ "", headers \\ [], opts \\ [])

Makes a DELETE request to the given URL using the OAuth2.AccessToken.

delete!(client, url, body \\ "", headers \\ [], opts \\ [])

Same as delete/5 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

delete_serializer(client, mime)

Un-register a serialization module for a given mime type.

get(client, url, headers \\ [], opts \\ [])

Makes a GET request to the given url using the OAuth2.AccessToken struct.

get!(client, url, headers \\ [], opts \\ [])

Same as get/4 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

get_token(client, params \\ [], headers \\ [], opts \\ [])

Fetches an OAuth2.AccessToken struct by making a request to the token endpoint.

get_token!(client, params \\ [], headers \\ [], opts \\ [])

Same as get_token/4 but raises OAuth2.Error if an error occurs during the request.

merge_params(client, params)

Set multiple params in the client in one call.

new(client \\ %Client{}, opts)

Builds a new OAuth2.Client struct using the opts provided.

patch(client, url, body \\ "", headers \\ [], opts \\ [])

Makes a PATCH request to the given url using the OAuth2.AccessToken struct.

patch!(client, url, body \\ "", headers \\ [], opts \\ [])

Same as patch/5 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

post(client, url, body \\ "", headers \\ [], opts \\ [])

Makes a POST request to the given URL using the OAuth2.AccessToken.

post!(client, url, body \\ "", headers \\ [], opts \\ [])

Same as post/5 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

put(client, url, body \\ "", headers \\ [], opts \\ [])

Makes a PUT request to the given url using the OAuth2.AccessToken struct.

put!(client, url, body \\ "", headers \\ [], opts \\ [])

Same as put/5 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

put_header(client, key, value)

Adds a new header key if not present, otherwise replaces the previous value of that header with value.

put_headers(client, list)

Set multiple headers in the client in one call.

put_param(client, key, value)

Puts the specified value in the params for the given key.

put_serializer(client, mime, module)

Register a serialization module for a given mime type.

refresh_token(token, params \\ [], headers \\ [], opts \\ [])

Refreshes an existing access token using a refresh token.

refresh_token!(client, params \\ [], headers \\ [], opts \\ [])

Calls refresh_token/4 but raises Error if there an error occurs.

Link to this section Types

Link to this type

authorize_url() View Source 
authorize_url() :: binary()

Link to this type

body() View Source 
body() :: any()

Link to this type

client_id() View Source 
client_id() :: binary()

Link to this type

client_secret() View Source 
client_secret() :: binary()

Link to this type

headers() View Source 
headers() :: [{binary(), binary()}]

Link to this type

param() View Source 
param() :: binary() | %{optional(binary()) => param()} | [param()]

Link to this type

params() View Source 
params() :: %{optional(binary()) => param()} | Keyword.t()

Link to this type

redirect_uri() View Source 
redirect_uri() :: binary()

Link to this type

ref() View Source 
ref() :: reference() | nil

Link to this type

request_opts() View Source 
request_opts() :: Keyword.t()

Link to this type

serializers() View Source 
serializers() :: %{optional(binary()) => module()}

Link to this type

site() View Source 
site() :: binary()

Link to this type

strategy() View Source 
strategy() :: module()

Link to this type

t() View Source 
t() :: %OAuth2.Client{
  authorize_url: authorize_url(),
  client_id: client_id(),
  client_secret: client_secret(),
  headers: headers(),
  params: params(),
  redirect_uri: redirect_uri(),
  ref: ref(),
  request_opts: request_opts(),
  serializers: serializers(),
  site: site(),
  strategy: strategy(),
  token: token(),
  token_method: token_method(),
  token_url: token_url()
}

Link to this type

token() View Source 
token() :: OAuth2.AccessToken.t() | nil

Link to this type

token_method() View Source 
token_method() :: :post | :get | atom()

Link to this type

token_url() View Source 
token_url() :: binary()

Link to this section Functions

Link to this function

authorize_url!(client, params \\ []) View Source 
authorize_url!(t(), list()) :: binary()

Returns the authorize url based on the client configuration.

Example 

iex> OAuth2.Client.authorize_url!(%OAuth2.Client{})
"/oauth/authorize?client_id=&redirect_uri=&response_type=code"
Link to this function

basic_auth(client) View Source 
basic_auth(t()) :: t()

Adds authorization header for basic auth.

Link to this function

delete(client, url, body \\ "", headers \\ [], opts \\ []) View Source 
delete(t(), binary(), body(), headers(), Keyword.t()) ::
  {:ok, OAuth2.Response.t()}
  | {:error, OAuth2.Response.t()}
  | {:error, OAuth2.Error.t()}

Makes a DELETE request to the given URL using the OAuth2.AccessToken.

Link to this function

delete!(client, url, body \\ "", headers \\ [], opts \\ []) View Source 
delete!(t(), binary(), body(), headers(), Keyword.t()) ::
  OAuth2.Response.t() | OAuth2.Error.t()

Same as delete/5 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

An OAuth2.Error exception is raised if the request results in an error tuple ({:error, reason}).

Link to this function

delete_serializer(client, mime) View Source 
delete_serializer(t(), binary()) :: t()

Un-register a serialization module for a given mime type.

Example 

iex> client = OAuth2.Client.delete_serializer(%OAuth2.Client{}, "application/json")
%OAuth2.Client{}
iex> OAuth2.Client.get_serializer(client, "application/json")
nil
Link to this function

get(client, url, headers \\ [], opts \\ []) View Source 
get(t(), binary(), headers(), Keyword.t()) ::
  {:ok, OAuth2.Response.t()}
  | {:error, OAuth2.Response.t()}
  | {:error, OAuth2.Error.t()}

Makes a GET request to the given url using the OAuth2.AccessToken struct.

Link to this function

get!(client, url, headers \\ [], opts \\ []) View Source 
get!(t(), binary(), headers(), Keyword.t()) ::
  OAuth2.Response.t() | OAuth2.Error.t()

Same as get/4 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

Link to this function

get_token(client, params \\ [], headers \\ [], opts \\ []) View Source 
get_token(t(), params(), headers(), Keyword.t()) ::
  {:ok, OAuth2.Client.t()}
  | {:error, OAuth2.Response.t()}
  | {:error, OAuth2.Error.t()}

Fetches an OAuth2.AccessToken struct by making a request to the token endpoint.

Returns the OAuth2.Client struct loaded with the access token which can then be used to make authenticated requests to an OAuth2 provider's API.

Arguments

  • client - a OAuth2.Client struct with the strategy to use, defaults to OAuth2.Strategy.AuthCode
  • params - a keyword list of request parameters which will be encoded into a query string or request body dependening on the selected strategy
  • headers - a list of request headers
  • opts - a Keyword list of request options which will be merged with OAuth2.Client.request_opts

Options

  • :recv_timeout - the timeout (in milliseconds) of the request
  • :proxy - a proxy to be used for the request; it can be a regular url or a {host, proxy} tuple
Link to this function

get_token!(client, params \\ [], headers \\ [], opts \\ []) View Source 
get_token!(t(), params(), headers(), Keyword.t()) ::
  OAuth2.Client.t() | OAuth2.Error.t()

Same as get_token/4 but raises OAuth2.Error if an error occurs during the request.

Link to this function

merge_params(client, params) View Source 
merge_params(t(), params()) :: t()

Set multiple params in the client in one call.

Link to this function

new(client \\ %Client{}, opts) View Source 
new(t(), Keyword.t()) :: t()

Builds a new OAuth2.Client struct using the opts provided.

Client struct fields

  • authorize_url - absolute or relative URL path to the authorization endpoint. Defaults to "/oauth/authorize"
  • client_id - the client_id for the OAuth2 provider
  • client_secret - the client_secret for the OAuth2 provider
  • headers - a list of request headers
  • params - a map of request parameters
  • redirect_uri - the URI the provider should redirect to after authorization or token requests
  • request_opts - a keyword list of request options that will be sent to the hackney client. See the hackney documentation for a list of available options.
  • site - the OAuth2 provider site host
  • strategy - a module that implements the appropriate OAuth2 strategy, default OAuth2.Strategy.AuthCode
  • token - %OAuth2.AccessToken{} struct holding the token for requests.
  • token_method - HTTP method to use to request token (:get or :post). Defaults to :post
  • token_url - absolute or relative URL path to the token endpoint. Defaults to "/oauth/token"

Example 

iex> OAuth2.Client.new(token: "123")
%OAuth2.Client{authorize_url: "/oauth/authorize", client_id: "",
client_secret: "", headers: [], params: %{}, redirect_uri: "", site: "",
strategy: OAuth2.Strategy.AuthCode,
token: %OAuth2.AccessToken{access_token: "123", expires_at: nil,
other_params: %{}, refresh_token: nil, token_type: "Bearer"},
token_method: :post, token_url: "/oauth/token"}

iex> token = OAuth2.AccessToken.new("123")
iex> OAuth2.Client.new(token: token)
%OAuth2.Client{authorize_url: "/oauth/authorize", client_id: "",
client_secret: "", headers: [], params: %{}, redirect_uri: "", site: "",
strategy: OAuth2.Strategy.AuthCode,
token: %OAuth2.AccessToken{access_token: "123", expires_at: nil,
other_params: %{}, refresh_token: nil, token_type: "Bearer"},
token_method: :post, token_url: "/oauth/token"}
Link to this function

patch(client, url, body \\ "", headers \\ [], opts \\ []) View Source 
patch(t(), binary(), body(), headers(), Keyword.t()) ::
  {:ok, OAuth2.Response.t()}
  | {:error, OAuth2.Response.t()}
  | {:error, OAuth2.Error.t()}

Makes a PATCH request to the given url using the OAuth2.AccessToken struct.

Link to this function

patch!(client, url, body \\ "", headers \\ [], opts \\ []) View Source 
patch!(t(), binary(), body(), headers(), Keyword.t()) ::
  OAuth2.Response.t() | OAuth2.Error.t()

Same as patch/5 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

An OAuth2.Error exception is raised if the request results in an error tuple ({:error, reason}).

Link to this function

post(client, url, body \\ "", headers \\ [], opts \\ []) View Source 
post(t(), binary(), body(), headers(), Keyword.t()) ::
  {:ok, OAuth2.Response.t()}
  | {:error, OAuth2.Response.t()}
  | {:error, OAuth2.Error.t()}

Makes a POST request to the given URL using the OAuth2.AccessToken.

Link to this function

post!(client, url, body \\ "", headers \\ [], opts \\ []) View Source 
post!(t(), binary(), body(), headers(), Keyword.t()) ::
  OAuth2.Response.t() | OAuth2.Error.t()

Same as post/5 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

An OAuth2.Error exception is raised if the request results in an error tuple ({:error, reason}).

Link to this function

put(client, url, body \\ "", headers \\ [], opts \\ []) View Source 
put(t(), binary(), body(), headers(), Keyword.t()) ::
  {:ok, OAuth2.Response.t()}
  | {:error, OAuth2.Response.t()}
  | {:error, OAuth2.Error.t()}

Makes a PUT request to the given url using the OAuth2.AccessToken struct.

Link to this function

put!(client, url, body \\ "", headers \\ [], opts \\ []) View Source 
put!(t(), binary(), body(), headers(), Keyword.t()) ::
  OAuth2.Response.t() | OAuth2.Error.t()

Same as put/5 but returns a OAuth2.Response or OAuth2.Error exception if the request results in an error.

An OAuth2.Error exception is raised if the request results in an error tuple ({:error, reason}).

Link to this function

put_header(client, key, value) View Source 
put_header(t(), binary(), binary()) :: t()

Adds a new header key if not present, otherwise replaces the previous value of that header with value.

Link to this function

put_headers(client, list) View Source 
put_headers(t(), list()) :: t()

Set multiple headers in the client in one call.

Link to this function

put_param(client, key, value) View Source 
put_param(t(), String.t() | atom(), any()) :: t()

Puts the specified value in the params for the given key.

The key can be a string or an atom. Atoms are automatically convert to strings.

Link to this function

put_serializer(client, mime, module) View Source 
put_serializer(t(), binary(), atom()) :: t()

Register a serialization module for a given mime type.

Example 

iex> client = OAuth2.Client.put_serializer(%OAuth2.Client{}, "application/json", Jason)
%OAuth2.Client{serializers: %{"application/json" => Jason}}
iex> OAuth2.Client.get_serializer(client, "application/json")
Jason
Link to this function

refresh_token(token, params \\ [], headers \\ [], opts \\ []) View Source 
refresh_token(t(), params(), headers(), Keyword.t()) ::
  {:ok, OAuth2.Client.t()}
  | {:error, OAuth2.Response.t()}
  | {:error, OAuth2.Error.t()}

Refreshes an existing access token using a refresh token.

Link to this function

refresh_token!(client, params \\ [], headers \\ [], opts \\ []) View Source 
refresh_token!(t(), params(), headers(), Keyword.t()) ::
  OAuth2.Client.t() | OAuth2.Error.t()

Calls refresh_token/4 but raises Error if there an error occurs.