Packages
ash_authentication
5.0.0-rc.0
5.0.0-rc.12
5.0.0-rc.11
5.0.0-rc.10
5.0.0-rc.9
5.0.0-rc.8
5.0.0-rc.7
5.0.0-rc.6
5.0.0-rc.5
5.0.0-rc.4
5.0.0-rc.3
5.0.0-rc.2
5.0.0-rc.1
5.0.0-rc.0
4.14.1
4.14.0
4.13.7
4.13.6
4.13.5
4.13.4
4.13.3
4.13.2
retired
4.13.1
retired
4.13.0
4.12.0
4.11.0
4.10.0
4.9.9
4.9.8
4.9.7
4.9.6
4.9.5
4.9.4
4.9.3
4.9.2
4.9.1
4.9.0
4.8.7
4.8.6
4.8.5
4.8.3
4.8.2
4.8.1
4.8.0
4.7.6
4.7.5
4.7.4
4.7.3
4.7.2
4.7.1
4.7.0
4.6.4
4.6.3
4.6.2
4.6.1
4.6.0
4.5.6
4.5.5
4.5.4
4.5.3
4.5.2
4.5.1
4.5.0
4.4.9
4.4.8
4.4.7
4.4.6
4.4.5
4.4.4
4.4.3
4.4.2
4.4.1
4.4.0
4.3.12
4.3.11
4.3.10
4.3.9
4.3.8
4.3.7
4.3.6
4.3.5
4.3.4
4.3.3
4.3.2
4.3.1
4.3.0
4.2.7
4.2.6
4.2.5
4.2.4
4.2.3
4.2.2
4.2.1
4.2.0
4.1.0
4.0.4
4.0.3
4.0.2
4.0.1
4.0.0
4.0.0-rc.6
4.0.0-rc.5
4.0.0-rc.3
4.0.0-rc.2
4.0.0-rc.1
4.0.0-rc.0
3.12.4
3.12.3
3.12.2
3.12.1
3.12.0
3.11.16
3.11.15
3.11.14
3.11.13
3.11.12
3.11.11
3.11.10
3.11.9
3.11.8
3.11.7
3.11.6
3.11.5
3.11.4
3.11.3
3.11.2
3.11.1
3.11.0
3.10.8
3.10.7
3.10.6
3.10.5
3.10.4
3.10.3
3.10.2
3.10.1
3.10.0
3.9.6
3.9.5
3.9.4
3.9.3
3.9.2
3.9.1
3.9.0
3.8.0
3.7.9
3.7.8
3.7.6
3.7.5
3.7.4
3.7.3
3.7.2
3.7.1
3.7.0
3.6.1
3.6.0
3.5.3
3.5.2
3.5.1
3.5.0
3.3.1
3.3.0
3.2.2
3.2.1
3.2.0
3.1.0
3.0.3
Authentication extension for the Ash Framework.
Security advisory:
This version has known vulnerabilities.
View advisories
Current section
Files
Jump to
Current section
Files
documentation/topics/tokens.md
<!--
SPDX-FileCopyrightText: 2022 Alembic Pty Ltd
SPDX-License-Identifier: MIT
-->
# 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 `d: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 `d: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:
```elixir
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):
```elixir
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):
```elixir
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:
```elixir
# 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.