Ankusa.Admin.Auth behaviour (ankusa v0.7.0)

Authentication and authorization for the three control planes: the admin API (Ankusa.Admin.Router), the route-management API (Ankusa.Routes.Router) and the claim-check gateway (Ankusa.ClaimCheck.Router).

Each router mounts this module as a plug ahead of :match. The plug authenticates the request, assigns the Ankusa.Principal to conn.assigns.principal and halts with 401 when there is none; each route then calls authorize/3, authorize_tenant/4 or authorize_global/3 for the scope it needs, which answers 403 otherwise. GET /health and GET /ready are exempt: probes carry no credentials.

Modes

Each listener has its own auth block (admin.auth, routes.admin.auth, claim_check.auth):

%{
  mode: :none | :token | :jwt | :mtls,
  allow_insecure: false,
  tokens: [%{id: "ci", sha256: "<64 hex>", scopes: ["dlq:read", "tenant:*"]}],
  jwt: %{issuer: ..., audience: ..., jwks_url: ..., keys: [...], ...},
  mtls: %{subject_map: %{"cn:ops-laptop" => ["dlq:read", "tenant:*"]}}
}

:none (the default) authenticates nobody and hands every request the all-powerful Ankusa.Principal.operator/1. It is only accepted when the listener binds loopback: Ankusa.Config.new/1 refuses mode: :none on any other address unless allow_insecure: true says the deployment is protected by something else (a mesh, a proxy, a network policy). Even tls.verify: :verify_peer does not count: it keeps strangers off the port but does not say what a certificate may do; use mode: :mtls.
:token — Ankusa.Admin.Auth.Token: static bearer tokens, stored as SHA-256 hashes, each with its scopes. For development, CI and machine-to-machine scripts.
:jwt — Ankusa.Admin.Auth.JWT: OIDC/OAuth2 access tokens signed by your identity provider, verified against its JWKS.
:mtls — Ankusa.Admin.Auth.MTLS: the verified client certificate of a tls.verify: :verify_peer listener, mapped to a principal by subject. Requires that listener's tls block.

Further modes are modules implementing authenticate/2.

Responses

401 {"error":"unauthenticated"} with www-authenticate: Bearer realm="ankusa" when no credential, or a bad one, was presented. The response never says which.
403 {"error":"forbidden","scope":"dlq:read"} when the principal lacks the named scope. A tenant scope names tenant:<id>.

Summary

Types

opts()

What an implementation of authenticate/2 is given.

section()

Which control plane the plug guards.

Callbacks

authenticate(t, opts)

Identify the caller of conn: a principal, or {:error, :unauthenticated} for a missing, malformed, expired or unknown credential. opts.config is the listener's normalised auth block.

Functions

auth_config(config, atom)

The auth block of the control plane section.

authorize(conn, scope, fun)

Run fun when the principal holds scope (or every scope in a list), else answer 403.

authorize_global(conn, scope, fun)

authorize/3 for a resource that spans tenants (the DLQ, the quarantine pen, replay jobs, route definitions): the principal must also hold tenant:*.

authorize_tenant(conn, scope, tenant, fun)

authorize/3 for a resource that belongs to one tenant: the principal must also hold tenant:<tenant> or tenant:*.

authorize_tenants(conn, scope, requested, fun)

authorize/3 for a resource that spans tenants but is filtered by tenant (the DLQ, the quarantine pen, replay jobs, the rate-limit listing).

bearer(conn)

The bearer token of conn: exactly one Authorization: Bearer <token> header, the scheme matched case-insensitively. A bare or oversized token, a second header, or another scheme is :error.

normalize!(auth, key, map, enabled?)

Validate and normalise one auth block of a listener. key is its dotted config name ("admin.auth") and listener the section it sits in (its ip and tls are what mode: :none and mode: :mtls are checked against). enabled? says whether this instance runs the listener: a listener that is not started is not held to the loopback rule. Raises ArgumentError naming the key.

secure_compare(a, b)

Constant-time comparison of two equal-length binaries.