View Source AshAuthentication.Strategy.Password (ash_authentication v3.9.4)

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

Example:

defmodule MyApp.Accounts.User do
  use Ash.Resource,
    extensions: [AshAuthentication]

  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
    api MyApp.Accounts

    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

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

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" => "outatime1985", "password" => "outatime1985"})
...> user.username |> to_string()
"marty"

plugs

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-1

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)

dsl-documentation

DSL Documentation

Strategy for authenticating using local resources as the source of truth.

Examples:

password :password do
  identity_field :email
  hashed_password_field :hashed_password
  hash_provider AshAuthentication.BcryptProvider
  confirmation_required? true
end
  • :identity_field (atom/0) - The name of the attribute which uniquely identifies the user.
    Usually something like username or email_address. The default value is :username.

  • :hashed_password_field (atom/0) - The name of the attribute within which to store the user's password once it has been hashed. The default value is :hashed_password.

  • :hash_provider (atom/0) - A module which implements the AshAuthentication.HashProvider behaviour.
    Used to provide cryptographic hashing of passwords. The default value is AshAuthentication.BcryptProvider.

  • :confirmation_required? (boolean/0) - Whether a password confirmation field is required when registering or changing passwords. The default value is true.

  • :password_field (atom/0) - The name of the argument used to collect the user's password in plaintext when registering, checking or changing passwords. The default value is :password.

  • :password_confirmation_field (atom/0) - The name of the argument used to confirm the user's password in plaintext when registering or changing passwords. The default value is :password_confirmation.

  • :register_action_name (atom/0) - The name to use for the register action.
    If not present it will be generated by prepending the strategy name with register_with_.

  • :sign_in_action_name (atom/0) - The name to use for the sign in action.
    If not present it will be generated by prepending the strategy name with sign_in_with_.

resettable

resettable

Configure password reset options for the resource

  • :token_lifetime (pos_integer/0) - How long should the reset token be valid, in hours.
    Defaults to 3 days. The default value is 72.

  • :request_password_reset_action_name (atom/0) - The name to use for the action which generates a password reset token.
    If not present it will be generated by prepending the strategy name with request_password_reset_with_.

  • :password_reset_action_name (atom/0) - The name to use for the action which actually resets the user's password.
    If not present it will be generated by prepending the strategy name with password_reset_with_.

  • :sender - Required. How to send the password reset instructions to the user.
    Allows you to glue sending of reset instructions to swoosh, ex_twilio or whatever notification system is appropriate for your application.
    Accepts a module, module and opts, or a function that takes a record, reset token and options.
    See AshAuthentication.Sender for more information.

Link to this section Summary

Functions

See AshAuthentication.Strategy.Password.Dsl.dsl/0.

Generate a reset token for a user.

Link to this section Types

@type t() :: %AshAuthentication.Strategy.Password{
  confirmation_required?: boolean(),
  hash_provider: module(),
  hashed_password_field: atom(),
  identity_field: atom(),
  name: atom(),
  password_confirmation_field: atom(),
  password_field: atom(),
  provider: atom(),
  register_action_name: atom(),
  resettable: [AshAuthentication.Strategy.Password.Resettable.t()],
  resource: module(),
  sign_in_action_name: atom()
}

Link to this section Functions

See AshAuthentication.Strategy.Password.Dsl.dsl/0.

Link to this function

reset_token_for(strategy, user)

View Source
@spec reset_token_for(t(), Ash.Resource.record()) :: {:ok, String.t()} | :error

Generate a reset token for a user.

Used by AshAuthentication.Strategy.Password.RequestPasswordResetPreparation.

Link to this function

transform(entity, dsl_state)

View Source

Callback implementation for AshAuthentication.Strategy.Custom.transform/2.

Link to this function

verify(strategy, dsl_state)

View Source

Callback implementation for AshAuthentication.Strategy.Custom.verify/2.