Assent.Strategy.OAuth2 (Assent v0.1.15) 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. If not set, no authentication will be used during the access token request. 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 toHS256
for:client_secret_jwt
andRS256
for:private_key_jwt
Usage
config = [
client_id: "REPLACE_WITH_CLIENT_ID",
client_secret: "REPLACE_WITH_CLIENT_SECRET",
auth_method: :client_secret_post,
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
Generate authorization URL for request phase.
Callback phase for generating access token with authorization code and fetch
user data. Returns a map with access token in :token
and user data in
:user
.
Performs a HTTP GET request to the API using the access token.
Gets an access token.
Fetch user data with the access token.
Refreshes the access token.
Link to this section Functions
Specs
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[]
Specs
callback(Assent.Config.t(), map(), atom()) :: {:ok, %{user: map(), token: map()}} | {:error, term()}
Callback phase for generating access token with authorization code and fetch
user data. Returns a map with access token in :token
and user data in
:user
.
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 fromauthorize_url/1
, optional
Specs
Performs a HTTP GET request to the API using the access token.
Uses authorization_headers/2
for headers.
Specs
get_access_token(Assent.Config.t(), binary(), Keyword.t()) :: {:ok, map()} | {:error, term()}
Gets an access token.
Specs
Fetch user data with the access token.
Uses get/4
to fetch the user data.
Specs
refresh_access_token(Assent.Config.t(), map(), Keyword.get()) :: {:ok, map()} | {:error, term()}
Refreshes the access token.