Tokens

Token Lifetime

Since refresh tokens are not yet included in ash_authentication, you should set the token lifetime to a reasonably long time to ensure a good user experience. Alternatively, refresh tokens can be implemented on your own.

Requiring Token Storage

Using AshAuthentication.Dsl.authentication.tokens.require_token_presence_for_authentication? inverts the token validation behaviour from requiring that tokens are not revoked to requiring any token presented by a client to be present in the token resource to be considered valid.

Requires store_all_tokens? to be true.

store_all_tokens? instructs AshAuthentication to keep track of all tokens issued to any user. This is optional behaviour with ash_authentication in order to preserve as much performance as possible.

Sign in Tokens

Enabled with AshAuthentication.Strategy.Password.authentication.strategies.password.sign_in_tokens_enabled?

Sign in tokens can be generated on request by setting the :token_type context to :sign_in when calling the sign in action. You might do this when you need to generate a short lived token to be exchanged for a real token using the validate_sign_in_token route. This is used, for example, by ash_authentication_phoenix (since 1.7) to support signing in a liveview, and then redirecting with a valid token to a controller action, allowing the liveview to show invalid username/password errors.

Extra Claims

You can add custom claims to generated tokens using the extra_claims option. This is useful for including user-specific data like roles, permissions, or tenant information in your JWTs.

DSL Configuration

Configure default extra claims that are included in all tokens for a resource:

authentication do
  tokens do
    enabled? true
    token_resource MyApp.Token

    # Using a function (receives user and options)
    extra_claims fn user, _opts ->
      %{"role" => user.role, "tenant_id" => user.tenant_id}
    end

    # Or using a static map
    extra_claims %{"app_version" => "1.0"}
  end
end

The function receives the user record and options (containing tenant, etc.) and should return a map of claims to include in the token.

Action-Level Claims

You can also add claims on a per-action basis using AshAuthentication.add_token_claims/2. This function works with changesets, queries, and action inputs.

For create actions (like registration):

create :register_with_password do
  # ... other configuration
  change AshAuthentication.GenerateTokenChange
  change fn changeset, _ctx ->
    AshAuthentication.add_token_claims(changeset, %{"session_type" => "registration"})
  end
end

For read actions (like sign-in):

MyApp.User
|> Ash.Query.for_read(:sign_in_with_password, %{email: email, password: password})
|> AshAuthentication.add_token_claims(%{"session_type" => "api"})
|> Ash.read_one!()

Action-level claims are merged with DSL-configured claims, with action-level claims taking precedence in case of conflicts.

Accessing Extra Claims

When store_all_tokens? is enabled, extra claims are stored in the token resource's extra_data attribute. When a user authenticates via bearer token or session (with require_token_presence_for_authentication? enabled), the extra claims are restored and available in the user's metadata:

# In a controller or plug
user = conn.assigns.current_user
claims = user.__metadata__.token_claims
# => %{"role" => "admin", "tenant_id" => "abc123"}

This allows you to access custom token data without needing to decode the JWT on every request.