Strategy for authenticating using Okta.
This strategy builds on-top of AshAuthentication.Strategy.Oidc and
assent, and uses Okta's OpenID Connect
discovery endpoint to retrieve token, authorization, and user info URLs.
In order to use Okta you need to provide the following minimum configuration:
client_idclient_secretredirect_uribase_url- your Okta authorization server, typicallyhttps://YOUR_OKTA_DOMAIN/oauth2/default(the built-indefaultCustom Authorization Server).
Choosing a base_url
Okta exposes two kinds of authorization servers:
- Custom Authorization Server (recommended) — issuer
https://YOUR_OKTA_DOMAIN/oauth2/{authServerId}. Every Okta org ships with one nameddefault. - Org Authorization Server — issuer
https://YOUR_OKTA_DOMAIN. Only suitable for a small number of Okta-internal use cases.
If you're not sure, use the default Custom Authorization Server.
More documentation:
- The Okta Tutorial — covers groups
claims, step-up / MFA via
acr_values, and Org vs Custom server choice in depth. - The Okta OpenID Connect Overview.
- The OIDC documentation.
authentication.strategies.okta
okta name \\ :oktaProvides a pre-configured authentication strategy for Okta.
This strategy is built using the :oidc strategy, and automatically
retrieves configuration from Okta's discovery endpoint
({base_url}/.well-known/openid-configuration).
Set base_url to your Okta authorization server. For most installations
that's https://YOUR_OKTA_DOMAIN/oauth2/default (the built-in default
Custom Authorization Server).
More documentation:
Strategy defaults:
The following defaults are applied:
:authorization_paramsis set to[scope: "profile email"].
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. | |
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. | |
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. Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string. | |
site | (any, any -> any) | module | String.t | Deprecated: Use base_url instead. | |
prevent_hijacking? | boolean | true | Requires a confirmation add_on to be present if the password strategy is used with the same identity_field. |
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. |
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. | |
trusted_audiences | (any, any -> any) | module | list(any) | nil | A 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.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. | |
code_verifier | boolean | false | Boolean 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 | [scope: "profile email"] | Any additional parameters to encode in the request phase. eg: authorization_params scope: "openid profile email" |
registration_enabled? | boolean | true | If 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_name | atom | The 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_name | atom | The 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_resource | module | false | false | The resource used to store user identities, or false to disable. See the User Identities section of the strategy docs for more. |
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. 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_configuration | nil | %{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_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, true to automatically generate it with AshAuthentication.Strategy.Oidc.NonceGenerator, or false to disable. |