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.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
|
|
|
|
|
|
|
|
## DSL Documentation
|
|
|
|
|
|
|
|
User confirmation flow
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* `:name` (`t:atom/0`) - Required. Uniquely identifies the add-on.
|
|
|
|
|
2023-09-22 12:15:47 +12:00
|
|
|
* `:token_lifetime` - How long should the confirmation token be valid.
|
|
|
|
If no unit is provided, then hours is assumed.
|
|
|
|
Defaults to 3 days. The default value is `{3, :days}`.
|
2023-09-22 10:20:50 +12:00
|
|
|
|
|
|
|
* `:monitor_fields` (list of `t:atom/0`) - Required. A list of fields to monitor for changes (eg `[:email, :phone_number]`).
|
|
|
|
The confirmation will only be sent when one of these fields are changed.
|
|
|
|
|
|
|
|
* `:confirmed_at_field` (`t:atom/0`) - The name of a field to store the time that the last confirmation took
|
|
|
|
place.
|
|
|
|
This attribute will be dynamically added to the resource if not already
|
|
|
|
present. The default value is `:confirmed_at`.
|
|
|
|
|
|
|
|
* `:confirm_on_create?` (`t:boolean/0`) - Generate and send a confirmation token when a new resource is created?
|
|
|
|
Will only trigger when a create action is executed _and_ one of the
|
|
|
|
monitored fields is being set. The default value is `true`.
|
|
|
|
|
|
|
|
* `:confirm_on_update?` (`t:boolean/0`) - Generate and send a confirmation token when a resource is changed?
|
|
|
|
Will only trigger when an update action is executed _and_ one of the
|
|
|
|
monitored fields is being set. The default value is `true`.
|
|
|
|
|
|
|
|
* `:inhibit_updates?` (`t:boolean/0`) - Wait until confirmation is received before actually changing a monitored
|
|
|
|
field?
|
|
|
|
If a change to a monitored field is detected, then the change is stored
|
|
|
|
in the token resource and the changeset updated to not make the
|
|
|
|
requested change. When the token is confirmed, the change will be
|
|
|
|
applied.
|
|
|
|
This could be potentially weird for your users, but useful in the case
|
|
|
|
of a user changing their email address or phone number where you want
|
|
|
|
to verify that the new contact details are reachable. The default value is `true`.
|
|
|
|
|
|
|
|
* `:sender` - Required. How to send the confirmation instructions to the user.
|
|
|
|
Allows you to glue sending of confirmation instructions to
|
|
|
|
[swoosh](https://hex.pm/packages/swoosh),
|
|
|
|
[ex_twilio](https://hex.pm/packages/ex_twilio) or whatever notification
|
|
|
|
system is appropriate for your application.
|
|
|
|
Accepts a module, module and opts, or a function that takes a record,
|
|
|
|
reset token and options.
|
|
|
|
The options will be a keyword list containing the original
|
|
|
|
changeset, before any changes were inhibited. This allows you
|
|
|
|
to send an email to the user's new email address if it is being
|
|
|
|
changed for example.
|
|
|
|
See `AshAuthentication.Sender` for more information.
|
|
|
|
|
|
|
|
* `:confirm_action_name` (`t:atom/0`) - The name of the action to use when performing confirmation.
|
|
|
|
If this action is not already present on the resource, it will be
|
|
|
|
created for you. The default value is `:confirm`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## authentication.add_ons.confirmation
|
|
|
|
```elixir
|
|
|
|
confirmation name \ :confirm
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
User confirmation flow
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2023-10-12 09:49:40 +13:00
|
|
|
### Arguments
|
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">
|
2023-10-12 09:49:40 +13:00
|
|
|
<a id="authentication-add_ons-confirmation-name" href="#authentication-add_ons-confirmation-name">
|
2023-09-27 16:42:46 +13:00
|
|
|
<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 add-on.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
2023-10-12 09:49:40 +13:00
|
|
|
</tbody>
|
|
|
|
</table>
|
|
|
|
### Options
|
|
|
|
|
|
|
|
<table>
|
|
|
|
<thead>
|
|
|
|
<tr>
|
|
|
|
<th>Name</th>
|
|
|
|
<th>Type</th>
|
|
|
|
<th>Default</th>
|
|
|
|
<th colspan=2>Docs</th>
|
|
|
|
</tr>
|
|
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<tr>
|
2023-09-27 16:42:46 +13:00
|
|
|
<td style="text-align: left">
|
2023-10-12 09:49:40 +13:00
|
|
|
<a id="authentication-add_ons-confirmation-monitor_fields" href="#authentication-add_ons-confirmation-monitor_fields">
|
2023-09-27 16:42:46 +13:00
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
monitor_fields
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
<sup style="color: red">*</sup>
|
|
|
|
|
|
|
|
</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 to monitor for changes (eg `[:email, :phone_number]`).
|
|
|
|
The confirmation will only be sent when one of these fields are changed.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
2023-10-12 09:49:40 +13:00
|
|
|
<a id="authentication-add_ons-confirmation-sender" href="#authentication-add_ons-confirmation-sender">
|
2023-09-27 16:42:46 +13:00
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
sender
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
<sup style="color: red">*</sup>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">(any, any, any -> any) | module</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
How to send the confirmation instructions to the user.
|
|
|
|
Allows you to glue sending of confirmation instructions to
|
|
|
|
[swoosh](https://hex.pm/packages/swoosh),
|
|
|
|
[ex_twilio](https://hex.pm/packages/ex_twilio) or whatever notification
|
|
|
|
system is appropriate for your application.
|
|
|
|
Accepts a module, module and opts, or a function that takes a record,
|
|
|
|
reset token and options.
|
|
|
|
The options will be a keyword list containing the original
|
|
|
|
changeset, before any changes were inhibited. This allows you
|
|
|
|
to send an email to the user's new email address if it is being
|
|
|
|
changed for example.
|
|
|
|
See `AshAuthentication.Sender` for more information.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
2023-10-12 09:49:40 +13:00
|
|
|
<a id="authentication-add_ons-confirmation-token_lifetime" href="#authentication-add_ons-confirmation-token_lifetime">
|
2023-09-27 16:42:46 +13:00
|
|
|
<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">{3, :days}</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
How long should the confirmation token be valid.
|
|
|
|
If no unit is provided, then hours is assumed.
|
|
|
|
|
|
|
|
Defaults to 3 days.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
2023-10-12 09:49:40 +13:00
|
|
|
<a id="authentication-add_ons-confirmation-confirmed_at_field" href="#authentication-add_ons-confirmation-confirmed_at_field">
|
2023-09-27 16:42:46 +13:00
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
confirmed_at_field
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">atom</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">:confirmed_at</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
The name of a field to store the time that the last confirmation took
|
|
|
|
place.
|
|
|
|
This attribute will be dynamically added to the resource if not already
|
|
|
|
present.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
2023-10-12 09:49:40 +13:00
|
|
|
<a id="authentication-add_ons-confirmation-confirm_on_create?" href="#authentication-add_ons-confirmation-confirm_on_create?">
|
2023-09-27 16:42:46 +13:00
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
confirm_on_create?
|
|
|
|
</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>
|
|
|
|
Generate and send a confirmation token when a new resource is created?
|
|
|
|
Will only trigger when a create action is executed _and_ one of the
|
|
|
|
monitored fields is being set.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
2023-10-12 09:49:40 +13:00
|
|
|
<a id="authentication-add_ons-confirmation-confirm_on_update?" href="#authentication-add_ons-confirmation-confirm_on_update?">
|
2023-09-27 16:42:46 +13:00
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
confirm_on_update?
|
|
|
|
</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>
|
|
|
|
Generate and send a confirmation token when a resource is changed?
|
|
|
|
Will only trigger when an update action is executed _and_ one of the
|
|
|
|
monitored fields is being set.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
2023-10-12 09:49:40 +13:00
|
|
|
<a id="authentication-add_ons-confirmation-inhibit_updates?" href="#authentication-add_ons-confirmation-inhibit_updates?">
|
2023-09-27 16:42:46 +13:00
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
inhibit_updates?
|
|
|
|
</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>
|
|
|
|
Wait until confirmation is received before actually changing a monitored
|
|
|
|
field?
|
|
|
|
If a change to a monitored field is detected, then the change is stored
|
|
|
|
in the token resource and the changeset updated to not make the
|
|
|
|
requested change. When the token is confirmed, the change will be
|
|
|
|
applied.
|
|
|
|
This could be potentially weird for your users, but useful in the case
|
|
|
|
of a user changing their email address or phone number where you want
|
|
|
|
to verify that the new contact details are reachable.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td style="text-align: left">
|
2023-10-12 09:49:40 +13:00
|
|
|
<a id="authentication-add_ons-confirmation-confirm_action_name" href="#authentication-add_ons-confirmation-confirm_action_name">
|
2023-09-27 16:42:46 +13:00
|
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
|
|
confirm_action_name
|
|
|
|
</span>
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">atom</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left">
|
|
|
|
<code class="inline">:confirm</code>
|
|
|
|
</td>
|
|
|
|
<td style="text-align: left" colspan=2>
|
|
|
|
The name of the action to use when performing confirmation.
|
|
|
|
If this action is not already present on the resource, it will be
|
|
|
|
created for you.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
</tbody>
|
|
|
|
</table>
|
2023-09-22 10:20:50 +12:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Introspection
|
|
|
|
|
|
|
|
Target: `AshAuthentication.AddOn.Confirmation`
|
|
|
|
|
|
|
|
|