Add protection to a Raxx application using Basic Authentication.

Basic Authentication is specified in RFC 7617 (which obsoletes RFC 2617).

This module provides helpers for submitting and verifying credentials.

Submitting credentials

A client (or test case) can add user credentials to a request with set_credentials/3

iex> request(:GET, "/")
...> |> set_credentials("Aladdin", "open sesame")
...> |> get_header("authorization")
"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

Verifying fixed credentials

A server can authenticate a request against a fixed set of credentials using authenticate/3

iex> request(:GET, "/")
...> |> set_header("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
...> |> authenticate("Aladdin", "open sesame")
{:ok, "Aladdin"}

iex> request(:GET, "/")
...> |> set_header("authorization", "Basic SmFmYXI6bXkgbGFtcA==")
...> |> authenticate("Aladdin", "open sesame")
{:error, :invalid_credentials}

Verifying multiple credentials

To authenticate a request when credentials are not fixed, define an application authenticate function. This function can authenticate a user in any way it wants. e.g. by fetching the user from the database. Extracting credentials from a received request can be done using get_credentials/1.

defmodule MyApp.Admin do
  def authenticate(request) do
    with {:ok, {user_id, password}} <- get_credentials(request) do
      # Find user and verify credentials
      {:ok, user}
    end
  end
end

NOTE: when comparing saved passwords with submitted passwords use secure_compare/2 to protect against timing attacks.

Challenging unauthorized requests

If a request is submitted with absent or invalid credentials a server should inform the client that it is accessing a resource protected with basic authentication. Use unauthorized/1 to create such a response.

NOTE

• The Basic authentication scheme is not a secure method of user authentication https://tools.ietf.org/html/rfc7617#section-4

• This module will be extracted to a separate project before the release of raxx 1.0