mirror of
https://github.com/team-alembic/ash_authentication.git
synced 2024-09-20 13:24:20 +12:00
98ee7a341b
* chore(deps): bump spark from 1.1.43 to 1.1.44 Bumps [spark](https://github.com/ash-project/spark) from 1.1.43 to 1.1.44. - [Changelog](https://github.com/ash-project/spark/blob/main/CHANGELOG.md) - [Commits](https://github.com/ash-project/spark/compare/v1.1.43...v1.1.44) --- updated-dependencies: - dependency-name: spark dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> * docs: Update DSL cheat sheets. --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: James Harton <james@harton.nz>
996 lines
27 KiB
Text
996 lines
27 KiB
Text
<!--
|
|
This file was generated by Spark. Do not edit it by hand.
|
|
-->
|
|
# DSL: AshAuthentication.Strategy.OAuth2
|
|
|
|
Strategy for authenticating using an OAuth 2.0 server as the source of truth.
|
|
|
|
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]
|
|
|
|
attributes do
|
|
uuid_primary_key :id
|
|
attribute :email, :ci_string, allow_nil?: false
|
|
end
|
|
|
|
authentication do
|
|
api MyApp.Accounts
|
|
|
|
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
|
|
```
|
|
|
|
## 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
|
|
api MyApp.Accounts
|
|
|
|
strategies do
|
|
oauth2 :example do
|
|
registration_enabled? false
|
|
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
|
|
|> Changeset.change_attribute(:email, user_info["email"])
|
|
end
|
|
end
|
|
end
|
|
|
|
authentication do
|
|
api MyApp.Accounts
|
|
|
|
strategies do
|
|
oauth2 :example do
|
|
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.
|
|
|
|
|
|
## DSL Documentation
|
|
|
|
OAuth2 authentication
|
|
|
|
|
|
|
|
|
|
|
|
* `:name` (`t:atom/0`) - Required. Uniquely identifies the strategy.
|
|
|
|
* `:client_id` - Required. The OAuth2 client ID.
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
Example:
|
|
```elixir
|
|
client_id fn _, resource ->
|
|
:my_app
|
|
|> Application.get_env(resource, [])
|
|
|> Keyword.fetch(:oauth_client_id)
|
|
end
|
|
```
|
|
|
|
* `:site` - Required. 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.
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
Example:
|
|
```elixir
|
|
site fn _, resource ->
|
|
:my_app
|
|
|> Application.get_env(resource, [])
|
|
|> Keyword.fetch(:oauth_site)
|
|
end
|
|
```
|
|
|
|
* `:auth_method` - The authentication strategy used, optional. If not set, no
|
|
authentication will be used during the access token request. The
|
|
value may be one of the following:
|
|
* `:client_secret_basic`
|
|
* `:client_secret_post`
|
|
* `:client_secret_jwt`
|
|
* `:private_key_jwt`
|
|
Valid values are nil, :client_secret_basic, :client_secret_post, :client_secret_jwt, :private_key_jwt The default value is `:client_secret_post`.
|
|
|
|
* `:client_secret` - 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.
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
Example:
|
|
```elixir
|
|
site fn _, resource ->
|
|
:my_app
|
|
|> Application.get_env(resource, [])
|
|
|> Keyword.fetch(:oauth_site)
|
|
end
|
|
```
|
|
|
|
* `:authorize_url` - Required. The API url to the OAuth2 authorize endpoint.
|
|
Relative to the value of `site`.
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
Example:
|
|
```elixir
|
|
authorize_url fn _, _ -> {:ok, "https://exampe.com/authorize"} end
|
|
```
|
|
|
|
* `:token_url` - Required. The API url to access the token endpoint.
|
|
Relative to the value of `site`.
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
Example:
|
|
```elixir
|
|
token_url fn _, _ -> {:ok, "https://example.com/oauth_token"} end
|
|
```
|
|
|
|
* `:user_url` - Required. The API url to access the user endpoint.
|
|
Relative to the value of `site`.
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
Example:
|
|
```elixir
|
|
user_url fn _, _ -> {:ok, "https://example.com/userinfo"} end
|
|
```
|
|
|
|
* `:private_key` - 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.
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
* `:redirect_uri` - Required. The callback URI base.
|
|
Not the whole URI back to the callback endpoint, but the URI to your
|
|
`AuthPlug`. We can generate the rest.
|
|
Whilst not particularly secret, it seemed prudent to allow this to be
|
|
configured dynamically so that you can use different URIs for
|
|
different environments.
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
* `:authorization_params` (`t:keyword/0`) - Any additional parameters to encode in the request phase.
|
|
eg: `authorization_params scope: "openid profile email"` The default value is `[]`.
|
|
|
|
* `:registration_enabled?` (`t:boolean/0`) - Is registration enabled for this provider?
|
|
If this option is enabled, then new users will be able to register for
|
|
your site when authenticating and not already present.
|
|
If not, then only existing users will be able to authenticate. The default value is `true`.
|
|
|
|
* `:register_action_name` (`t:atom/0`) - The name of the action to use to register a user.
|
|
Only needed if `registration_enabled?` is `true`.
|
|
Because we we don't know the response format of the server, you must
|
|
implement your own registration action of the same name.
|
|
See the "Registration and Sign-in" section of the module
|
|
documentation for more information.
|
|
The default is computed from the strategy name eg:
|
|
`register_with_#{name}`.
|
|
|
|
* `:sign_in_action_name` (`t:atom/0`) - The name of the action to use to sign in an existing user.
|
|
Only needed if `registration_enabled?` is `false`.
|
|
Because we don't know the response format of the server, you must
|
|
implement your own sign-in action of the same name.
|
|
See the "Registration and Sign-in" section of the module
|
|
documentation for more information.
|
|
The default is computed from the strategy name, eg:
|
|
`sign_in_with_#{name}`.
|
|
|
|
* `:identity_resource` - The resource used to store user identities.
|
|
Given that a user can be signed into multiple different
|
|
authentication providers at once we use the
|
|
`AshAuthentication.UserIdentity` resource to build a mapping
|
|
between users, providers and that provider's uid.
|
|
See the Identities section of the module documentation for more
|
|
information.
|
|
Set to `false` to disable. The default value is `false`.
|
|
|
|
* `:identity_relationship_name` (`t:atom/0`) - Name of the relationship to the provider identities resource The default value is `:identities`.
|
|
|
|
* `:identity_relationship_user_id_attribute` (`t:atom/0`) - The name of the destination (user_id) attribute on your provider
|
|
identity resource.
|
|
The only reason to change this would be if you changed the
|
|
`user_id_attribute_name` option of the provider identity. The default value is `:user_id`.
|
|
|
|
* `:icon` (`t:atom/0`) - 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. The default value is `:oauth2`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## authentication.strategies.oauth2
|
|
```elixir
|
|
oauth2 name \ :oauth2
|
|
```
|
|
|
|
|
|
OAuth2 authentication
|
|
|
|
|
|
|
|
|
|
|
|
### Arguments
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Default</th>
|
|
<th colspan=2>Docs</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-name" href="#authentication-strategies-oauth2-name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
name
|
|
</span>
|
|
</a>
|
|
<sup style="color: red">*</sup>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
Uniquely identifies the strategy.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
</tbody>
|
|
</table>
|
|
### Options
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Default</th>
|
|
<th colspan=2>Docs</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-client_id" href="#authentication-strategies-oauth2-client_id">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
client_id
|
|
</span>
|
|
</a>
|
|
<sup style="color: red">*</sup>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">(any, any -> any) | module | String.t</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The OAuth2 client ID.
|
|
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
|
|
Example:
|
|
|
|
```elixir
|
|
client_id fn _, resource ->
|
|
:my_app
|
|
|> Application.get_env(resource, [])
|
|
|> Keyword.fetch(:oauth_client_id)
|
|
end
|
|
```
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-site" href="#authentication-strategies-oauth2-site">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
site
|
|
</span>
|
|
</a>
|
|
<sup style="color: red">*</sup>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">(any, any -> any) | module | String.t</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
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.
|
|
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
|
|
Example:
|
|
|
|
```elixir
|
|
site fn _, resource ->
|
|
:my_app
|
|
|> Application.get_env(resource, [])
|
|
|> Keyword.fetch(:oauth_site)
|
|
end
|
|
```
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-authorize_url" href="#authentication-strategies-oauth2-authorize_url">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
authorize_url
|
|
</span>
|
|
</a>
|
|
<sup style="color: red">*</sup>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">(any, any -> any) | module | String.t</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The API url to the OAuth2 authorize endpoint.
|
|
|
|
Relative to the value of `site`.
|
|
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
|
|
Example:
|
|
|
|
```elixir
|
|
authorize_url fn _, _ -> {:ok, "https://exampe.com/authorize"} end
|
|
```
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-token_url" href="#authentication-strategies-oauth2-token_url">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
token_url
|
|
</span>
|
|
</a>
|
|
<sup style="color: red">*</sup>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">(any, any -> any) | module | String.t</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The API url to access the token endpoint.
|
|
|
|
Relative to the value of `site`.
|
|
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
|
|
Example:
|
|
|
|
```elixir
|
|
token_url fn _, _ -> {:ok, "https://example.com/oauth_token"} end
|
|
```
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-user_url" href="#authentication-strategies-oauth2-user_url">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
user_url
|
|
</span>
|
|
</a>
|
|
<sup style="color: red">*</sup>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">(any, any -> any) | module | String.t</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The API url to access the user endpoint.
|
|
|
|
Relative to the value of `site`.
|
|
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
|
|
Example:
|
|
|
|
```elixir
|
|
user_url fn _, _ -> {:ok, "https://example.com/userinfo"} end
|
|
```
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-redirect_uri" href="#authentication-strategies-oauth2-redirect_uri">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
redirect_uri
|
|
</span>
|
|
</a>
|
|
<sup style="color: red">*</sup>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">(any, any -> any) | module | String.t</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The callback URI base.
|
|
|
|
Not the whole URI back to the callback endpoint, but the URI to your
|
|
`AuthPlug`. We can generate the rest.
|
|
|
|
Whilst not particularly secret, it seemed prudent to allow this to be
|
|
configured dynamically so that you can use different URIs for
|
|
different environments.
|
|
|
|
Takes either a module which implements the `AshAuthentication.Secret`
|
|
behaviour, a 2 arity anonymous function or a string.
|
|
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-auth_method" href="#authentication-strategies-oauth2-auth_method">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
auth_method
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">nil | :client_secret_basic | :client_secret_post | :client_secret_jwt | :private_key_jwt</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:client_secret_post</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The authentication strategy used, optional. If not set, no
|
|
authentication will be used during the access token request. The
|
|
value may be one of the following:
|
|
|
|
* `:client_secret_basic`
|
|
* `:client_secret_post`
|
|
* `:client_secret_jwt`
|
|
* `:private_key_jwt`
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-client_secret" href="#authentication-strategies-oauth2-client_secret">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
client_secret
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">(any, any -> any) | module | String.t</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
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.
|
|
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
|
|
Example:
|
|
|
|
```elixir
|
|
site fn _, resource ->
|
|
:my_app
|
|
|> Application.get_env(resource, [])
|
|
|> Keyword.fetch(:oauth_site)
|
|
end
|
|
```
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-private_key" href="#authentication-strategies-oauth2-private_key">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
private_key
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">(any, any -> any) | module | String.t</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
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.
|
|
|
|
See the module documentation for `AshAuthentication.Secret` for more
|
|
information.
|
|
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-authorization_params" href="#authentication-strategies-oauth2-authorization_params">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
authorization_params
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">Keyword.t</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">[]</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
Any additional parameters to encode in the request phase.
|
|
|
|
eg: `authorization_params scope: "openid profile email"`
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-registration_enabled?" href="#authentication-strategies-oauth2-registration_enabled?">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
registration_enabled?
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">boolean</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">true</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
Is registration enabled for this provider?
|
|
|
|
If this option is enabled, then new users will be able to register for
|
|
your site when authenticating and not already present.
|
|
|
|
If not, then only existing users will be able to authenticate.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-register_action_name" href="#authentication-strategies-oauth2-register_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
register_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the action to use to register a user.
|
|
|
|
Only needed if `registration_enabled?` is `true`.
|
|
|
|
Because we we don't know the response format of the server, you must
|
|
implement your own registration action of the same name.
|
|
|
|
See the "Registration and Sign-in" section of the module
|
|
documentation for more information.
|
|
|
|
The default is computed from the strategy name eg:
|
|
`register_with_#{name}`.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-sign_in_action_name" href="#authentication-strategies-oauth2-sign_in_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
sign_in_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the action to use to sign in an existing user.
|
|
|
|
Only needed if `registration_enabled?` is `false`.
|
|
|
|
Because we don't know the response format of the server, you must
|
|
implement your own sign-in action of the same name.
|
|
|
|
See the "Registration and Sign-in" section of the module
|
|
documentation for more information.
|
|
|
|
The default is computed from the strategy name, eg:
|
|
`sign_in_with_#{name}`.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-identity_resource" href="#authentication-strategies-oauth2-identity_resource">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
identity_resource
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">module | false</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">false</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The resource used to store user identities.
|
|
|
|
Given that a user can be signed into multiple different
|
|
authentication providers at once we use the
|
|
`AshAuthentication.UserIdentity` resource to build a mapping
|
|
between users, providers and that provider's uid.
|
|
|
|
See the Identities section of the module documentation for more
|
|
information.
|
|
|
|
Set to `false` to disable.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-identity_relationship_name" href="#authentication-strategies-oauth2-identity_relationship_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
identity_relationship_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:identities</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
Name of the relationship to the provider identities resource
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-identity_relationship_user_id_attribute" href="#authentication-strategies-oauth2-identity_relationship_user_id_attribute">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
identity_relationship_user_id_attribute
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:user_id</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the destination (user_id) attribute on your provider
|
|
identity resource.
|
|
|
|
The only reason to change this would be if you changed the
|
|
`user_id_attribute_name` option of the provider identity.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="authentication-strategies-oauth2-icon" href="#authentication-strategies-oauth2-icon">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
icon
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:oauth2</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
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.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
|
### Introspection
|
|
|
|
Target: `AshAuthentication.Strategy.OAuth2`
|
|
|
|
|