Alexandria
API & Development

Authentication & Authorization

How alexandria-server authenticates OAuth 2.0 access tokens (A1–A5), authorizes operations with the admin role and namespace stewards, and how the laboratory identity provider works.

Authentication & Authorization

alexandria-server is an OAuth 2.0 resource server. It never issues tokens or handles passwords: it validates JWT access tokens (RFC 9068, type at+jwt) issued by the identity providers listed in its configuration.

The client admin API is unauthenticated and relies on being bound to its own listener.


1. Token Validation

Checks run in order (REQ-HUB-022); the first failure answers 401, API_UNAUTHENTICATED and WWW-Authenticate: Bearer error="invalid_token".

CheckRule
A1JWT of type at+jwt, signed with an allowed asymmetric algorithm.
A2Issuer listed in auth.issuers.
A3Signature verifies with a key of the issuer's JWKS, located through its discovery document. An unknown kid triggers one JWKS refresh.
A4Audience contains auth.audience.
A5Not expired and not used before nbf, within clock_skew.

The principal of a valid token is the pair iss + sub. It is admin when the claim named by auth.admin_claim.claim (default roles) contains auth.admin_claim.value (default vhub-admin).

A request without Authorization is anonymous and may use public endpoints. A request with an invalid token is always rejected, even on a public endpoint.


2. Authorization

OperationRule
Public readsAlways allowed.
Namespace creation, steward assignment and removal, hub-wide eventsAdmin only.
Listing the stewards of a namespaceAdmin or a steward of it.
Everything else inside a namespaceA steward of that namespace. The admin role alone is not enough.

Missing token: 401. Valid token without permission: 403, API_FORBIDDEN_ROLE. Steward membership is read on every request, so assigning or removing a steward takes effect immediately (REQ-HUB-023).

There is no four-eyes rule in this version: the steward who proposes a candidate may also approve it.


3. Laboratory Identity Provider (fake-idp)

deploy/fake-idp replaces a real provider in the laboratory (DP-4). The hub validates its tokens through the same JWKS path as any other issuer.

./bin/fake-idp serve                                   # http://127.0.0.1:9400
./bin/fake-idp token --sub ana --admin --ttl 24h       # admin token
./bin/fake-idp token --sub sergio --ttl 24h            # plain principal

serve implements OIDC Discovery, the JWKS and an interactive Authorization Code flow with PKCE (a password-less subject picker, /token with rotating refresh tokens and /logout), which is what the console uses to sign in. Flags: --addr, --issuer, --key, --ttl, --clock-file.

token prints one access token. Flags: --sub, --admin, --aud, --ttl, --clock-file. Both subcommands must use the same --key file, which is created on first use.

fake-idp lets anyone become any subject. It only redirects to loopback addresses and is strictly a laboratory tool.


4. Using a Real Provider

  1. Add the provider to auth.issuers (section layout: auth_config.issuer) and set the audience.
  2. Make the provider emit access tokens as JWTs with that audience.
  3. Map the admin role into the configured claim.
  4. Assign stewards by the iss and sub their tokens carry.

Browser clients such as the console additionally need a public client registration with PKCE and, when the console is embedded in the hub, CORS for the hub origin.

On this page