mirror of
https://github.com/team-alembic/ash_authentication.git
synced 2024-09-20 13:24:20 +12:00
ba44d56820
docs: make all DSL docs one liners (now required by spark)
133 lines
5.2 KiB
Markdown
133 lines
5.2 KiB
Markdown
<!--
|
|
This file was generated by Spark. Do not edit it by hand.
|
|
-->
|
|
# DSL: AshAuthentication.AddOn.Confirmation
|
|
|
|
Confirmation support.
|
|
|
|
Sometimes when creating a new user, or changing a sensitive attribute (such as
|
|
their email address) you may want to wait for the user to confirm by way of
|
|
sending them a confirmation token to prove that it was really them that took
|
|
the action.
|
|
|
|
In order to add confirmation to your resource, it must been the following
|
|
minimum requirements:
|
|
|
|
1. Have a primary key
|
|
2. Have at least one attribute you wish to confirm
|
|
3. Tokens must be enabled
|
|
|
|
## 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
|
|
|
|
add_ons do
|
|
confirmation :confirm do
|
|
monitor_fields [:email]
|
|
sender MyApp.ConfirmationSender
|
|
end
|
|
end
|
|
|
|
strategies do
|
|
# ...
|
|
end
|
|
end
|
|
|
|
identities do
|
|
identity :email, [:email] do
|
|
eager_check_with MyApp.Accounts
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
## Attributes
|
|
|
|
A `confirmed_at` attribute will be added to your resource if it's not already
|
|
present (see `confirmed_at_field` in the DSL documentation).
|
|
|
|
## Actions
|
|
|
|
By default confirmation will add an action which updates the `confirmed_at`
|
|
attribute as well as retrieving previously stored changes and applying them to
|
|
the resource.
|
|
|
|
If you wish to perform the confirm action directly from your code you can do
|
|
so via the `AshAuthentication.Strategy` protocol.
|
|
|
|
### Example
|
|
|
|
iex> strategy = Info.strategy!(Example.User, :confirm)
|
|
...> {:ok, user} = Strategy.action(strategy, :confirm, %{"confirm" => confirmation_token()})
|
|
...> user.confirmed_at >= one_second_ago()
|
|
true
|
|
|
|
## Plugs
|
|
|
|
Confirmation provides a single endpoint for the `:confirm` phase. If you wish
|
|
to interact with the plugs directly, you can do so via the
|
|
`AshAuthentication.Strategy` protocol.
|
|
|
|
### Example
|
|
|
|
iex> strategy = Info.strategy!(Example.User, :confirm)
|
|
...> conn = conn(:get, "/user/confirm", %{"confirm" => confirmation_token()})
|
|
...> conn = Strategy.plug(strategy, :confirm, conn)
|
|
...> {_conn, {:ok, user}} = Plug.Helpers.get_authentication_result(conn)
|
|
...> user.confirmed_at >= one_second_ago()
|
|
true
|
|
|
|
|
|
|
|
## authentication.add_ons.confirmation
|
|
```elixir
|
|
confirmation name \\ :confirm
|
|
```
|
|
|
|
|
|
User confirmation flow
|
|
|
|
|
|
|
|
|
|
|
|
### Arguments
|
|
|
|
| Name | Type | Default | Docs |
|
|
|------|------|---------|------|
|
|
| [`name`](#authentication-add_ons-confirmation-name){: #authentication-add_ons-confirmation-name .spark-required} | `atom` | | Uniquely identifies the add-on. |
|
|
### Options
|
|
|
|
| Name | Type | Default | Docs |
|
|
|------|------|---------|------|
|
|
| [`monitor_fields`](#authentication-add_ons-confirmation-monitor_fields){: #authentication-add_ons-confirmation-monitor_fields .spark-required} | `list(atom)` | | A list of fields to monitor for changes. Confirmation will be sent when one of these fields are changed. |
|
|
| [`sender`](#authentication-add_ons-confirmation-sender){: #authentication-add_ons-confirmation-sender .spark-required} | `(any, any, any -> any) \| module` | | How to send the confirmation instructions to the user. |
|
|
| [`token_lifetime`](#authentication-add_ons-confirmation-token_lifetime){: #authentication-add_ons-confirmation-token_lifetime } | `pos_integer \| {pos_integer, :days \| :hours \| :minutes \| :seconds}` | `{3, :days}` | How long should the confirmation token be valid. If no unit is provided, then hours is assumed. |
|
|
| [`confirmed_at_field`](#authentication-add_ons-confirmation-confirmed_at_field){: #authentication-add_ons-confirmation-confirmed_at_field } | `atom` | `:confirmed_at` | The name of the field to store the time that the last confirmation took place. Created if it does not exist. |
|
|
| [`confirm_on_create?`](#authentication-add_ons-confirmation-confirm_on_create?){: #authentication-add_ons-confirmation-confirm_on_create? } | `boolean` | `true` | Generate and send a confirmation token when a new resource is created. Triggers when a create action is executed _and_ one of the monitored fields is being set. |
|
|
| [`confirm_on_update?`](#authentication-add_ons-confirmation-confirm_on_update?){: #authentication-add_ons-confirmation-confirm_on_update? } | `boolean` | `true` | Generate and send a confirmation token when a resource is changed. Triggers when an update action is executed _and_ one of the monitored fields is being set. |
|
|
| [`inhibit_updates?`](#authentication-add_ons-confirmation-inhibit_updates?){: #authentication-add_ons-confirmation-inhibit_updates? } | `boolean` | `true` | Whether or not to wait until confirmation is received before actually changing a monitored field. See [the confirmation guide](/documentation/topics/confirmation.md) for more. |
|
|
| [`confirm_action_name`](#authentication-add_ons-confirmation-confirm_action_name){: #authentication-add_ons-confirmation-confirm_action_name } | `atom` | `:confirm` | The name of the action to use when performing confirmation. Will be created if it does not already exist. |
|
|
|
|
|
|
|
|
|
|
|
|
### Introspection
|
|
|
|
Target: `AshAuthentication.AddOn.Confirmation`
|
|
|
|
|
|
|
|
<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>
|