mirror of
https://github.com/team-alembic/ash_authentication.git
synced 2024-09-21 13:53:25 +12:00
160 lines
6.6 KiB
Markdown
160 lines
6.6 KiB
Markdown
<!--
|
|
This file was generated by Spark. Do not edit it by hand.
|
|
-->
|
|
# 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],
|
|
domain: MyApp.Accounts
|
|
|
|
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
|
|
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.
|
|
- also includes:
|
|
- `AshAuthentication.Strategy.Auth0`
|
|
- `AshAuthentication.Strategy.Github`
|
|
- `AshAuthentication.Strategy.Google`
|
|
- `AshAuthentication.Strategy.Oidc`
|
|
3. `AshAuthentication.Strategy.MagicLink`
|
|
- authenticate by sending a single-use link to the user.
|
|
|
|
## 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
|
|
|
|
| Name | Type | Default | Docs |
|
|
|------|------|---------|------|
|
|
| [`subject_name`](#authentication-subject_name){: #authentication-subject_name } | `atom` | | The subject name is used anywhere that a short version of your resource name is needed. Must be unique system-wide and will be inferred from the resource name by default (ie `MyApp.Accounts.User` -> `user`). |
|
|
| [`domain`](#authentication-domain){: #authentication-domain } | `module` | | The name of the Ash domain to use to access this resource when doing anything authentication related. |
|
|
| [`get_by_subject_action_name`](#authentication-get_by_subject_action_name){: #authentication-get_by_subject_action_name } | `atom` | `:get_by_subject` | The name of the read action used to retrieve records. If the action doesn't exist, one will be generated for you. |
|
|
| [`select_for_senders`](#authentication-select_for_senders){: #authentication-select_for_senders } | `list(atom)` | | A list of fields that we will ensure are selected whenever a sender will be invoked. Defaults to `[:email]` if there is an `:email` attribute on the resource, and `[]` otherwise. |
|
|
|
|
|
|
## authentication.tokens
|
|
Configure JWT settings for this resource
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
|
|
|
| Name | Type | Default | Docs |
|
|
|------|------|---------|------|
|
|
| [`token_resource`](#authentication-tokens-token_resource){: #authentication-tokens-token_resource .spark-required} | `module \| false` | | The resource used to store token information, such as in-flight confirmations, revocations, and if `store_all_tokens?` is enabled, authentication tokens themselves. |
|
|
| [`enabled?`](#authentication-tokens-enabled?){: #authentication-tokens-enabled? } | `boolean` | `false` | Should JWTs be generated by this resource? |
|
|
| [`store_all_tokens?`](#authentication-tokens-store_all_tokens?){: #authentication-tokens-store_all_tokens? } | `boolean` | `false` | Store all tokens in the `token_resource`. See the [tokens guide](/documentation/topics/tokens.md) for more. |
|
|
| [`require_token_presence_for_authentication?`](#authentication-tokens-require_token_presence_for_authentication?){: #authentication-tokens-require_token_presence_for_authentication? } | `boolean` | `false` | Require a locally-stored token for authentication. See the [tokens guide](/documentation/topics/tokens.md) for more. |
|
|
| [`signing_algorithm`](#authentication-tokens-signing_algorithm){: #authentication-tokens-signing_algorithm } | `String.t` | `"HS256"` | 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. |
|
|
| [`token_lifetime`](#authentication-tokens-token_lifetime){: #authentication-tokens-token_lifetime } | `pos_integer \| {pos_integer, :days \| :hours \| :minutes \| :seconds}` | `{14, :days}` | How long a token should be valid. See [the tokens guide](/documentation/topics/tokens.md) for more. |
|
|
| [`signing_secret`](#authentication-tokens-signing_secret){: #authentication-tokens-signing_secret } | `(any, any -> any) \| module \| String.t` | | The secret used to sign tokens. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
|
|
|
|
|
|
|
|
|
|
## authentication.strategies
|
|
Configure authentication strategies on this resource
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## authentication.add_ons
|
|
Additional add-ons related to, but not providing authentication
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>
|