mirror of
https://github.com/team-alembic/ash_authentication.git
synced 2024-09-20 13:24:20 +12:00
bb9b3d7655
chore: update cheat sheets
359 lines
8.1 KiB
Text
359 lines
8.1 KiB
Text
<!--
|
|
This file was generated by Spark. Do not edit it by hand.
|
|
-->
|
|
# 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.
|
|
|
|
|
|
## token
|
|
Configuration options for this token resource
|
|
|
|
### Nested DSLs
|
|
* [revocation](#token-revocation)
|
|
* [confirmation](#token-confirmation)
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Default</th>
|
|
<th colspan=2>Docs</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-api" href="#token-api">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
api
|
|
</span>
|
|
</a>
|
|
<sup style="color: red">*</sup>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">module</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The Ash API to use to access this resource.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-expunge_expired_action_name" href="#token-expunge_expired_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
expunge_expired_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:expunge_expired</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the action used to remove expired tokens.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-read_expired_action_name" href="#token-read_expired_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
read_expired_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:read_expired</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the action use to find all expired tokens.
|
|
|
|
Used internally by the `expunge_expired` action.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-expunge_interval" href="#token-expunge_interval">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
expunge_interval
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">pos_integer</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">12</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
How often to remove expired records.
|
|
|
|
How often to scan this resource for records which have expired, and thus can be removed.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-store_token_action_name" href="#token-store_token_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
store_token_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:store_token</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the action to use to store a token.
|
|
|
|
Used if `store_all_tokens?` is enabled in your authentication resource.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-get_token_action_name" href="#token-get_token_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
get_token_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:get_token</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
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.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
## token.revocation
|
|
Configuration options for token revocation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Default</th>
|
|
<th colspan=2>Docs</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-revocation-revoke_token_action_name" href="#token-revocation-revoke_token_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
revoke_token_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:revoke_token</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the action used to revoke tokens.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-revocation-is_revoked_action_name" href="#token-revocation-is_revoked_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
is_revoked_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:revoked?</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the action used to check if a token is revoked.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
|
|
|
|
## token.confirmation
|
|
Configuration options for confirmation tokens
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Default</th>
|
|
<th colspan=2>Docs</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-confirmation-store_changes_action_name" href="#token-confirmation-store_changes_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
store_changes_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:store_confirmation_changes</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the action used to store confirmation changes.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td style="text-align: left">
|
|
<a id="token-confirmation-get_changes_action_name" href="#token-confirmation-get_changes_action_name">
|
|
<span style="font-family: Inconsolata, Menlo, Courier, monospace;">
|
|
get_changes_action_name
|
|
</span>
|
|
</a>
|
|
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">atom</code>
|
|
</td>
|
|
<td style="text-align: left">
|
|
<code class="inline">:get_confirmation_changes</code>
|
|
</td>
|
|
<td style="text-align: left" colspan=2>
|
|
The name of the action used to get confirmation changes.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|