OAuth2 v0.8.3 OAuth2.Client

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{status_code: 401}} ->
"Not Good"
{:ok, %OAuth2.Response{status_code: status_code, body: body}} when status_code in [200..299] ->
"Yay!!"
{:error, %OAuth2.Error{reason: reason}} ->
reason
end

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

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

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

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

Refreshes an existing access token using a refresh token

Types

authorize_url :: binary
body :: any
client_id :: binary
client_secret :: binary
headers :: [{binary, binary}]
param ::
  binary |
  %{optional(binary) => param} |
  [param]
params :: %{optional(binary) => param} | Keyword.t
redirect_uri :: binary
site :: binary
strategy :: module
t :: %OAuth2.Client{authorize_url: authorize_url, client_id: client_id, client_secret: client_secret, headers: headers, params: params, redirect_uri: redirect_uri, site: site, strategy: strategy, token: token, token_method: token_method, token_url: token_url}
token_method :: :post | :get | atom
token_url :: binary

Functions

authorize_url!(client, params \\ [])

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"
basic_auth(client)

Specs

basic_auth(t) :: t

Adds authorization header for basic auth.

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

Specs

delete(t, binary, body, headers, Keyword.t) ::
  {:ok, Response.t} |
  {:error, OAuth2.Error.t}

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

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

Specs

delete!(t, binary, body, headers, Keyword.t) ::
  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}).

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

Specs

get(t, binary, headers, Keyword.t) ::
  {:ok, Response.t} |
  {:error, OAuth2.Error.t}

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

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

Specs

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

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

Specs

get_token(t, params, headers, Keyword.t) ::
  {:ok, OAuth2.Client.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
  • headers - a list of request headers
  • opts - a Keyword list of options

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

Specs

merge_params(t, params) :: t

Set multiple params in the client in one call.

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

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
  • 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”}

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

Specs

patch(t, binary, body, headers, Keyword.t) ::
  {:ok, Response.t} |
  {:error, OAuth2.Error.t}

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

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

Specs

patch!(t, binary, body, headers, Keyword.t) ::
  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}).

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

Specs

post(t, binary, body, headers, Keyword.t) ::
  {:ok, Response.t} |
  {:error, OAuth2.Error.t}

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

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

Specs

post!(t, binary, body, headers, Keyword.t) ::
  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}).

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

Specs

put(t, binary, body, headers, Keyword.t) ::
  {:ok, Response.t} |
  {:error, OAuth2.Error.t}

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

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

Specs

put!(t, binary, body, headers, Keyword.t) ::
  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}).

put_header(client, key, value)

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.

put_headers(client, list)

Specs

put_headers(t, list) :: t

Set multiple headers in the client in one call.

put_param(client, key, value)

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.

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

Specs

refresh_token(t, params, headers, Keyword.t) ::
  {:ok, OAuth2.Client.t} |
  {:error, OAuth2.Error.t}

Refreshes an existing access token using a refresh token.

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

Specs

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