View Source 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 

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
  end

  authentication do
    add_ons do
      confirmation :confirm do
        monitor_fields [:email]
        sender MyApp.ConfirmationSender
      end
    end

    strategies do
      # ...
    end
  end

  identities do
    identity :email, [:email]
  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 

confirmation name \\ :confirm

User confirmation flow

Arguments

NameTypeDefaultDocs
nameatomUniquely identifies the add-on.

Options

NameTypeDefaultDocs
monitor_fieldslist(atom)A list of fields to monitor for changes. Confirmation will be sent when one of these fields are changed.
sender(any, any, any -> any) | moduleHow to send the confirmation instructions to the user.
token_lifetimepos_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.
prevent_hijacking?booleantrueWhether or not to prevent upserts over unconfirmed uers. See the confirmation guide for more.
confirmed_at_fieldatom:confirmed_atThe name of the field to store the time that the last confirmation took place. Created if it does not exist.
confirm_on_create?booleantrueGenerate 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?booleantrueGenerate 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?booleantrueWhether or not to wait until confirmation is received before actually changing a monitored field. See the confirmation guide for more.
auto_confirm_actionslist(atom)A list of actions that should set confirmed_at to true automatically. For example, you would likely want to place :sign_in_with_magic_link in this list if using magic link.
confirm_action_nameatomThe name of the action to use when performing confirmation. Will be created if it does not already exist. Defaults to confirm_<String.trim_leading(strategy_name, "confirm")>

Introspection

Target: AshAuthentication.AddOn.Confirmation