mirror of
https://github.com/team-alembic/ash_authentication.git
synced 2024-09-20 05:13:10 +12:00
207 lines
5.5 KiB
Text
207 lines
5.5 KiB
Text
# DSL: AshAuthentication.TokenResource
|
|
|
|
This is an Ash resource extension which generates the default token resource.
|
|
|
|
The token resource is used to store information about tokens that should not
|
|
be shared with the end user. It does not actually contain any tokens.
|
|
|
|
For example:
|
|
|
|
* When an authentication token has been revoked
|
|
* When a confirmation token has changes to apply
|
|
|
|
## Storage
|
|
|
|
The information stored in this resource is essentially ephemeral - all tokens
|
|
have an expiry date, so it doesn't make sense to keep them after that time has
|
|
passed. However, if you have any tokens with very long expiry times then we
|
|
suggest you store this resource in a resilient data-layer such as Postgres.
|
|
|
|
## Usage
|
|
|
|
There is no need to define any attributes or actions (although you can if you
|
|
want). The extension will wire up everything that's needed for the token
|
|
system to function.
|
|
|
|
```
|
|
defmodule MyApp.Accounts.Token do
|
|
use Ash.Resource,
|
|
data_layer: AshPostgres.DataLayer,
|
|
extensions: [AshAuthentication.TokenResource]
|
|
|
|
token do
|
|
api MyApp.Accounts
|
|
end
|
|
|
|
postgres do
|
|
table "tokens"
|
|
repo MyApp.Repo
|
|
end
|
|
end
|
|
```
|
|
|
|
Whilst it is possible to have multiple token resources, there is no need to do
|
|
so.
|
|
|
|
## Removing expired records
|
|
|
|
Once a token has expired there's no point in keeping the information it refers
|
|
to, so expired tokens can be automatically removed by adding the
|
|
`AshAuthentication.Supervisor` to your application supervision tree. This
|
|
will start the `AshAuthentication.TokenResource.Expunger` `GenServer` which
|
|
periodically scans and removes any expired records.
|
|
|
|
<!--- ash-hq-hide-start --> <!--- -->
|
|
|
|
## Dsl
|
|
|
|
### Index
|
|
|
|
* token
|
|
* revocation
|
|
* confirmation
|
|
|
|
### Docs
|
|
|
|
## token
|
|
|
|
Configuration options for this token resource
|
|
|
|
* [revocation](#module-revocation)
|
|
* [confirmation](#module-confirmation)
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
* `:api` (`t:atom/0`) - Required. The Ash API to use to access this resource.
|
|
|
|
* `:expunge_expired_action_name` (`t:atom/0`) - The name of the action used to remove expired tokens. The default value is `:expunge_expired`.
|
|
|
|
* `:read_expired_action_name` (`t:atom/0`) - The name of the action use to find all expired tokens.
|
|
Used internally by the `expunge_expired` action. The default value is `:read_expired`.
|
|
|
|
* `:expunge_interval` (`t:pos_integer/0`) - How often to remove expired records.
|
|
How often to scan this resource for records which have expired, and thus can be removed. The default value is `12`.
|
|
|
|
* `:store_token_action_name` (`t:atom/0`) - The name of the action to use to store a token.
|
|
Used if `store_all_tokens?` is enabled in your authentication resource. The default value is `:store_token`.
|
|
|
|
* `:get_token_action_name` (`t:atom/0`) - The name of the action used to retrieve tokens from the store.
|
|
Used if `require_token_presence_for_authentication?` is enabled in your authentication resource. The default value is `:get_token`.
|
|
|
|
|
|
|
|
|
|
|
|
### revocation
|
|
|
|
Configuration options for token revocation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
* `:revoke_token_action_name` (`t:atom/0`) - The name of the action used to revoke tokens. The default value is `:revoke_token`.
|
|
|
|
* `:is_revoked_action_name` (`t:atom/0`) - The name of the action used to check if a token is revoked. The default value is `:revoked?`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### confirmation
|
|
|
|
Configuration options for confirmation tokens
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
* `:store_changes_action_name` (`t:atom/0`) - The name of the action used to store confirmation changes. The default value is `:store_confirmation_changes`.
|
|
|
|
* `:get_changes_action_name` (`t:atom/0`) - The name of the action used to get confirmation changes. The default value is `:get_confirmation_changes`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!--- ash-hq-hide-stop --> <!--- -->
|
|
|
|
|
|
## token
|
|
Configuration options for this token resource
|
|
|
|
### Nested DSLs
|
|
* [revocation](#token-revocation)
|
|
* [confirmation](#token-confirmation)
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
|
| Name | Type | Default | Docs |
|
|
| --- | --- | --- | --- |
|
|
| `api`* | `module` | | The Ash API to use to access this resource. |
|
|
| `expunge_expired_action_name` | `atom` | `:expunge_expired` | The name of the action used to remove expired tokens. |
|
|
| `read_expired_action_name` | `atom` | `:read_expired` | The name of the action use to find all expired tokens. Used internally by the `expunge_expired` action. |
|
|
| `expunge_interval` | `pos_integer` | `12` | How often to remove expired records. How often to scan this resource for records which have expired, and thus can be removed. |
|
|
| `store_token_action_name` | `atom` | `:store_token` | The name of the action to use to store a token. Used if `store_all_tokens?` is enabled in your authentication resource. |
|
|
| `get_token_action_name` | `atom` | `:get_token` | The name of the action used to retrieve tokens from the store. Used if `require_token_presence_for_authentication?` is enabled in your authentication resource. |
|
|
|
|
|
|
## token.revocation
|
|
Configuration options for token revocation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
|
| Name | Type | Default | Docs |
|
|
| --- | --- | --- | --- |
|
|
| `revoke_token_action_name` | `atom` | `:revoke_token` | The name of the action used to revoke tokens. |
|
|
| `is_revoked_action_name` | `atom` | `:revoked?` | The name of the action used to check if a token is revoked. |
|
|
|
|
|
|
|
|
|
|
## token.confirmation
|
|
Configuration options for confirmation tokens
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
|
| Name | Type | Default | Docs |
|
|
| --- | --- | --- | --- |
|
|
| `store_changes_action_name` | `atom` | `:store_confirmation_changes` | The name of the action used to store confirmation changes. |
|
|
| `get_changes_action_name` | `atom` | `:get_confirmation_changes` | The name of the action used to get confirmation changes. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|