Haytni v0.6.1 Haytni.AuthenticablePlugin View Source

This is a base plugin as it handles basic informations of a user (which are email and hashed password) and their authentication.

Fields:

  • email (string)
  • encrypted_password (string)

Configuration:

  • authentication_keys (default: ~W[email]a): the key(s), in addition to the password, requested to login. You can redefine it to ~W[name]a, for example, to ask the username instead of its email address.
  • password hashing algorithm (default: bcrypt):
    • password_hash_fun (default: &Bcrypt.hash_pwd_salt/1): the function to hash a password
    • password_check_fun (default: &Bcrypt.check_pass/3): the function to check if a password matches its hash

To use:

* `pbkdf2` add `{:pbkdf2_elixir, "~> 1.0"}` as `deps` to your `mix.exs` then set `password_hash_fun` to `&Pbkdf2.hash_pwd_salt/1` and `password_check_fun` to `&Pbkdf2.check_pass/2` in config/config.exs
* `argon2` add `{:argon2_elixir, "~> 2.0"}` as `deps` to your `mix.exs` then set `password_hash_fun` to `&Argon2.hash_pwd_salt/1` and `password_check_fun` to ` &Argon2.check_pass/2` in config/config.exs

      stack Haytni.AuthenticablePlugin,
        authentication_keys: ~W[email]a,
        password_check_fun: &Bcrypt.check_pass/3,
        password_hash_fun: &Bcrypt.hash_pwd_salt/1

Routes:

  • haytni_<scope>_session_path (actions: new/create, delete): the generated routes can be customized through the following parameters when you call YourAppWeb.Haytni.routes/1:

    • login_path (default: "/session"): custom path assigned to the sign-in route
    • logout_path (default: same value as login_path): the path for th sign out route
    • logout_method (default: :delete): the HTTP method to use for the user to log out, in case where the default DELETE method were not well supported by your clients
    # lib/your_app_web/router.ex
    defmodule YourAppWeb.Router do
      # ...
      scope ... do
        YourAppWeb.Haytni.routes(
          login_path: "/login",
          logout_path: "/logout",
          logout_method: :get
        )
      end
      # ...
    end

Link to this section Summary

Functions

Returns true if password matches user's current hash (encrypted_password field)

Hashes a password.

Callback implementation for Haytni.Plugin.invalid?/2.

The translated string to display when credentials (password and/or email by default) are wrong.

Callback implementation for Haytni.Plugin.on_logout/2.

Converts the parameters received for authentication by the controller in a %Ecto.Changeset{} to handle and validate user inputs according to plugin's configuration (authentication_keys).

Link to this section Functions

Link to this function

authenticate(conn, module, config, session_params)

View Source

Specs

authenticate(
  conn :: Plug.Conn.t(),
  module :: module(),
  config :: Haytni.AuthenticablePlugin.Config.t(),
  session_params :: %{optional(String.t()) => String.t()}
) :: {:ok, Plug.Conn.t()} | {:error, Ecto.Changeset.t()}

Authentificates a user.

Returns:

  • {:ok, user} if crendentials are correct and user is valid
  • {:error, changeset} if credentials are incorrect or user is invalid (rejected by a Haytni.Plugin.invalid? callback by a plugin in the stack)
Link to this function

check_password(user, password, config, options \\ [])

View Source

Specs

check_password(
  user :: Haytni.user() | nil,
  password :: String.t(),
  config :: Haytni.AuthenticablePlugin.Config.t(),
  options :: Keyword.t()
) :: {:ok, Haytni.user()} | {:error, String.t()}

Returns true if password matches user's current hash (encrypted_password field)

options is a keyword-list passed to Comeonin:

  • hide_user (boolean, default: true): if not false, protects against timing attacks
  • hash_key (atom, looks by default for a password_hash and encrypted_password key): the name of the key containing the hash in user
Link to this function

find_user(conn, module, config)

View Source

Callback implementation for Haytni.Plugin.find_user/3.

Link to this function

hash_password(password, config)

View Source

Specs

hash_password(
  password :: String.t(),
  config :: Haytni.AuthenticablePlugin.Config.t()
) :: String.t()

Hashes a password.

Returns the hash of the password after having hashed it with config.password_hash_fun

Callback implementation for Haytni.Plugin.invalid?/2.

Link to this function

invalid_credentials_message()

View Source

Specs

invalid_credentials_message() :: String.t()

The translated string to display when credentials (password and/or email by default) are wrong.

Link to this function

on_email_change(multi, changeset, module, config)

View Source

Callback implementation for Haytni.Plugin.on_email_change/4.

Link to this function

on_failed_authentication(user, multi, keywords, module, config)

View Source

Callback implementation for Haytni.Plugin.on_failed_authentication/5.

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

on_successful_authentication(conn, user, multi, keywords, config)

View Source

Callback implementation for Haytni.Plugin.on_successful_authentication/5.

Link to this function

session_changeset(config, session_params \\ %{})

View Source

Specs

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

Converts the parameters received for authentication by the controller in a %Ecto.Changeset{} to handle and validate user inputs according to plugin's configuration (authentication_keys).

Link to this function

validate_password(changeset, config)

View Source

Callback implementation for Haytni.Plugin.validate_password/2.