AshAuthentication.Strategy.Totp

Strategy for Time-based One-Time Password (TOTP) authentication.

Provides TOTP support via nimble_totp, allowing users to authenticate using time-based codes from authenticator apps like Google Authenticator, Authy, or 1Password.

Requirements

Your resource needs to meet the following minimum requirements:

1. Have a primary key.
2. An identity field (e.g., email or username) for identifying users.
3. A sensitive binary field for storing the TOTP secret.
4. A sensitive datetime field for tracking the last successful TOTP authentication.
5. A brute force protection strategy (rate limiting, audit log, or custom preparation).

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, public?: true
    attribute :totp_secret, :binary, sensitive?: true
    attribute :last_totp_at, :utc_datetime, sensitive?: true
  end

  authentication do
    tokens do
      enabled? true
      token_resource MyApp.Accounts.Token
    end

    strategies do
      totp do
        identity_field :email
        issuer "MyApp"
        brute_force_strategy {:audit_log, :my_audit_log}
      end
    end

    add_ons do
      audit_log :my_audit_log do
        audit_log_resource MyApp.Accounts.AuditLog
        log_actions [:sign_in_with_totp, :verify_with_totp, :confirm_setup_with_totp]
      end
    end
  end

  identities do
    identity :unique_email, [:email]
  end
end

Actions

The TOTP strategy can generate up to four actions:

• setup - Generates a new TOTP secret for the user. Returns the user with a totp_url calculation that can be rendered as a QR code.
• confirm_setup - When confirm_setup_enabled? is true, this action verifies a TOTP code before activating the secret. Requires tokens to be enabled.
• sign_in - Authenticates a user using their identity and a TOTP code.
• verify - Checks if a TOTP code is valid for a given user (without signing in).

Brute Force Protection

TOTP codes have a small keyspace (typically 6 digits), making them vulnerable to brute force attacks. You must configure a brute_force_strategy:

• :rate_limit - Uses AshRateLimiter to limit attempts.
• {:audit_log, :audit_log_name} - Uses an audit log to track failed attempts.
• {:preparation, ModuleName} - Custom preparation for rate limiting.

Working with Actions

You can interact with TOTP actions via the AshAuthentication.Strategy protocol:

iex> strategy = AshAuthentication.Info.strategy!(MyApp.Accounts.User, :totp)
...> {:ok, user} = AshAuthentication.Strategy.action(strategy, :setup, %{user: existing_user})
...> user.totp_url_for_totp  # QR code URL

iex> {:ok, true} = AshAuthentication.Strategy.action(strategy, :verify, %{user: user, code: "123456"})

authentication.strategies.totp

totp name \\ :totp

Adds TOTP-based one-time passcode authentication.

Arguments

Options

Introspection

Target: AshAuthentication.Strategy.Totp