Assent v0.1.2 Assent.Strategy.OAuth2 View Source

OAuth 2.0 strategy.

This strategy only supports the Authorization Code flow per RFC 6749.

authorize_url/1 returns a map with a :url and :session_params key. The :session_params should be stored and passed back into callback/3 as part of config when the user returns. The :session_params carries a :state value for the request to prevent CSRF.

This library also supports JWT tokens for client authentication as per RFC 7523.

Configuration

:client_id - The OAuth2 client id, required
:site - The domain of the OAuth2 server, required
:auth_method - The authentication strategy used, optional, defaults to :client_secret_basic. The value may be one of the following:
- :client_secret_basic - Authenticate with basic authorization header
- :client_secret_post - Authenticate with post params
- :client_secret_jwt - Authenticate with JWT using :client_secret as secret
- :private_key_jwt - Authenticate with JWT using :private_key_path or :private_key as secret
:client_secret - The OAuth2 client secret, required if :auth_method is :client_secret_basic, :client_secret_post, or :client_secret_jwt
:private_key_id - The private key ID, required if :auth_method is :private_key_jwt
:private_key_path - The path for the private key, required if :auth_method is :private_key_jwt and :private_key hasn't been set
:private_key - The private key content that can be defined instead of :private_key_path, required if :auth_method is :private_key_jwt and :private_key_path hasn't been set
:jwt_algorithm - The algorithm to use for JWT signing, optional, defaults to HS256 for :client_secret_jwt and RS256 for :private_key_jwt

Usage

config =  [
  client_id: "REPLACE_WITH_CLIENT_ID",
  client_secret: "REPLACE_WITH_CLIENT_SECRET",
  site: "https://auth.example.com",
  authorization_params: [scope: "user:read user:write"],
  user_url: "https://example.com/api/user"
]

{:ok, {url: url, session_params: session_params}} =
  config
  |> Assent.Config.put(:redirect_uri, "http://localhost:4000/auth/callback")
  |> Assent.Strategy.OAuth2.authorize_url()

{:ok, %{user: user, token: token}} =
  config
  |> Assent.Config.put(:session_params, session_params)
  |> Assent.Strategy.OAuth2.callback(params)

Link to this section Summary

Functions

authorization_headers(config, token)

authorize_url(config)

Generate authorization URL for request phase.

callback(config, params, strategy \\ __MODULE__)

Callback phase for generating access token and fetch user data.

get(config, token, url, params \\ [])

Makes a HTTP get request to the API.

get_user(config, token, params \\ [])

Link to this section Functions

authorization_headers(config, token)

authorization_headers(Assent.Config.t(), map()) :: [{binary(), binary()}]

authorize_url(config)

authorize_url(Assent.Config.t()) ::
  {:ok, %{session_params: %{state: binary()}, url: binary()}} | {:error, term()}

Generate authorization URL for request phase.

Configuration

:redirect_uri - The URI that the server redirects the user to after authentication, required
:authorize_url - The path or URL for the OAuth2 server to redirect users to, defaults to /oauth/authorize
:authorization_params - The authorization parameters, defaults to []

callback(config, params, strategy \\ MODULE)

callback(Assent.Config.t(), map(), atom()) ::
  {:ok, %{user: map(), token: map()}} | {:error, term()}

Callback phase for generating access token and fetch user data.

Configuration

:token_url - The path or URL to fetch the token from, optional, defaults to /oauth/token
:user_url - The path or URL to fetch user data, required
:session_params - The session parameters that was returned from authorize_url/1, optional

get(config, token, url, params \\ [])

get(Assent.Config.t(), map(), binary(), map() | Keyword.t()) ::
  {:ok, map()} | {:error, term()}

Makes a HTTP get request to the API.

JSON responses will be decoded to maps.

get_user(config, token, params \\ [])

get_user(Assent.Config.t(), map(), map() | Keyword.t()) ::
  {:ok, map()} | {:error, term()}