Haytni v0.6.1 Haytni.LockablePlugin View Source

This plugin locks an account after a specified number of failed sign-in attempts. User can unlock its account via email and/or after a specified time period.

Fields:

  • failed_attempts (integer, default: 0): the current count of successive failures to login
  • locked_at (datetime@utc, nullable, default: NULL): when the account was locked (NULL while the account is not locked)
  • unlock_token (string, nullable, unique, default: NULL): the token send to the user to unlock its account

Configuration:

  • maximum_attempts (default: 20): the amount of successive attempts to login before locking the corresponding account

  • unlock_token_length (default: 32): the length of the generated token

  • unlock_keys (default: ~W[email]a): the field(s) to match to accept the unlock request

  • unlock_in (default: {1, :hour}): delay to automatically unlock the account

  • unlock_strategy (default: :both): strategy used to unlock an account. One of:

    • :email: sends an unlock link to the user email
    • :time: re-enables login after a certain amount of time (see :unlock_in below)
    • :both: enables both strategies
    • :none: no unlock strategy. You should handle unlocking by yourself.
      stack Haytni.LockablePlugin,
        maximum_attempts: 20,
        unlock_in: {1, :hour},
        unlock_strategy: :both,
        unlock_keys: ~W[email]a,
        unlock_token_length: 32

Routes:

  • haytni_<scope>_unlock_path (actions: new/create, show): default path is "/unlock" but you can override it by the :unlock_path option when calling YourApp.Haytni.routes/1 from your router (eg: YourApp.Haytni.routes(unlock_path: "/unblock"))

Link to this section Summary

Functions

The translated string to display when email strategy is switched off for someone who would want to request an unlock token or have previously received one by email.

Returns true if :email strategy (included in :both) is enabled

The translated string to display when an unlock token is invalid (ie not associated to someone)

Returns true if it's the last attempt before account locking in case of a new sign-in failure

The (database) attributes as a keyword-list to turn a user as a locked account

Returns true if user account is currently locked.

The translated string to display when a user request a token while he is not currently locked

Callback implementation for Haytni.Plugin.on_logout/2.

Resend, by email, the instructions to unlock an account.

Unlock an account from an unlock token.

The (database) attributes as a keyword-list to turn an account to unlocked state

Converts the "raw" parameters received by the controller to request a new token to unlock its account to an %Ecto.Changeset{}

Link to this section Functions

Link to this function

email_strategy_disabled_message()

View Source

Specs

email_strategy_disabled_message() :: String.t()

The translated string to display when email strategy is switched off for someone who would want to request an unlock token or have previously received one by email.

Link to this function

email_strategy_enabled?(config)

View Source

Specs

email_strategy_enabled?(config :: Haytni.LockablePlugin.Config.t()) :: boolean()

Returns true if :email strategy (included in :both) is enabled

Link to this function

find_user(conn, module, config)

View Source

Callback implementation for Haytni.Plugin.find_user/3.

Specs

invalid_token_message() :: String.t()

The translated string to display when an unlock token is invalid (ie not associated to someone)

Link to this function

last_attempt?(user, config)

View Source

Specs

last_attempt?(user :: Haytni.user(), config :: Haytni.LockablePlugin.Config.t()) ::
  boolean()

Returns true if it's the last attempt before account locking in case of a new sign-in failure

Specs

lock_attributes(config :: Haytni.LockablePlugin.Config.t()) :: Keyword.t()

The (database) attributes as a keyword-list to turn a user as a locked account

Specs

locked?(user :: Haytni.user(), config :: Haytni.LockablePlugin.Config.t()) ::
  boolean()

Returns true if user account is currently locked.

Specs

not_locked_message() :: String.t()

The translated string to display when a user request a token while he is not currently locked

Link to this function

on_email_change(multi, changeset, module, config)

View Source

Callback implementation for Haytni.Plugin.on_email_change/4.

Callback implementation for Haytni.Plugin.on_logout/2.

Link to this function

on_registration(multi, module, config)

View Source

Callback implementation for Haytni.Plugin.on_registration/3.

Link to this function

resend_unlock_instructions(module, config, request_params)

View Source

Specs

resend_unlock_instructions(
  module :: module(),
  config :: Haytni.LockablePlugin.Config.t(),
  request_params :: %{optional(String.t()) => String.t()}
) :: {:ok, nil | Haytni.user()} | {:error, Ecto.Changeset.t()}

Resend, by email, the instructions to unlock an account.

Returns:

  • {:error, :email_strategy_disabled} if :email strategy is disabled
  • {:error, changeset} if there is no such account matching config.unlock_keys or if the account is not currently locked (changeset.errors is set consequently)
  • {:ok, user} if successful

In strict mode (config :haytni, mode: :strict), returned values are different:

  • {:error, :email_strategy_disabled} if :email strategy is disabled
  • {:error, changeset} if (form) fields are empty
  • {:ok, nil} if no one matches config.unlock_keys or if the account is not currently locked
  • {:ok, user} if successful (meaning an email has been sent)
Link to this function

unlock(module, config, token)

View Source

Specs

unlock(
  module :: module(),
  config :: Haytni.LockablePlugin.Config.t(),
  token :: String.t()
) :: {:ok, Haytni.user()} | {:error, String.t()}

Unlock an account from an unlock token.

Returns the user as {:ok, user} if the token exists and {:error, message} if not.

Specs

unlock_attributes() :: Keyword.t()

The (database) attributes as a keyword-list to turn an account to unlocked state

Link to this function

unlock_request_changeset(config, request_params \\ %{})

View Source

Specs

unlock_request_changeset(
  config :: Haytni.LockablePlugin.Config.t(),
  request_params :: %{required(String.t()) => String.t()}
) :: Ecto.Changeset.t()

Converts the "raw" parameters received by the controller to request a new token to unlock its account to an %Ecto.Changeset{}

Link to this function

validate_create_registration(changeset, config)

View Source

Callback implementation for Haytni.Plugin.validate_create_registration/2.

Link to this function

validate_password(changeset, config)

View Source

Callback implementation for Haytni.Plugin.validate_password/2.

Link to this function

validate_update_registration(changeset, config)

View Source

Callback implementation for Haytni.Plugin.validate_update_registration/2.