AshAuthentication.Strategy.Oidc

Copy Markdown View Source

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, required
  • site - The OIDC issuer, required
  • openid_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 to client_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 defined
  • id_token_signed_response_alg - The id_token_signed_response_alg parameter sent by the Client during Registration, defaults to RS256
  • id_token_ttl_seconds - The number of seconds from iat that an ID Token will be considered valid, optional, defaults to nil
  • nonce - 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.

More documentation:

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.

More documentation:

Arguments

NameTypeDefaultDocs
nameatomUniquely identifies the strategy.

Options

NameTypeDefaultDocs
client_id(any, any -> any) | module | String.tThe OAuth2 client ID. Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string.
base_url(any, any -> any) | module | String.tThe 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.
redirect_uri(any, any -> any) | module | String.tThe callback URI base. Not the whole URI back to the callback endpoint, but the URI to your AuthPlug. Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string.
site(any, any -> any) | module | String.tDeprecated: Use base_url instead.
prevent_hijacking?booleantrueRequires a confirmation add_on to be present if the password strategy is used with the same identity_field.
auth_methodnil | :client_secret_basic | :client_secret_post | :client_secret_jwt | :private_key_jwt:client_secret_postThe authentication strategy used, optional. If not set, no authentication will be used during the access token request.
client_secret(any, any -> any) | module | String.tThe 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.
trusted_audiences(any, any -> any) | module | list(any) | nilA list of audiences which are trusted. Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string.
private_key(any, any -> any) | module | String.tThe 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.
code_verifierbooleanfalseBoolean to generate and use a random 128 byte long url safe code verifier for PKCE flow, optional, defaults to false. When set to true the session params will contain :code_verifier, :code_challenge, and :code_challenge_method params
authorization_params(any, any -> any) | module | keyword | nil[]Any additional parameters to encode in the request phase. eg: authorization_params scope: "openid profile email"
registration_enabled?booleantrueIf enabled, new users will be able to register for your site when authenticating and not already present. If not, only existing users will be able to authenticate.
register_action_nameatomThe name of the action to use to register a user, if registration_enabled? is true. Defaults to register_with_<name> See the "Registration and Sign-in" section of the strategy docs for more.
sign_in_action_nameatomThe name of the action to use to sign in an existing user, if sign_in_enabled? is true. Defaults to sign_in_with_<strategy>, which is generated for you by default. See the "Registration and Sign-in" section of the strategy docs for more information.
identity_resourcemodule | falsefalseThe resource used to store user identities. Required: matching users by email or other provider claims is unsafe, so the provider's iss/sub claims must be persisted. See the User Identities section of the strategy docs for more.
warn_on_missing_identity_resource?booleantrueWhether to emit a compile-time warning when no identity_resource is configured. Set to false only when you have deliberately chosen not to use an identity resource and accept that users are matched by provider claims such as email, which is unsafe and will become unsupported in a future release.
trust_email_verified?booleanfalseWhether the provider's email_verified claim can be trusted to attach an OAuth2 sign-in to a pre-existing local account with the same email. Only enable this for providers that reliably assert email ownership. When false, a sign-in whose iss/sub is not yet known will never be matched to an existing account by email.
on_untrusted_email_match:reject | :confirm:rejectWhat to do when a new iss/sub presents an email matching an existing account but the email can't be trusted (see trust_email_verified?). :reject (the default) refuses the sign-in. :confirm issues a confirmation to the existing account's email and links the provider only once the recipient proves ownership; requires a confirmation add-on. Note: confirming binds whatever provider identity initiated the flow, so the confirmation email must make clear which provider is being linked - otherwise a user can be tricked into linking an attacker's provider account.
identity_relationship_nameatom:identitiesName of the relationship to the provider identities resource
identity_relationship_user_id_attributeatom:user_idThe name of the destination (user_id) attribute on your provider identity resource. Only necessary if you've changed the user_id_attribute_name option of the provider identity.
openid_configuration_uri(any, any -> any) | module | 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" | "none""client_secret_basic"The client authentication method to use.
openid_configurationnil | %{optional(String.t) => any}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_secondsnil | pos_integerThe number of seconds from iat that an ID Token will be considered valid.
nonceboolean | (any, any -> any) | module | String.ttrueA function for generating the session nonce, true to automatically generate it with AshAuthentication.Strategy.Oidc.NonceGenerator, or false to disable.

Introspection

Target: AshAuthentication.Strategy.OAuth2