mirror of
https://github.com/team-alembic/ash_authentication.git
synced 2024-09-21 13:53:25 +12:00
180 lines
8.8 KiB
Markdown
180 lines
8.8 KiB
Markdown
<!--
|
|
This file was generated by Spark. Do not edit it by hand.
|
|
-->
|
|
# DSL: AshAuthentication.Strategy.Password
|
|
|
|
Strategy for authenticating using local resources as the source of truth.
|
|
|
|
In order to use password authentication your resource needs to meet the
|
|
following minimum requirements:
|
|
|
|
1. Have a primary key.
|
|
2. A uniquely constrained identity field (eg `username` or `email`).
|
|
3. A sensitive string field within which to store the hashed password.
|
|
|
|
There are other options documented in the DSL.
|
|
|
|
### Example:
|
|
|
|
```elixir
|
|
defmodule MyApp.Accounts.User do
|
|
use Ash.Resource,
|
|
extensions: [AshAuthentication],
|
|
domain: MyApp.Accounts
|
|
|
|
attributes do
|
|
uuid_primary_key :id
|
|
attribute :email, :ci_string, allow_nil?: false
|
|
attribute :hashed_password, :string, allow_nil?: false, sensitive?: true
|
|
end
|
|
|
|
authentication do
|
|
strategies do
|
|
password :password do
|
|
identity_field :email
|
|
hashed_password_field :hashed_password
|
|
end
|
|
end
|
|
end
|
|
|
|
identities do
|
|
identity :unique_email, [:email]
|
|
end
|
|
end
|
|
```
|
|
|
|
## Actions
|
|
|
|
By default the password strategy will automatically generate the register,
|
|
sign-in, reset-request and reset actions for you, however you're free to
|
|
define them yourself. If you do, then the action will be validated to ensure
|
|
that all the needed configuration is present.
|
|
|
|
If you wish to work with the actions directly from your code you can do so via
|
|
the `AshAuthentication.Strategy` protocol.
|
|
|
|
### Examples:
|
|
|
|
Interacting with the actions directly:
|
|
|
|
iex> strategy = Info.strategy!(Example.User, :password)
|
|
...> {:ok, marty} = Strategy.action(strategy, :register, %{"username" => "marty", "password" => "outatime1985", "password_confirmation" => "outatime1985"})
|
|
...> marty.username |> to_string()
|
|
"marty"
|
|
|
|
...> {:ok, user} = Strategy.action(strategy, :sign_in, %{"username" => "marty", "password" => "outatime1985"})
|
|
...> user.username |> to_string()
|
|
"marty"
|
|
|
|
## Plugs
|
|
|
|
The password strategy provides plug endpoints for all four actions, although
|
|
only sign-in and register will be reported by `Strategy.routes/1` if the
|
|
strategy is not configured as resettable.
|
|
|
|
If you wish to work with the plugs directly, you can do so via the
|
|
`AshAuthentication.Strategy` protocol.
|
|
|
|
### Examples:
|
|
|
|
Dispatching to plugs directly:
|
|
|
|
iex> strategy = Info.strategy!(Example.User, :password)
|
|
...> conn = conn(:post, "/user/password/register", %{"user" => %{"username" => "marty", "password" => "outatime1985", "password_confirmation" => "outatime1985"}})
|
|
...> conn = Strategy.plug(strategy, :register, conn)
|
|
...> {_conn, {:ok, marty}} = Plug.Helpers.get_authentication_result(conn)
|
|
...> marty.username |> to_string()
|
|
"marty"
|
|
|
|
...> conn = conn(:post, "/user/password/reset_request", %{"user" => %{"username" => "marty"}})
|
|
...> conn = Strategy.plug(strategy, :reset_request, conn)
|
|
...> {_conn, :ok} = Plug.Helpers.get_authentication_result(conn)
|
|
|
|
## Testing
|
|
|
|
See the [Testing guide](/documentation/topics/testing.md) for tips on testing resources using this strategy.
|
|
|
|
|
|
|
|
## authentication.strategies.password
|
|
```elixir
|
|
password name \\ :password
|
|
```
|
|
|
|
|
|
Strategy for authenticating using local resources as the source of truth.
|
|
|
|
### Nested DSLs
|
|
* [resettable](#authentication-strategies-password-resettable)
|
|
|
|
|
|
### Examples
|
|
```
|
|
password :password do
|
|
identity_field :email
|
|
hashed_password_field :hashed_password
|
|
hash_provider AshAuthentication.BcryptProvider
|
|
confirmation_required? true
|
|
end
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Options
|
|
|
|
| Name | Type | Default | Docs |
|
|
|------|------|---------|------|
|
|
| [`identity_field`](#authentication-strategies-password-identity_field){: #authentication-strategies-password-identity_field } | `atom` | `:username` | The name of the attribute which uniquely identifies the user, usually something like `username` or `email_address`. |
|
|
| [`hashed_password_field`](#authentication-strategies-password-hashed_password_field){: #authentication-strategies-password-hashed_password_field } | `atom` | `:hashed_password` | The name of the attribute within which to store the user's password once it has been hashed. |
|
|
| [`hash_provider`](#authentication-strategies-password-hash_provider){: #authentication-strategies-password-hash_provider } | `module` | `AshAuthentication.BcryptProvider` | A module which implements the `AshAuthentication.HashProvider` behaviour, to provide cryptographic hashing of passwords. |
|
|
| [`confirmation_required?`](#authentication-strategies-password-confirmation_required?){: #authentication-strategies-password-confirmation_required? } | `boolean` | `true` | Whether a password confirmation field is required when registering or changing passwords. |
|
|
| [`register_action_accept`](#authentication-strategies-password-register_action_accept){: #authentication-strategies-password-register_action_accept } | `list(atom)` | `[]` | A list of additional fields to be accepted in the register action. |
|
|
| [`password_field`](#authentication-strategies-password-password_field){: #authentication-strategies-password-password_field } | `atom` | `:password` | The name of the argument used to collect the user's password in plaintext when registering, checking or changing passwords. |
|
|
| [`password_confirmation_field`](#authentication-strategies-password-password_confirmation_field){: #authentication-strategies-password-password_confirmation_field } | `atom` | `:password_confirmation` | The name of the argument used to confirm the user's password in plaintext when registering or changing passwords. |
|
|
| [`register_action_name`](#authentication-strategies-password-register_action_name){: #authentication-strategies-password-register_action_name } | `atom` | | The name to use for the register action. Defaults to `register_with_<strategy_name>` |
|
|
| [`registration_enabled?`](#authentication-strategies-password-registration_enabled?){: #authentication-strategies-password-registration_enabled? } | `boolean` | `true` | If you do not want new users to be able to register using this strategy, set this to false. |
|
|
| [`sign_in_action_name`](#authentication-strategies-password-sign_in_action_name){: #authentication-strategies-password-sign_in_action_name } | `atom` | | The name to use for the sign in action. Defaults to `sign_in_with_<strategy_name>` |
|
|
| [`sign_in_enabled?`](#authentication-strategies-password-sign_in_enabled?){: #authentication-strategies-password-sign_in_enabled? } | `boolean` | `true` | If you do not want new users to be able to sign in using this strategy, set this to false. |
|
|
| [`sign_in_tokens_enabled?`](#authentication-strategies-password-sign_in_tokens_enabled?){: #authentication-strategies-password-sign_in_tokens_enabled? } | `boolean` | `false` | Whether or not to support generating short lived sign in tokens. Requires the resource to have tokens enabled. There is no drawback to supporting this, and in the future this default will change from `false` to `true`. |
|
|
| [`sign_in_token_lifetime`](#authentication-strategies-password-sign_in_token_lifetime){: #authentication-strategies-password-sign_in_token_lifetime } | `pos_integer \| {pos_integer, :days \| :hours \| :minutes \| :seconds}` | `{60, :seconds}` | A lifetime for which a generated sign in token will be valid, if `sign_in_tokens_enabled?`. Unit defaults to `:seconds`. |
|
|
|
|
|
|
## authentication.strategies.password.resettable
|
|
|
|
|
|
Configure password reset options for the resource
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
|
|
|
| Name | Type | Default | Docs |
|
|
|------|------|---------|------|
|
|
| [`sender`](#authentication-strategies-password-resettable-sender){: #authentication-strategies-password-resettable-sender .spark-required} | `(any, any, any -> any) \| module` | | The sender to use when sending password reset instructions. |
|
|
| [`token_lifetime`](#authentication-strategies-password-resettable-token_lifetime){: #authentication-strategies-password-resettable-token_lifetime } | `pos_integer \| {pos_integer, :days \| :hours \| :minutes \| :seconds}` | `{3, :days}` | How long should the reset token be valid. If no unit is provided `:hours` is assumed. |
|
|
| [`request_password_reset_action_name`](#authentication-strategies-password-resettable-request_password_reset_action_name){: #authentication-strategies-password-resettable-request_password_reset_action_name } | `atom` | | The name to use for the action which generates a password reset token. Defaults to `request_password_reset_with_<strategy_name>`. |
|
|
| [`password_reset_action_name`](#authentication-strategies-password-resettable-password_reset_action_name){: #authentication-strategies-password-resettable-password_reset_action_name } | `atom` | | The name to use for the action which actually resets the user's password. Defaults to `password_reset_with_<strategy_name>`. |
|
|
|
|
|
|
|
|
|
|
|
|
### Introspection
|
|
|
|
Target: `AshAuthentication.Strategy.Password.Resettable`
|
|
|
|
|
|
|
|
|
|
### Introspection
|
|
|
|
Target: `AshAuthentication.Strategy.Password`
|
|
|
|
|
|
|
|
<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>
|