OAuth2 v0.8.0 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

Types

authorize_url()

body()

client_id()

client_secret()

headers()

param()

params()

redirect_uri()

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

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 \\ %OAuth2.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

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

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}

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 :: OAuth2.AccessToken.t | nil

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 \\ [])

Specs

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.

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

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.