OAuth2.Client (OAuth2 v2.1.0) 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

Functions

Returns the authorize url based on the client configuration.

Adds authorization header for basic auth.

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

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

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

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

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

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

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

Set multiple params in the client in one call.

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

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

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

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

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

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

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

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

Set multiple headers in the client in one call.

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

Register a serialization module for a given mime type.

Refreshes an existing access token using a refresh token.

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

Link to this section Types

Specs

authorize_url() :: binary()

Specs

body() :: any()

Specs

client_id() :: binary()

Specs

client_secret() :: binary()

Specs

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

Specs

param() :: binary() | %{required(binary()) => param()} | [param()]

Specs

params() :: %{required(binary()) => param()} | Keyword.t() | %{}

Specs

redirect_uri() :: binary()

Specs

ref() :: reference() | nil

Specs

request_opts() :: Keyword.t()

Specs

serializers() :: %{required(binary()) => module()}

Specs

site() :: binary()

Specs

strategy() :: module()

Specs

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()
}

Specs

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

Specs

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

Specs

token_url() :: binary()

Link to this section Functions

Link to this function

authorize_url!(client, params \\ [])

View Source

Specs

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"

Specs

basic_auth(t()) :: t()

Adds authorization header for basic auth.

Link to this function

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

View Source

Specs

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

Specs

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

Specs

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

Specs

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

Specs

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

Specs

get_token(t(), params(), headers(), Keyword.t()) ::
  {:ok, 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 depending 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

Specs

get_token!(t(), params(), headers(), Keyword.t()) :: 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

Specs

merge_params(t(), params()) :: t()

Set multiple params in the client in one call.

Link to this function

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

View Source

Specs

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

Specs

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

Specs

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

Specs

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

Specs

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

Specs

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

Specs

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

Specs

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

Specs

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

Specs

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

Specs

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

Specs

refresh_token(t(), params(), headers(), Keyword.t()) ::
  {:ok, 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

Specs

refresh_token!(t(), params(), headers(), Keyword.t()) :: t() | OAuth2.Error.t()

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