Strategy for authenticating using Apple Sign In
This strategy builds on-top of AshAuthentication.Strategy.Oidc and
assent.
In order to use Apple Sign In you need to provide the following minimum configuration:
client_idteam_idprivate_key_idprivate_key_pathorprivate_keyredirect_uri
More documentation:
authentication.strategies.apple
apple name \\ :appleProvides a pre-configured authentication strategy for Apple Sign In.
This strategy is built using the :oidc strategy, and thus provides all the same
configuration options should you need them.
More documentation:
Strategy defaults:
The following defaults are applied:
:base_urlis set to"https://appleid.apple.com".:openid_configurationis set to%{"authorization_endpoint" => "https://appleid.apple.com/auth/authorize", "issuer" => "https://appleid.apple.com", "jwks_uri" => "https://appleid.apple.com/auth/keys", "token_endpoint" => "https://appleid.apple.com/auth/token", "token_endpoint_auth_methods_supported" => ["client_secret_post"]}.:authorization_paramsis set to[scope: "email", response_mode: "form_post"].:client_authentication_methodis set to"client_secret_post".:openid_default_scopeis set tonil.
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. | |
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. | |
team_id | (any, any -> any) | module | String.t | The Apple team ID associated with the application. | |
private_key_id | (any, any -> any) | module | String.t | The private key ID used for signing the JWT token. | |
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. |
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 |
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. 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. |
idp_initiated_login? | boolean | false | If enabled, a callback arriving with no stored session (an IdP/third-party-initiated login, e.g. an identity provider's app-launcher or portal tile, that omits state) is treated as a trigger to restart authentication rather than completed directly. The plug discards the inbound response and redirects into the request phase, where a fresh state is generated and later verified — the OpenID Connect Core §4 ("Initiating Login from a Third Party") pattern. This keeps CSRF state verification intact for all flows. Only callbacks that carry no state parameter are restarted — one bearing state came from a request phase that already ran, so it fails closed rather than bouncing again. Requires the user to still have a live session at the provider so the restarted flow returns immediately. Defaults to false (stateless callbacks fail closed). |
warn_on_missing_identity_resource? | boolean | true | Whether 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. |
email_field | atom | :email | The name of the attribute which holds the user's email address. Read only by the sign-in action (registration_enabled? false), where it names the value the provider's verified email must equal before the sign-in attaches to the account the action's filter matched. The register action needs no such setting: it attaches only when the verified email is one of the upsert_identity values that matched, which is evidence of the same fact. The sign-in action's filter matches on values the strategy never sees, so the attribute must be named here. The action must also select it - an email the action leaves unselected reads as absent and the sign-in is refused. Set trust_email_verified? false on a resource that stores no email address. |
trust_email_verified? | boolean | true | Whether 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. The claim alone is not enough, because a verified email attests ownership of that address and nothing else. The register action attaches only when its upsert_identity matched the account by the verified email, so an action keyed on a username or another provider claim never auto-attaches. The sign-in action attaches only when the verified email equals the account's email_field. On the register action, on_untrusted_email_match :confirm offers the sign-ins that no longer attach a linking path; the sign-in action has no such path and refuses them. 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 | :reject | What 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?). Read by the register action only; a sign-in action always refuses. :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_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. |
client_secret | (any, any -> any) | module | String.t | The OAuth2 client secret. Required if :client_authentication_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. | |
openid_configuration_uri | (any, any -> any) | module | String.t | "/.well-known/openid-configuration" | The URI for the OpenID provider |
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. | |
trusted_audiences | (any, any -> any) | module | list(any) | nil | A list of audiences which are trusted, in addition to client_id. Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string. | |
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. |
private_key_path | (any, any -> any) | module | String.t | The path to the private key file used for signing the JWT token. Required if private_key is not set. |