<!--
This file was generated by Spark. Do not edit it by hand.
-->
# DSL: AshAuthentication.Strategy.OAuth2
Strategy for authenticating using any OAuth 2.0 server as the source of truth.
This authentication strategy provides registration and sign-in for users using a
remote [OAuth 2.0](https://oauth.net/2/) server as the source of truth. You
will be required to provide either a "register" or a "sign-in" action depending
on your configuration, which the strategy will attempt to validate for common
misconfigurations.
This strategy wraps the excellent [`assent`](https://hex.pm/packages/assent)
package, which provides OAuth 2.0 capabilities.
In order to use OAuth 2.0 authentication on your resource, it needs to meet
the following minimum criteria:
1. Have a primary key.
2. Provide a strategy-specific action, either register or sign-in.
3. Provide configuration for OAuth2 destinations, secrets, etc.
### Example:
```elixir
defmodule MyApp.Accounts.User do
use Ash.Resource,
extensions: [AshAuthentication],
domain: MyApp.Accounts
attributes do
uuid_primary_key :id
attribute :email, :ci_string, allow_nil?: false
end
authentication do
strategies do
oauth2 :example do
client_id "OAuth Client ID"
redirect_uri "https://my.app/"
client_secret "My Super Secret Secret"
site "https://auth.example.com/"
end
end
end
end
```
## Secrets and runtime configuration
In order to use OAuth 2.0 you need to provide a varying number of secrets and
other configuration which may change based on runtime environment. The
`AshAuthentication.Secret` behaviour is provided to accommodate this. This
allows you to provide configuration either directly on the resource (ie as a
string), as an anonymous function, or as a module.
> ### Warning {: .warning}
>
> We **strongly** urge you not to share actual secrets in your code or
> repository.
### Examples:
Providing configuration as an anonymous function:
```elixir
oauth2 do
client_secret fn _path, resource ->
Application.fetch_env(:my_app, resource, :oauth2_client_secret)
end
end
```
Providing configuration as a module:
```elixir
defmodule MyApp.Secrets do
use AshAuthentication.Secret
def secret_for([:authentication, :strategies, :example, :client_secret], MyApp.User, _opts), do: Application.fetch_env(:my_app, :oauth2_client_secret)
end
# and in your strategies:
oauth2 :example do
client_secret MyApp.Secrets
end
```
## User identities
Because your users can be signed in via multiple providers at once, you can
specify an `identity_resource` in the DSL configuration which points to a
seperate Ash resource which has the `AshAuthentication.UserIdentity` extension
present. This resource will be used to store details of the providers in use
by each user and a relationship will be added to the user resource.
Setting the `identity_resource` will cause extra validations to be applied to
your resource so that changes are tracked correctly on sign-in or
registration.
## Actions
When using an OAuth 2.0 provider you need to declare either a "register" or
"sign-in" action. The reason for this is that it's not possible for us to
know ahead of time how you want to manage the link between your user resources
and the "user info" provided by the OAuth server.
Both actions receive the following two arguments:
1. `user_info` - a map with string keys containing the [OpenID Successful
UserInfo
response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse).
Usually this will be used to populate your email, nickname or other
identifying field.
2. `oauth_tokens` a map with string keys containing the [OpenID Successful
Token
response](https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse)
(or similar).
The actions themselves can be interacted with directly via the
`AshAuthentication.Strategy` protocol, but you are more likely to interact
with them via the web/plugs.
### Sign-in
The sign-in action is called when a successful OAuth2 callback is received.
You should use it to constrain the query to the correct user based on the
arguments provided.
This action is only needed when the `registration_enabled?` DSL settings is
set to `false`.
### Registration
The register action is a little more complicated than the sign-in action,
because we cannot tell the difference between a new user and a returning user
(they all use the same OAuth flow). In order to handle this your register
action must be defined as an upsert with a configured `upsert_identity` (see
example below).
### Examples:
Providing sign-in to users who already exist in the database (and by extension
rejecting new users):
```elixir
defmodule MyApp.Accounts.User do
attributes do
uuid_primary_key :id
attribute :email, :ci_string, allow_nil?: false
end
actions do
read :sign_in_with_example do
argument :user_info, :map, allow_nil?: false
argument :oauth_tokens, :map, allow_nil?: false
prepare AshAuthentication.Strategy.OAuth2.SignInPreparation
filter expr(email == get_path(^arg(:user_info), [:email]))
end
end
authentication do
strategies do
oauth2 :example do
registration_enabled? false
end
end
end
end
```
Providing registration or sign-in to all comers:
```elixir
defmodule MyApp.Accounts.User do
attributes do
uuid_primary_key :id
attribute :email, :ci_string, allow_nil?: false
end
actions do
create :register_with_oauth2 do
argument :user_info, :map, allow_nil?: false
argument :oauth_tokens, :map, allow_nil?: false
upsert? true
upsert_identity :email
change AshAuthentication.GenerateTokenChange
change fn changeset, _ctx ->
user_info = Ash.Changeset.get_argument(changeset, :user_info)
changeset
|> Ash.Changeset.change_attribute(:email, user_info["email"])
end
end
end
authentication do
strategies do
oauth2 :example do
end
end
end
end
```
## Plugs
OAuth 2.0 is (usually) a browser-based flow. This means that you're most
likely to interact with this strategy via it's plugs. There are two phases to
authentication with OAuth 2.0:
1. The request phase, where the user's browser is redirected to the remote
authentication provider for authentication.
2. The callback phase, where the provider redirects the user back to your app
to create a local database record, session, etc.
## authentication.strategies.oauth2
```elixir
oauth2 name \\ :oauth2
```
OAuth2 authentication
### Arguments
| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#authentication-strategies-oauth2-name){: #authentication-strategies-oauth2-name .spark-required} | `atom` | | Uniquely identifies the strategy. |
### Options
| Name | Type | Default | Docs |
|------|------|---------|------|
| [`client_id`](#authentication-strategies-oauth2-client_id){: #authentication-strategies-oauth2-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. |
| [`authorize_url`](#authentication-strategies-oauth2-authorize_url){: #authentication-strategies-oauth2-authorize_url .spark-required} | `(any, any -> any) \| module \| String.t` | | The API url to the OAuth2 authorize endpoint, relative to `site`, e.g `authorize_url fn _, _ -> {:ok, "https://exampe.com/authorize"} end`. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
| [`token_url`](#authentication-strategies-oauth2-token_url){: #authentication-strategies-oauth2-token_url .spark-required} | `(any, any -> any) \| module \| String.t` | | The API url to access the token endpoint, relative to `site`, e.g `token_url fn _, _ -> {:ok, "https://example.com/oauth_token"} end`. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
| [`user_url`](#authentication-strategies-oauth2-user_url){: #authentication-strategies-oauth2-user_url .spark-required} | `(any, any -> any) \| module \| String.t` | | The API url to access the user endpoint, relative to `site`, e.g `user_url fn _, _ -> {:ok, "https://example.com/userinfo"} end`. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
| [`redirect_uri`](#authentication-strategies-oauth2-redirect_uri){: #authentication-strategies-oauth2-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. |
| [`base_url`](#authentication-strategies-oauth2-base_url){: #authentication-strategies-oauth2-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. |
| [`site`](#authentication-strategies-oauth2-site){: #authentication-strategies-oauth2-site } | `(any, any -> any) \| module \| String.t` | | Deprecated: Use `base_url` instead. |
| [`auth_method`](#authentication-strategies-oauth2-auth_method){: #authentication-strategies-oauth2-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-oauth2-client_secret){: #authentication-strategies-oauth2-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-oauth2-trusted_audiences){: #authentication-strategies-oauth2-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-oauth2-private_key){: #authentication-strategies-oauth2-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. |
| [`authorization_params`](#authentication-strategies-oauth2-authorization_params){: #authentication-strategies-oauth2-authorization_params } | `keyword` | `[]` | Any additional parameters to encode in the request phase. eg: `authorization_params scope: "openid profile email"` |
| [`registration_enabled?`](#authentication-strategies-oauth2-registration_enabled?){: #authentication-strategies-oauth2-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-oauth2-register_action_name){: #authentication-strategies-oauth2-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-oauth2-sign_in_action_name){: #authentication-strategies-oauth2-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-oauth2-identity_resource){: #authentication-strategies-oauth2-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`](#authentication-strategies-oauth2-identity_relationship_name){: #authentication-strategies-oauth2-identity_relationship_name } | `atom` | `:identities` | Name of the relationship to the provider identities resource |
| [`identity_relationship_user_id_attribute`](#authentication-strategies-oauth2-identity_relationship_user_id_attribute){: #authentication-strategies-oauth2-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. |
| [`icon`](#authentication-strategies-oauth2-icon){: #authentication-strategies-oauth2-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. |
### Introspection
Target: `AshAuthentication.Strategy.OAuth2`
<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>