Behaviour for handling authentication errors in the HTTP pipeline.

Implement this behaviour in your application to customize how authentication errors are presented to users. The generated MyAppWeb.AuthErrorHandler provides a default implementation.

Error Types

• :unauthenticated - No authenticated user found
• :stale_sudo - Sudo window has expired, re-authentication required
• :rate_limited - Request rate limit exceeded
• :insufficient_scope - Bearer token lacks the required scope
• :token_expired - API token has expired
• :token_revoked - API token was revoked
• :mfa_required - MFA enrollment or challenge required
• :no_active_org - No active organization on the scope (Phase 14 / D-08); the current request requires an org context but scope.active_organization is nil. Typically reached when the user has zero memberships or the stale-pointer recovery path left the scope unpopulated.
• :insufficient_role - Authenticated user's membership role is not in the required list for the requested resource (Phase 14 / D-08).

Example

defmodule MyAppWeb.AuthErrorHandler do
  @behaviour Sigra.Plug.ErrorHandler

  @impl true
  def auth_error(conn, :unauthenticated, _opts) do
    conn
    |> Phoenix.Controller.put_flash(:error, "You must log in to access this page.")
    |> Phoenix.Controller.redirect(to: "/login")
  end

  @impl true
  def auth_error(conn, :stale_sudo, _opts) do
    conn
    |> Phoenix.Controller.put_flash(:error, "Please re-enter your password to continue.")
    |> Phoenix.Controller.redirect(to: "/users/sudo")
  end

  @impl true
  def auth_error(conn, :rate_limited, _opts) do
    conn
    |> Plug.Conn.put_resp_content_type("text/plain")
    |> Plug.Conn.send_resp(429, "Too many requests. Please try again later.")
  end
end