View Source AshAuthentication.AddOn.Confirmation (ash_authentication v3.11.15)

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


defmodule MyApp.Accounts.User do
  use Ash.Resource,
    extensions: [AshAuthentication]

  attributes do
    uuid_primary_key :id
    attribute :email, :ci_string, allow_nil?: false

  authentication do
    api MyApp.Accounts

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

    strategies do
      # ...

  identities do
    identity :email, [:email] do
      eager_check_with MyApp.Accounts


A confirmed_at attribute will be added to your resource if it's not already present (see confirmed_at_field in the DSL documentation).


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.


iex> strategy = Info.strategy!(Example.User, :confirm)
...> {:ok, user} = Strategy.action(strategy, :confirm, %{"confirm" => confirmation_token()})
...> user.confirmed_at >= one_second_ago()


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.


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()

DSL Documentation

User confirmation flow

  • :name (atom/0) - Required. Uniquely identifies the add-on.

  • :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}.

  • :monitor_fields (list of 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 (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? (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? (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? (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, 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 (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.



@type t() :: %AshAuthentication.AddOn.Confirmation{
  confirm_action_name: atom(),
  confirm_on_create?: boolean(),
  confirm_on_update?: boolean(),
  confirmed_at_field: atom(),
  inhibit_updates?: boolean(),
  monitor_fields: [atom()],
  name: :confirm,
  provider: :confirmation,
  resource: module(),
  sender: nil | {module(), keyword()},
  strategy_module: module(),
  token_lifetime: hours :: pos_integer()


Link to this function

confirmation_token(strategy, changeset, user)

View Source
@spec confirmation_token(t(), Ash.Changeset.t(), Ash.Resource.record()) ::
  {:ok, String.t()} | :error | {:error, any()}

Generate a confirmation token for a changeset.

This will generate a token with the "act" claim set to the confirmation action for the strategy, and the "chg" claim will contain any changes.

Link to this function

transform(entity, dsl_state)

View Source

Callback implementation for AshAuthentication.Strategy.Custom.transform/2.

Link to this function

verify(strategy, dsl_state)

View Source

Callback implementation for AshAuthentication.Strategy.Custom.verify/2.