KeenAuth.AuthenticationController behaviour (KeenAuth v1.0.1)

Copy Markdown View Source

Handles the OAuth authentication flow for KeenAuth.

This controller provides the core endpoints for OAuth authentication:

  • new/2 - Initiates the OAuth flow by redirecting to the provider
  • callback/2 - Handles the OAuth callback from the provider
  • delete/2 - Signs out the user

Usage

You can use this controller directly via KeenAuth.authentication_routes/0 or create your own controller that uses this module:

defmodule MyAppWeb.AuthController do
  use KeenAuth.AuthenticationController

  # Override any callback as needed
  def callback(conn, params) do
    # Custom logic before
    result = super(conn, params)
    # Custom logic after
    result
  end
end

Authentication Flow

  1. User visits /auth/:provider/new
  2. Controller redirects to OAuth provider with authorization URL
  3. Provider redirects back to /auth/:provider/callback
  4. Controller processes the callback through the pipeline:
    • Strategy fetches user data from provider
    • Mapper normalizes the user data
    • Processor handles business logic (validation, database, etc.)
    • Storage persists the session
  5. User is redirected to the original destination

Summary

Types

oauth_callback_response()
tokens_map()

Callbacks

callback(conn, any)
delete(conn, any)
new(conn, any)

Functions

callback(conn, params)

Handles the OAuth callback from the provider.

delete(conn, params)

Signs out the user by delegating to the processor's sign_out/3 callback.

get_authorization_uri(conn, provider)
make_callback_back(conn, provider, params, session_params \\ %{})
map_user(conn, provider, user)
maybe_put_redirect_to(conn, params)
new(conn, params)

Initiates the OAuth flow by redirecting to the provider's authorization URL.

process(conn, provider, mapped_user, oauth_result)
store(conn, provider, mapped_user, oauth_response)

Types

oauth_callback_response()

@type oauth_callback_response() :: %{
  user: KeenAuth.User.t() | map(),
  token: tokens_map()
}

tokens_map()

@type tokens_map() :: %{
  optional(:access_token) => binary(),
  optional(:id_token) => binary(),
  optional(:refresh_token) => binary()
}

Callbacks

callback(conn, any)

@callback callback(conn :: Plug.Conn.t(), any()) :: Plug.Conn.t()

delete(conn, any)

@callback delete(conn :: Plug.Conn.t(), any()) :: Plug.Conn.t()

new(conn, any)

@callback new(conn :: Plug.Conn.t(), any()) :: Plug.Conn.t()

Functions

callback(conn, params)

Handles the OAuth callback from the provider.

Processes the authentication response through the full pipeline:

  1. Validates the OAuth callback and fetches user data
  2. Maps the raw user data to a normalized format
  3. Processes the user through custom business logic
  4. Stores the authentication in the configured storage

On success, redirects the user to their original destination.

delete(conn, params)

Signs out the user by delegating to the processor's sign_out/3 callback.

If a provider is specified in params, uses that provider. Otherwise, retrieves the provider from storage. Redirects back if no user is signed in.

get_authorization_uri(conn, provider)

@spec get_authorization_uri(Plug.Conn.t(), atom()) ::
  {:ok, %{session_params: map(), url: binary()}}

make_callback_back(conn, provider, params, session_params \\ %{})

@spec make_callback_back(Plug.Conn.t(), atom(), map(), map()) ::
  {:ok, oauth_callback_response()}

map_user(conn, provider, user)

@spec map_user(Plug.Conn.t(), atom(), map()) :: KeenAuth.User.t()

maybe_put_redirect_to(conn, params)

@spec maybe_put_redirect_to(Plug.Conn.t(), map()) :: Plug.Conn.t()

new(conn, params)

Initiates the OAuth flow by redirecting to the provider's authorization URL.

Stores session parameters and optional redirect URL, then redirects the user to the OAuth provider for authentication.

process(conn, provider, mapped_user, oauth_result)

@spec process(Plug.Conn.t(), atom(), KeenAuth.User.t() | map(), any()) :: any()

store(conn, provider, mapped_user, oauth_response)

@spec store(
  Plug.Conn.t(),
  atom(),
  KeenAuth.User.t() | map(),
  oauth_callback_response()
) :: any()