ash_authentication

<!--
SPDX-FileCopyrightText: 2026 Alembic Pty Ltd

SPDX-License-Identifier: MIT
-->

# OTP (One-Time Password) Tutorial

The OTP strategy provides passwordless authentication where users receive a short code (e.g. `"XKPTMH"`) via email or SMS, then submit it to sign in. This is similar to the magic link strategy but uses a short code instead of a URL.

> #### Time-based one-time passwords {: .tip}
>
> If you're looking for the six-digit numeric codes which periodically change - sometimes
> called Google Authenticator - you almost certainly want [TOTP](tutorials/totp.md) instead.

## Security requirements

> #### Brute force protection {: .warning}
>
> OTP codes have limited entropy by design — short codes that users can type without error.
> Without rate limiting, an attacker can enumerate all possible codes within the lifetime
> of a single OTP.
>
> For this reason, the OTP strategy **requires** you to declare a `brute_force_strategy`
> at the DSL level. The verifier will fail compilation if the declared strategy is not
> actually wired up to the request and sign-in actions.
>
> A 10-minute OTP lifetime with 6 uppercase letters gives ~85 million possible codes.
> Even so, restricting to a handful of attempts per identity per OTP lifetime is essential.

### Choosing a brute force strategy

The `brute_force_strategy` option accepts one of:

- `:rate_limit` — defers to the [`AshRateLimiter`](https://hexdocs.pm/ash_rate_limiter)
  extension on the same resource. The verifier checks that the extension is present
  and that every OTP action has a `rate_limit` entry.
- `{:audit_log, :audit_log_name}` — tracks failed attempts in an audit log add-on
  and blocks after `audit_log_max_failures` within `audit_log_window`.
- `{:preparation, MyApp.BruteForceMitigation}` — plug in a custom
  `Ash.Resource.Preparation` implementation and take full control.

Example using rate limiting:

```elixir
use Ash.Resource, extensions: [AshAuthentication, AshRateLimiter]

authentication do
  strategies do
    otp do
      identity_field :email
      brute_force_strategy :rate_limit
      sender MyApp.Accounts.User.Senders.SendOtp
    end
  end
end

rate_limit do
  backend MyApp.RateLimiterBackend

  action :request_otp,
    limit: 5,
    per: :timer.minutes(15),
    key: fn query -> "otp:request:#{query.arguments[:email]}" end

  action :sign_in_with_otp,
    limit: 5,
    per: :timer.minutes(10),
    key: fn query -> "otp:sign_in:#{query.arguments[:email]}" end
end
```

> #### Scope the rate limit bucket by identity {: .warning}
>
> `AshRateLimiter`'s default bucket key is the domain + resource + action name, which
> means **a single global bucket is shared by all callers**. Without a `key` function,
> once any 5 callers hit `sign_in_with_otp` in 10 minutes the 6th is blocked —
> regardless of whose email they supplied. That both lets an attacker DoS the entire
> app by burning the bucket and fails to stop them from enumerating a single victim's
> code.
>
> Always supply a `key` function that scopes by the `identity_field` argument, as in
> the example above.

Example using an audit log:

```elixir
authentication do
  strategies do
    otp do
      identity_field :email
      brute_force_strategy {:audit_log, :auth_audit_log}
      audit_log_window {5, :minutes}
      audit_log_max_failures 5
      sender MyApp.Accounts.User.Senders.SendOtp
    end
  end

  add_ons do
    audit_log :auth_audit_log do
      audit_log_resource MyApp.Accounts.AuthAuditLog
    end
  end
end
```

The audit log add-on tracks all authentication actions by default, so there's no
need to list them explicitly — failures on `request_otp` and `sign_in_with_otp`
will both count toward the `audit_log_max_failures` threshold.

## Prerequisites

Your user resource needs:

1. A primary key
2. A uniquely constrained identity field (e.g. `email`)
3. Tokens enabled with `store_all_tokens?` set to `true`

## Add the OTP strategy to the User resource

```elixir
defmodule MyApp.Accounts.User do
  use Ash.Resource,
    extensions: [AshAuthentication, AshRateLimiter],
    domain: MyApp.Accounts

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

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

    strategies do
      otp do
        identity_field :email
        brute_force_strategy :rate_limit
        sender MyApp.Accounts.User.Senders.SendOtp
      end
    end
  end

  # Per-identity rate limiting — see "Choosing a brute force strategy" above
  # for the reasoning behind scoping the bucket by email.
  rate_limit do
    backend MyApp.RateLimiterBackend

    action :request_otp,
      limit: 5,
      per: :timer.minutes(15),
      key: fn query -> "otp:request:#{query.arguments[:email]}" end

    action :sign_in_with_otp,
      limit: 5,
      per: :timer.minutes(10),
      key: fn query -> "otp:sign_in:#{query.arguments[:email]}" end
  end

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

## Configuration options

The strategy supports several options with sensible defaults:

```elixir
otp do
  identity_field :email
  otp_lifetime {10, :minutes}          # how long the code is valid
  otp_length 6                         # length of the generated code
  otp_characters :unambiguous_uppercase # :unambiguous_uppercase, :unambiguous_alphanumeric, :digits_only, :uppercase_letters_only
  case_sensitive? false                 # when false, "xkptmh" matches "XKPTMH"
  single_use_token? true               # revoke code after successful sign-in
  sender MyApp.Accounts.User.Senders.SendOtp
end
```

## Create an OTP sender

The sender receives the user record and the short OTP code (not a JWT). You are responsible for delivering it to the user.

Inside `lib/my_app/accounts/user/senders/send_otp.ex`:

```elixir
defmodule MyApp.Accounts.User.Senders.SendOtp do
  @moduledoc """
  Sends a one-time password code to the user.
  """
  use AshAuthentication.Sender

  @impl AshAuthentication.Sender
  def send(user, otp_code, _opts) do
    MyApp.Accounts.Emails.deliver_otp(user.email, otp_code)
  end
end
```

Inside `lib/my_app/accounts/emails.ex`:

```elixir
def deliver_otp(email, otp_code) do
  deliver(email, "Your sign-in code", """
  <html>
    <p>Your sign-in code is:</p>
    <p style="font-size: 24px; font-weight: bold; letter-spacing: 4px;">#{otp_code}</p>
    <p>This code expires in 10 minutes.</p>
  </html>
  """)
end
```

You can also use an inline function sender for simple cases:

```elixir
sender fn user, otp_code, _opts ->
  MyApp.Accounts.Emails.deliver_otp(user.email, otp_code)
end
```

## Registration

By default, the OTP strategy only allows existing users to sign in. To allow new users to register via OTP, set `registration_enabled?` to `true`:

```elixir
otp do
  identity_field :email
  registration_enabled? true
  sender MyApp.Accounts.User.Senders.SendOtp
end
```

When registration is enabled:

- The **request** action sends an OTP code even if no user with that email exists yet.
- The **sign-in** action becomes a `:create` action with `upsert? true`. If the user doesn't exist, they are created; if they do, they are matched by their identity.
- `{:audit_log, ...}` is **not** a valid `brute_force_strategy` in this mode, because audit log mitigation requires an existing user record. Use `:rate_limit` or `{:preparation, MyModule}` instead.
- The sender receives the email address as a string (instead of a user record) when the user doesn't exist yet. Handle both cases in your sender:

```elixir
def send(user_or_email, otp_code, _opts) do
  email =
    case user_or_email do
      %{email: email} -> email
      email when is_binary(email) -> email
    end

  MyApp.Accounts.Emails.deliver_otp(email, otp_code)
end
```

> **Note:** If you don't define a sign-in action yourself, the strategy auto-generates the correct one at compile time and changing `registration_enabled?` just works. However, if you have a sign-in action defined in your resource file (whether written by hand or generated by an installer), it is **not** regenerated automatically. If you change `registration_enabled?`, you must update the action yourself: use a `:create` action with `AshAuthentication.Strategy.Otp.SignInChange` when `true`, or a `:read` action with `AshAuthentication.Strategy.Otp.SignInPreparation` when `false`. The verifier will raise if there's a mismatch.

## How it works

The OTP strategy uses a deterministic JTI (JWT ID) to map short codes back to stored tokens without requiring any schema changes to your token resource. The JTI is derived from `(strategy_name, user_subject, otp_code)` via `AshAuthentication.SHA256Provider`, keeping the crypto consistent with the recovery code strategy.

**Request flow:**

1. User submits their email
2. Strategy finds the user, generates a random OTP code
3. A JWT is created with a deterministic JTI derived from `(strategy_name, user_subject, otp_code)`
4. The JWT is stored in the token resource with purpose `"otp"`
5. The short code is sent to the user via the sender
6. Returns `:ok` regardless of whether the user exists (never reveals user existence)

**Sign-in flow:**

1. User submits their email and OTP code
2. Strategy finds the user, recomputes the deterministic JTI from the submitted code
3. Looks up the token by JTI and purpose `"otp"`
4. If found: code is valid. Revokes the token (if `single_use_token?`), generates an auth JWT, returns the user
5. If not found: authentication fails

## Using the strategy programmatically

```elixir
strategy = AshAuthentication.Info.strategy!(MyApp.Accounts.User, :otp)

# Request an OTP code (sends email)
:ok = AshAuthentication.Strategy.action(strategy, :request, %{
  "email" => "user@example.com"
})

# Sign in with the code
{:ok, user} = AshAuthentication.Strategy.action(strategy, :sign_in, %{
  "email" => "user@example.com",
  "otp" => "XKPTMH"
})

# The auth JWT is available in metadata
token = user.__metadata__.token
```

## HTTP endpoints

When using `AshAuthentication.Plug`, the strategy automatically registers two POST routes:

```
POST /user/otp/request    {"user": {"email": "user@example.com"}}
POST /user/otp/sign_in    {"user": {"email": "user@example.com", "otp": "XKPTMH"}}
```

## Character sets and entropy

The built-in character sets and the number of possible codes they produce at the default length of 6:

| Option | Symbols | Codes at length 6 | Notes |
|---|---|---|---|
| `:unambiguous_uppercase` (default) | 21 | ~85.8 million | A–Z minus I, L, O, S, Z |
| `:unambiguous_alphanumeric` | 27 | ~387 million | above plus 3,4,6,7,8,9 |
| `:uppercase_letters_only` | 26 | ~309 million | full A–Z |
| `:digits_only` | 10 | 1 million | full 0–9; only just meets the minimum at length 6 |

The strategy enforces a minimum of 1,000,000 possible codes at compile time (derived from NIST SP 800-63B §5.1.3.2). Configurations that fall below this threshold — such as `:digits_only` with `otp_length` less than 6 — will raise a `Spark.Error.DslError` at compile time.

## Custom OTP generator

By default, the strategy uses `AshAuthentication.Strategy.Otp.DefaultGenerator` which generates cryptographically random codes from an ambiguity-reduced character set (excluding easily misread characters like `I`/`1`, `O`/`0`, `S`/`5`, `Z`/`2`).

You can supply your own generator module:

```elixir
otp do
  identity_field :email
  otp_generator MyApp.Accounts.OtpGenerator
  sender MyApp.Accounts.User.Senders.SendOtp
end
```

The module must export `generate/1` and `normalize/1`:

```elixir
defmodule MyApp.Accounts.OtpGenerator do
  def generate(opts) do
    length = Keyword.get(opts, :length, 6)
    # your implementation here
  end

  def normalize(code) do
    String.trim(code)
  end
end
```

The `generate/1` function receives `[length: ..., characters: ...]` from the strategy configuration. The `normalize/1` function is called on both the generated code (during request) and the submitted code (during sign-in) to ensure consistent matching.

> #### Security responsibility {: .warning}
>
> When using a custom generator, the compile-time entropy check is skipped — the
> strategy cannot reason about the code space your implementation produces. It is
> your responsibility to ensure the generator meets your system's security
> requirements, including sufficient entropy, cryptographically secure randomness,
> and correct handling of the `length` and `characters` opts.

## Differences from Magic Links

| | Magic Link | OTP |
|---|---|---|
| **User receives** | A URL with a JWT | A short code (e.g. `XKPTMH`) |
| **Sign-in requires** | Just the token (from URL) | Both identity field and code |
| **UX pattern** | Click link in email | Enter code on same page |
| **Registration** | Can register new users | Can register new users (opt-in) |
| **Interaction required** | Optional (configurable) | Always (user must type code) |