2023-09-27 16:42:46 +13:00
|
|
|
<!--
|
|
|
|
This file was generated by Spark. Do not edit it by hand.
|
|
|
|
-->
|
2023-09-22 10:20:50 +12:00
|
|
|
# DSL: AshAuthentication
|
|
|
|
|
|
|
|
AshAuthentication provides a turn-key authentication solution for folks using
|
|
|
|
[Ash](https://www.ash-hq.org/).
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
This package assumes that you have [Ash](https://ash-hq.org/) installed and
|
|
|
|
configured. See the Ash documentation for details.
|
|
|
|
|
|
|
|
Once installed you can easily add support for authentication by configuring
|
|
|
|
the `AshAuthentication` extension on your resource:
|
|
|
|
|
|
|
|
```elixir
|
|
|
|
defmodule MyApp.Accounts.User do
|
|
|
|
use Ash.Resource,
|
|
|
|
extensions: [AshAuthentication]
|
|
|
|
|
|
|
|
attributes do
|
|
|
|
uuid_primary_key :id
|
|
|
|
attribute :email, :ci_string, allow_nil?: false
|
|
|
|
attribute :hashed_password, :string, allow_nil?: false, sensitive?: true
|
|
|
|
end
|
|
|
|
|
|
|
|
authentication do
|
|
|
|
api MyApp.Accounts
|
|
|
|
|
|
|
|
strategies do
|
|
|
|
password :password do
|
|
|
|
identity_field :email
|
|
|
|
hashed_password_field :hashed_password
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
identities do
|
|
|
|
identity :unique_email, [:email]
|
|
|
|
end
|
|
|
|
end
|
|
|
|
```
|
|
|
|
|
|
|
|
If you plan on providing authentication via the web, then you will need to
|
|
|
|
define a plug using `AshAuthentication.Plug` which builds a `Plug.Router` that
|
|
|
|
routes incoming authentication requests to the correct provider and provides
|
|
|
|
callbacks for you to manipulate the conn after success or failure.
|
|
|
|
|
|
|
|
If you're using AshAuthentication with Phoenix, then check out
|
|
|
|
[`ash_authentication_phoenix`](https://github.com/team-alembic/ash_authentication_phoenix)
|
|
|
|
which provides route helpers, a controller abstraction and LiveView components
|
|
|
|
for easy set up.
|
|
|
|
|
|
|
|
## Authentication Strategies
|
|
|
|
|
|
|
|
Currently supported strategies:
|
|
|
|
|
|
|
|
1. `AshAuthentication.Strategy.Password`
|
|
|
|
- authenticate users against your local database using a unique identity
|
|
|
|
(such as username or email address) and a password.
|
|
|
|
2. `AshAuthentication.Strategy.OAuth2`
|
|
|
|
- authenticate using local or remote [OAuth 2.0](https://oauth.net/2/)
|
|
|
|
compatible services.
|
|
|
|
|
|
|
|
## Add-ons
|
|
|
|
|
|
|
|
Add-ons are like strategies, except that they don't actually provide
|
|
|
|
authentication - they just provide features adjacent to authentication.
|
|
|
|
Current add-ons:
|
|
|
|
|
|
|
|
1. `AshAuthentication.AddOn.Confirmation`
|
|
|
|
- allows you to force the user to confirm changes using a confirmation
|
|
|
|
token (eg. sending a confirmation email when a new user registers).
|
|
|
|
|
|
|
|
## Supervisor
|
|
|
|
|
|
|
|
Some add-ons or strategies may require processes to be started which manage
|
|
|
|
their state over the lifetime of the application (eg periodically deleting
|
|
|
|
expired token revocations). Because of this you should add
|
|
|
|
`{AshAuthentication.Supervisor, otp_app: :my_app}` to your application's
|
|
|
|
supervision tree. See [the Elixir
|
|
|
|
docs](https://hexdocs.pm/elixir/Application.html#module-the-application-callback-module)
|
|
|
|
for more information.
|
|
|
|
|
|
|
|
|
|
|
|
## authentication
|
|
|
|
Configure authentication for this resource
|
|
|
|
|
|
|
|
### Nested DSLs
|
|
|
|
* [tokens](#authentication-tokens)
|
|
|
|
* [strategies](#authentication-strategies)
|
|
|
|
* [add_ons](#authentication-add_ons)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
2023-09-27 16:42:46 +13:00
|
|
|
|
|
|
|
<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-api" href="#authentication-api">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
api
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
<sup style="color: red">*</sup>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">module</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
The name of the Ash API to use to access this resource when
|
|
|
|
doing anything authenticaiton related.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<a id="authentication-subject_name" href="#authentication-subject_name">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
subject_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 subject name is used anywhere that a short version of your
|
|
|
|
resource name is needed, eg:
|
|
|
|
|
|
|
|
- generating token claims,
|
|
|
|
- generating routes,
|
|
|
|
- form parameter nesting.
|
|
|
|
|
|
|
|
This needs to be unique system-wide and if not set will be inferred
|
|
|
|
from the resource name (ie `MyApp.Accounts.User` will have a subject
|
|
|
|
name of `user`).
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<a id="authentication-get_by_subject_action_name" href="#authentication-get_by_subject_action_name">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
get_by_subject_action_name
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">atom</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">:get_by_subject</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
The name of the read action used to retrieve records.
|
|
|
|
|
|
|
|
Used internally by `AshAuthentication.subject_to_user/2`. If the
|
|
|
|
action doesn't exist, one will be generated for you.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<a id="authentication-select_for_senders" href="#authentication-select_for_senders">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
select_for_senders
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">list(atom)</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
A list of fields that we will ensure are selected whenever a sender will be invoked.
|
|
|
|
This is useful if using something like `ash_graphql` which by default only selects
|
|
|
|
what fields appear in the query, and if you are exposing these actions that way.
|
|
|
|
Defaults to `[:email]` if there is an `:email` attribute on the resource, and `[]`
|
|
|
|
otherwise.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
</tbody>
|
|
|
|
</table>
|
2023-09-22 10:20:50 +12:00
|
|
|
|
|
|
|
|
|
|
|
## authentication.tokens
|
|
|
|
Configure JWT settings for this resource
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
2023-09-27 16:42:46 +13:00
|
|
|
|
|
|
|
<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-tokens-token_resource" href="#authentication-tokens-token_resource">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
token_resource
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
<sup style="color: red">*</sup>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">module | false</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
The resource used to store token information.
|
|
|
|
|
|
|
|
If token generation is enabled for this resource, we need a place to
|
|
|
|
store information about tokens, such as revocations and in-flight
|
|
|
|
confirmations.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<a id="authentication-tokens-enabled?" href="#authentication-tokens-enabled?">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
enabled?
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">boolean</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">false</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
Should JWTs be generated by this resource?
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<a id="authentication-tokens-store_all_tokens?" href="#authentication-tokens-store_all_tokens?">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
store_all_tokens?
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">boolean</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">false</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
Store all tokens in the `token_resource`?
|
|
|
|
|
|
|
|
Some applications need to keep track of all tokens issued to
|
|
|
|
any user. This is optional behaviour with `ash_authentication`
|
|
|
|
in order to preserve as much performance as possible.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<a id="authentication-tokens-require_token_presence_for_authentication?" href="#authentication-tokens-require_token_presence_for_authentication?">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
require_token_presence_for_authentication?
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">boolean</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">false</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
Require a locally-stored token for authentication?
|
|
|
|
|
|
|
|
This inverts the token validation behaviour from requiring that
|
|
|
|
tokens are not revoked to requiring any token presented by a
|
|
|
|
client to be present in the token resource to be considered
|
|
|
|
valid.
|
|
|
|
|
|
|
|
Requires `store_all_tokens?` to be `true`.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<a id="authentication-tokens-signing_algorithm" href="#authentication-tokens-signing_algorithm">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
signing_algorithm
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">String.t</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">"HS256"</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
The algorithm to use for token signing.
|
|
|
|
|
|
|
|
Available signing algorithms are;
|
|
|
|
EdDSA, Ed448ph, Ed448, Ed25519ph, Ed25519, PS512, PS384, PS256, ES512, ES384, ES256, RS512, RS384, RS256, HS512, HS384 and HS256.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<a id="authentication-tokens-token_lifetime" href="#authentication-tokens-token_lifetime">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
token_lifetime
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">pos_integer | {pos_integer, :days | :hours | :minutes | :seconds}</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">{14, :days}</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
How long a token should be valid.
|
|
|
|
|
|
|
|
Since refresh tokens are not yet supported, you should
|
|
|
|
probably set this to a reasonably long time to ensure
|
|
|
|
a good user experience.
|
|
|
|
|
|
|
|
You can either provide a tuple with a time unit, or a positive
|
|
|
|
integer, in which case the unit is assumed to be hours.
|
|
|
|
|
|
|
|
Defaults to 14 days.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<a id="authentication-tokens-signing_secret" href="#authentication-tokens-signing_secret">
|
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
signing_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 secret used to sign tokens.
|
|
|
|
|
|
|
|
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>
|
|
|
|
|
|
|
|
</tbody>
|
|
|
|
</table>
|
2023-09-22 10:20:50 +12:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## authentication.strategies
|
|
|
|
Configure authentication strategies on this resource
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## authentication.add_ons
|
|
|
|
Additional add-ons related to, but not providing authentication
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|