A behaviour for looking up users and authenticating credentials.

Implementation

Simply use Authority.Authentication in your module:

defmodule MyApp.Accounts do
  use Authority.Authentication
end

This will define a MyApp.Accounts.authenticate/2 function, which will execute the following callback functions in this order:

• before_identify/1
• identify/1
• before_validate/2
• validate/3
• after_validate/2

If any of the callbacks return an {:error, term} response, the failed/2 callback will execute. The __using__/1 macro provides default, empty implementations of all the callbacks except validate/3, which you must implement yourself.

All the default callback implementations can be overriden.

Execution Flow

If you call authenticate/2 with an {email, password} tuple, the callbacks will proceed as follows:

  MyApp.Accounts.authenticate({"test@example.com", "password"})

  # Will execute...
  before_identify("test@example.com")

  # This should return a user matching the email address
  identify("test@example.com")

  # If you need to do any checks on the user prior to validating
  # the password, do them here
  before_validate(user, :any)

  # Verify that the given password is valid for the given user
  validate("password", user, :any)

  # Do any cleanup needed after a successful validation
  after_validate(user, :any)

The :any argument is the purpose of the authentication. It allows you to require different credentials for different purposes. It can be passed as the second argument to authenticate/2:

  # Sets the purpose to :recovery, e.g. account recovery
  MyApp.Accounts.authenticate({"test@example.com", "password"}, :recovery)

Example

defmodule MyApp.Accounts do
  use Authority.Authentication

  # OPTIONAL
  @impl Authority.Authentication
  def before_identify(identifier) do
    # Do anything you need to do to the identifier
    # before it is used to identify the user.
    # 
    # Return {:ok, identifier}
  end

  # REQUIRED
  @impl Authority.Authentication
  def identify(identifier) do
    # Identify the user
  end

  # OPTIONAL
  @impl Authority.Authentication
  def before_validate(user, purpose) do
    # Define any additional checks that should determine
    # if authentication is permitted.
    #
    # For example, check if the user is active or if the
    # account is locked.
  end

  # REQUIRED
  @impl Authority.Authentication
  def validate(credential, user, purpose) do
    # check if the credential is valid for the user
  end

  # OPTIONAL
  @impl Authority.Authentication
  def after_validate(user, purpose) do
    # Clean up after a successful authentication
  end

  # OPTIONAL
  @impl Authority.Authentication
  def failed(user, error) do
    # Do anything that needs to be done on failure, such as
    # locking the user account on too many failed attempts
  end
end