Haytni.LockablePlugin (Haytni v0.7.0) 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)

Configuration:

maximum_attempts (default: 20): the amount of successive attempts to login before locking the corresponding account
unlock_keys (default: [:email]): the field(s) to match to accept the unlock request
unlock_in (default: {1, :hour}): delay to automatically unlock the account
unlock_within (default: {3, :day}): delay after which unlock token is considered as expired (ie the user has to request a new one)
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_within: {3, :day},
  unlock_strategy: :both,
  unlock_keys: [:email]
```

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

email_strategy_disabled_message()

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.

email_strategy_enabled?(config)

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

find_user(conn, module, config)

Callback implementation for Haytni.Plugin.find_user/3.

invalid_token_message()

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

last_attempt?(user, config)

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

lock_attributes()

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

lock_user(module, user)

Allows a privilegied user (administrator) to manually lock a user.

locked?(user, config)

Returns true if user account is currently locked.

on_delete_user(multi, user, module, config)

Callback implementation for Haytni.Plugin.on_delete_user/4.

on_email_change(multi, changeset, module, config)

Callback implementation for Haytni.Plugin.on_email_change/4.

on_logout(conn, module, config)

Callback implementation for Haytni.Plugin.on_logout/3.

on_registration(multi, module, config)

Callback implementation for Haytni.Plugin.on_registration/3.

resend_unlock_instructions(module, config, request_params)

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

unlock(module, config, token)

Unlock an account from a URL base64 encoded unlock token.

unlock_attributes()

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

unlock_request_changeset(config, request_params \\ %{})

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

unlock_user(module, user)

Allows a privilegied user (administrator) to manually unlock a user.

validate_create_registration(changeset, module, config)

Callback implementation for Haytni.Plugin.validate_create_registration/3.

validate_password(changeset, module, config)

Callback implementation for Haytni.Plugin.validate_password/3.

validate_update_registration(changeset, module, config)

Callback implementation for Haytni.Plugin.validate_update_registration/3.

Link to this section Functions

email_strategy_disabled_message()

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.

email_strategy_enabled?(config)

Specs

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

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

find_user(conn, module, config)

Callback implementation for Haytni.Plugin.find_user/3.

invalid_token_message()

Specs

invalid_token_message() :: String.t()

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

last_attempt?(user, config)

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

lock_attributes()

Specs

lock_attributes() :: Keyword.t()

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

lock_user(module, user)

Specs

lock_user(module :: module(), user :: Haytni.user()) ::
  Haytni.repo_nobang_operation(Haytni.user())

Allows a privilegied user (administrator) to manually lock a user.

locked?(user, config)

Specs

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

Returns true if user account is currently locked.

on_delete_user(multi, user, module, config)

Callback implementation for Haytni.Plugin.on_delete_user/4.

on_email_change(multi, changeset, module, config)

Callback implementation for Haytni.Plugin.on_email_change/4.

on_logout(conn, module, config)

Callback implementation for Haytni.Plugin.on_logout/3.

on_registration(multi, module, config)

Callback implementation for Haytni.Plugin.on_registration/3.

resend_unlock_instructions(module, config, request_params)

Specs

resend_unlock_instructions(
  module :: module(),
  config :: Haytni.LockablePlugin.Config.t(),
  request_params :: Haytni.params()
) :: {:ok, Haytni.nilable(Haytni.user())} | {:error, Ecto.Changeset.t()}

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

Returns:

{:ok, nil}: no one matches config.unlock_keys or the account is not currently locked
{:ok, user}: an email has been sent
{:error, changeset}: form fields are invalid (empty) or :email (reminder: included by :both) strategy is disabled

unlock(module, config, token)

Specs

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

Unlock an account from a URL base64 encoded unlock token.

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

unlock_attributes()

Specs

unlock_attributes() :: Keyword.t()

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

unlock_request_changeset(config, request_params \\ %{})

Specs

unlock_request_changeset(
  config :: Haytni.LockablePlugin.Config.t(),
  request_params :: Haytni.params()
) :: Ecto.Changeset.t()

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

unlock_user(module, user)

Specs

unlock_user(module :: module(), user :: Haytni.user()) ::
  Haytni.repo_nobang_operation(Haytni.user())

Allows a privilegied user (administrator) to manually unlock a user.

validate_create_registration(changeset, module, config)

Callback implementation for Haytni.Plugin.validate_create_registration/3.

validate_password(changeset, module, config)

Callback implementation for Haytni.Plugin.validate_password/3.

validate_update_registration(changeset, module, config)

Callback implementation for Haytni.Plugin.validate_update_registration/3.