View Source DSL: AshAuthentication.Strategy.Oidc
Strategy for authentication using an OpenID Connect compatible server as the source of truth.
This strategy builds on-top of AshAuthentication.Strategy.OAuth2
and
assent
.
In order to use OIDC you need to provide the following minimum configuration:
client_id
- The client id, requiredsite
- The OIDC issuer, requiredopenid_configuration_uri
- The URI for OpenID Provider, optional, defaults to/.well-known/openid-configuration
client_authentication_method
- The Client Authentication method to use, optional, defaults toclient_secret_basic
client_secret
- The client secret, required if:client_authentication_method
is:client_secret_basic
,:client_secret_post
, or:client_secret_jwt
openid_configuration
- The OpenID configuration, optional, the configuration will be fetched from:openid_configuration_uri
if this is not definedid_token_signed_response_alg
- Theid_token_signed_response_alg
parameter sent by the Client during Registration, defaults toRS256
id_token_ttl_seconds
- The number of seconds fromiat
that an ID Token will be considered valid, optional, defaults to nilnonce
- The nonce to use for authorization request, optional, MUST be session based and unguessable.
Nonce
nonce
can be set in the provider config. The nonce
will be returned in the
session_params
along with state
. You can use this to store the value in
the current session e.g. a httpOnly session cookie.
A random value generator can look like this:
16
|> :crypto.strong_rand_bytes()
|> Base.encode64(padding: false)
AshAuthentication will dynamically generate one for the session if nonce
is
set to true
.
DSL Documentation
Provides an OpenID Connect authentication strategy.
This strategy is built using the :oauth2
strategy, and thus provides
all the same configuration options should you need them.
Schema:
:name
(atom/0
) - Required. Uniquely identifies the strategy.:client_id
- Required. The OAuth2 client ID.
Takes either a module which implements theAshAuthentication.Secret
behaviour, a 2 arity anonymous function or a string.
See the module documentation forAshAuthentication.Secret
for more information.Example:
client_id fn _, resource -> :my_app |> Application.get_env(resource, []) |> Keyword.fetch(:oauth_client_id) end
:base_url
- The base URL of the OAuth2 server - including the leading protocol (iehttps://
).
Takes either a module which implements theAshAuthentication.Secret
behaviour, a 2 arity anonymous function or a string.
See the module documentation forAshAuthentication.Secret
for more information.Example:
base_url fn _, resource -> :my_app |> Application.get_env(resource, []) |> Keyword.fetch(:oauth_site) end
:site
- Deprecated: Usebase_url
instead.: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
:client_secret_post
:client_secret_jwt
:private_key_jwt
Valid values are nil, :client_secret_basic, :client_secret_post, :client_secret_jwt, :private_key_jwt The default value is:client_secret_post
.
:client_secret
- The OAuth2 client secret.
Required if :auth_method is:client_secret_basic
,:client_secret_post
or:client_secret_jwt
.
Takes either a module which implements theAshAuthentication.Secret
behaviour, a 2 arity anonymous function or a string.
See the module documentation forAshAuthentication.Secret
for more information.Example:
site fn _, resource -> :my_app |> Application.get_env(resource, []) |> Keyword.fetch(:oauth_site) end
:authorize_url
- Required. The API url to the OAuth2 authorize endpoint.
Relative to the value ofsite
.
Takes either a module which implements theAshAuthentication.Secret
behaviour, a 2 arity anonymous function or a string.
See the module documentation forAshAuthentication.Secret
for more information.Example:
authorize_url fn _, _ -> {:ok, "https://exampe.com/authorize"} end
:token_url
- Required. The API url to access the token endpoint.
Relative to the value ofsite
.
Takes either a module which implements theAshAuthentication.Secret
behaviour, a 2 arity anonymous function or a string.
See the module documentation forAshAuthentication.Secret
for more information.Example:
token_url fn _, _ -> {:ok, "https://example.com/oauth_token"} end
:private_key
- The private key to use if:auth_method
is:private_key_jwt
Takes either a module which implements theAshAuthentication.Secret
behaviour, a 2 arity anonymous function or a string.
See the module documentation forAshAuthentication.Secret
for more information.:redirect_uri
- Required. The callback URI base.
Not the whole URI back to the callback endpoint, but the URI to yourAuthPlug
. We can generate the rest.
Whilst not particularly secret, it seemed prudent to allow this to be configured dynamically so that you can use different URIs for different environments.
Takes either a module which implements theAshAuthentication.Secret
behaviour, a 2 arity anonymous function or a string.
See the module documentation forAshAuthentication.Secret
for more information.:authorization_params
(keyword/0
) - Any additional parameters to encode in the request phase.
eg:authorization_params scope: "openid profile email"
The default value is[]
.:registration_enabled?
(boolean/0
) - Is registration enabled for this provider?
If this option is enabled, then new users will be able to register for your site when authenticating and not already present.
If not, then only existing users will be able to authenticate. The default value istrue
.:register_action_name
(atom/0
) - The name of the action to use to register a user.
Only needed ifregistration_enabled?
istrue
.
Because we we don't know the response format of the server, you must implement your own registration action of the same name.
See the "Registration and Sign-in" section of the module documentation for more information.
The default is computed from the strategy name eg:register_with_#{name}
.:sign_in_action_name
(atom/0
) - The name of the action to use to sign in an existing user.
Only needed ifregistration_enabled?
isfalse
.
Because we don't know the response format of the server, you must implement your own sign-in action of the same name.
See the "Registration and Sign-in" section of the module documentation for more information.
The default is computed from the strategy name, eg:sign_in_with_#{name}
.:identity_resource
- The resource used to store user identities.
Given that a user can be signed into multiple different authentication providers at once we use theAshAuthentication.UserIdentity
resource to build a mapping between users, providers and that provider's uid.
See the Identities section of the module documentation for more information.
Set tofalse
to disable. The default value isfalse
.:identity_relationship_name
(atom/0
) - Name of the relationship to the provider identities resource The default value is:identities
.:identity_relationship_user_id_attribute
(atom/0
) - The name of the destination (user_id) attribute on your provider identity resource.
The only reason to change this would be if you changed theuser_id_attribute_name
option of the provider identity. The default value is:user_id
.:icon
(atom/0
) - The name of an icon to use in any potential UI.
This is a hint for UI generators to use, and not in any way canonical. The default value is:oauth2
.:openid_configuration_uri
(String.t/0
) - The URI for the OpenID provider The default value is"/.well-known/openid-configuration"
.:client_authentication_method
- The client authentication method to use. Valid values are :client_secret_basic, :client_secret_post, :client_secret_jwt, :private_key_jwt The default value is:client_secret_basic
.:openid_configuration
(map/0
) - The OpenID configuration.
If not set, the configuration will be retrieved fromopenid_configuration_uri
. The default value is%{}
.:id_token_signed_response_alg
- Theid_token_signed_response_alg
parameter sent by the Client during Registration. Valid values are "HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "Ed25519", "Ed25519ph", "Ed448", "Ed448ph", "EdDSA" The default value is"RS256"
.:id_token_ttl_seconds
- The number of seconds fromiat
that an ID Token will be considered valid. The default value isnil
.:nonce
- A function for generating the session nonce.
When set totrue
the nonce will be automatically generated usingAshAuthentication.Strategy.Oidc.NonceGenerator
. Set tofalse
to explicitly disable.
Takes either a module which implements theAshAuthentication.Secret
behaviour, a 2 arity anonymous function or a string.
See the module documentation forAshAuthentication.Secret
for more information.Example:
nonce fn _, _ -> 16 |> :crypto.strong_rand_bytes() |> Base.encode64(padding: false) end
The default value is
true
.:trusted_audiences
- A list of audiences which are trusted. The default value isnil
.
authentication.strategies.oidc
oidc name \ :oidc
Provides an OpenID Connect authentication strategy.
This strategy is built using the :oauth2
strategy, and thus provides
all the same configuration options should you need them.
Schema:
Arguments
Name | Type | Default | Docs | |
---|---|---|---|---|
name * |
atom
|
Uniquely identifies the strategy. |
Options
Name | Type | Default | Docs | |
---|---|---|---|---|
client_id * |
(any, any -> any) | module | String.t
|
The OAuth2 client ID. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. See the module documentation for `AshAuthentication.Secret` for more information. Example: ```elixir client_id fn _, resource -> :my_app |> Application.get_env(resource, []) |> Keyword.fetch(:oauth_client_id) end ``` | ||
authorize_url * |
(any, any -> any) | module | String.t
|
The API url to the OAuth2 authorize endpoint. Relative to the value of `site`. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. See the module documentation for `AshAuthentication.Secret` for more information. Example: ```elixir authorize_url fn _, _ -> {:ok, "https://exampe.com/authorize"} end ``` | ||
token_url * |
(any, any -> any) | module | String.t
|
The API url to access the token endpoint. Relative to the value of `site`. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. See the module documentation for `AshAuthentication.Secret` for more information. Example: ```elixir token_url fn _, _ -> {:ok, "https://example.com/oauth_token"} end ``` | ||
redirect_uri * |
(any, any -> any) | module | String.t
|
The callback URI base. Not the whole URI back to the callback endpoint, but the URI to your `AuthPlug`. We can generate the rest. Whilst not particularly secret, it seemed prudent to allow this to be configured dynamically so that you can use different URIs for different environments. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. See the module documentation for `AshAuthentication.Secret` for more information. | ||
base_url |
(any, any -> any) | module | String.t
|
The base URL of the OAuth2 server - including the leading protocol (ie `https://`). Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. See the module documentation for `AshAuthentication.Secret` for more information. Example: ```elixir base_url fn _, resource -> :my_app |> Application.get_env(resource, []) |> Keyword.fetch(:oauth_site) end ``` | ||
site |
(any, any -> any) | module | String.t
|
Deprecated: Use `base_url` instead. | ||
auth_method |
nil | :client_secret_basic | :client_secret_post | :client_secret_jwt | :private_key_jwt
|
:client_secret_post
|
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` * `:client_secret_post` * `:client_secret_jwt` * `:private_key_jwt` | |
client_secret |
(any, any -> any) | module | String.t
|
The OAuth2 client secret. Required if :auth_method is `:client_secret_basic`, `:client_secret_post` or `:client_secret_jwt`. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. See the module documentation for `AshAuthentication.Secret` for more information. Example: ```elixir site fn _, resource -> :my_app |> Application.get_env(resource, []) |> Keyword.fetch(:oauth_site) end ``` | ||
private_key |
(any, any -> any) | module | String.t
|
The private key to use if `:auth_method` is `:private_key_jwt` Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. See the module documentation for `AshAuthentication.Secret` for more information. | ||
authorization_params |
Keyword.t
|
[]
|
Any additional parameters to encode in the request phase. eg: `authorization_params scope: "openid profile email"` | |
registration_enabled? |
boolean
|
true
|
Is registration enabled for this provider? If this option is enabled, then new users will be able to register for your site when authenticating and not already present. If not, then only existing users will be able to authenticate. | |
register_action_name |
atom
|
The name of the action to use to register a user. Only needed if `registration_enabled?` is `true`. Because we we don't know the response format of the server, you must implement your own registration action of the same name. See the "Registration and Sign-in" section of the module documentation for more information. The default is computed from the strategy name eg: `register_with_#{name}`. | ||
sign_in_action_name |
atom
|
The name of the action to use to sign in an existing user. Only needed if `registration_enabled?` is `false`. Because we don't know the response format of the server, you must implement your own sign-in action of the same name. See the "Registration and Sign-in" section of the module documentation for more information. The default is computed from the strategy name, eg: `sign_in_with_#{name}`. | ||
identity_resource |
module | false
|
false
|
The resource used to store user identities. Given that a user can be signed into multiple different authentication providers at once we use the `AshAuthentication.UserIdentity` resource to build a mapping between users, providers and that provider's uid. See the Identities section of the module documentation for more information. Set to `false` to disable. | |
identity_relationship_name |
atom
|
:identities
|
Name of the relationship to the provider identities resource | |
identity_relationship_user_id_attribute |
atom
|
:user_id
|
The name of the destination (user_id) attribute on your provider identity resource. The only reason to change this would be if you changed the `user_id_attribute_name` option of the provider identity. | |
icon |
atom
|
:oauth2
|
The name of an icon to use in any potential UI. This is a *hint* for UI generators to use, and not in any way canonical. | |
openid_configuration_uri |
String.t
|
"/.well-known/openid-configuration"
|
The URI for the OpenID provider | |
client_authentication_method |
:client_secret_basic | :client_secret_post | :client_secret_jwt | :private_key_jwt
|
:client_secret_basic
|
The client authentication method to use. | |
openid_configuration |
map
|
%{}
|
The OpenID configuration. If not set, the configuration will be retrieved from `openid_configuration_uri`. | |
id_token_signed_response_alg |
"HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS512" | "ES256" | "ES384" | "ES512" | "PS256" | "PS384" | "PS512" | "Ed25519" | "Ed25519ph" | "Ed448" | "Ed448ph" | "EdDSA"
|
"RS256"
|
The `id_token_signed_response_alg` parameter sent by the Client during Registration. | |
id_token_ttl_seconds |
nil | pos_integer
|
The number of seconds from `iat` that an ID Token will be considered valid. | ||
nonce |
boolean | (any, any -> any) | module | String.t
|
true
|
A function for generating the session nonce. When set to `true` the nonce will be automatically generated using `AshAuthentication.Strategy.Oidc.NonceGenerator`. Set to `false` to explicitly disable. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. See the module documentation for `AshAuthentication.Secret` for more information. Example: ```elixir nonce fn _, _ -> 16 |> :crypto.strong_rand_bytes() |> Base.encode64(padding: false) end ``` | |
trusted_audiences |
nil | list(String.t)
|
A list of audiences which are trusted. |