<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshAuthentication.Strategy.Oidc

Strategy for authentication using an [OpenID
Connect](https://openid.net/connect/) compatible server as the source of
truth.

This strategy builds on-top of `AshAuthentication.Strategy.OAuth2` and
[`assent`](https://hex.pm/packages/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:

```elixir
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:
- The [OAuth2 documentation](`AshAuthentication.Strategy.OAuth2`)


### authentication.strategies.oidc
```elixir
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:
- The [OAuth2 documentation](`AshAuthentication.Strategy.OAuth2`)


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#authentication-strategies-oidc-name){: #authentication-strategies-oidc-name .spark-required} | `atom` |  | Uniquely identifies the strategy. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`client_id`](#authentication-strategies-oidc-client_id){: #authentication-strategies-oidc-client_id .spark-required} | `(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`](#authentication-strategies-oidc-base_url){: #authentication-strategies-oidc-base_url .spark-required} | `(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`](#authentication-strategies-oidc-redirect_uri){: #authentication-strategies-oidc-redirect_uri .spark-required} | `(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`](#authentication-strategies-oidc-site){: #authentication-strategies-oidc-site } | `(any, any -> any) \| module \| String.t` |  | Deprecated: Use `base_url` instead. |
| [`prevent_hijacking?`](#authentication-strategies-oidc-prevent_hijacking?){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-auth_method){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-client_secret){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-trusted_audiences){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-private_key){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-code_verifier){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-authorization_params){: #authentication-strategies-oidc-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?`](#authentication-strategies-oidc-registration_enabled?){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-register_action_name){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-sign_in_action_name){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-identity_resource){: #authentication-strategies-oidc-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. |
| [`warn_on_missing_identity_resource?`](#authentication-strategies-oidc-warn_on_missing_identity_resource?){: #authentication-strategies-oidc-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. |
| [`trust_email_verified?`](#authentication-strategies-oidc-trust_email_verified?){: #authentication-strategies-oidc-trust_email_verified? } | `boolean` | `false` | 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. 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`](#authentication-strategies-oidc-on_untrusted_email_match){: #authentication-strategies-oidc-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?`). `: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`](#authentication-strategies-oidc-identity_relationship_name){: #authentication-strategies-oidc-identity_relationship_name } | `atom` | `:identities` | Name of the relationship to the provider identities resource |
| [`identity_relationship_user_id_attribute`](#authentication-strategies-oidc-identity_relationship_user_id_attribute){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-openid_configuration_uri){: #authentication-strategies-oidc-openid_configuration_uri } | `(any, any -> any) \| module \| String.t` | `"/.well-known/openid-configuration"` | The URI for the OpenID provider |
| [`client_authentication_method`](#authentication-strategies-oidc-client_authentication_method){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-openid_configuration){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-id_token_signed_response_alg){: #authentication-strategies-oidc-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`](#authentication-strategies-oidc-id_token_ttl_seconds){: #authentication-strategies-oidc-id_token_ttl_seconds } | `nil \| pos_integer` |  | The number of seconds from `iat` that an ID Token will be considered valid. |
| [`nonce`](#authentication-strategies-oidc-nonce){: #authentication-strategies-oidc-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. |


### Introspection

Target: `AshAuthentication.Strategy.OAuth2`


<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>