Authentication Verifier Documentation

The Authentication Verifier handles many authentication methods while providing a simple and consistent interface for API servers to validate client sessions.

Introduction

The Authentication Verifier's primary role is to provide login mechanisms that issue a session cookie, which external Auth API servers then use to validate each incoming request.

The server manages client authentication in isolated realms. The following authentication methods are currently implemented:

• Username and password (HTTP Basic Auth, Argon2id-hashed passwords)
• OAuth2, OpenID Connect: JWT bearer token (RS256 / ES256, JWKS-based)
• Client certificate (mTLS, EC P-256)
• Two-factor authentication using TOTP (RFC 6238)
• AppRole — machine-to-machine credentials; role_id + secret_id exchange for an opaque app token
• Kubernetes service-account — Kubernetes SA JWTs for workloads running inside a cluster
• Token self-service — lookup, renew, and revoke app tokens (all machine auth methods)

The following methods are planned for future implementation:

• Enterprise SSO using SAML
• Authentication using OpenID4 Verifiable Proofs (Decentralized Identity)
• Passwordless authentication (WebAuthn, Hardware Tokens)
• Two-factor authentication using WebAuthn, Hardware Tokens, or OOB (SMS/Email)

Once a client is authenticated, the server issues a session cookie which is returned to the client. This cookie is then used by the client to authenticate subsequent requests to an API server. The API server validates the session cookie with the Authentication Verifier to ensure the client is authenticated.

Note on Users vs Clients: Admin records (super admins and realm admins) are simply authenticated clients that also hold a Admin record granting them server-administration privileges. Every admin must still log in through the normal /login endpoint — there is no separate admin login path. A Admin record has no special meaning outside the Authentication Verifier's own administration APIs.

Authentication Flow

sequenceDiagram
    participant Client
    participant AuthServer
    participant API
    participant Service

    Client->>AuthServer: 1. Authenticate (credentials)
    AuthServer->>AuthServer: 2. Validate Credentials
    AuthServer->>Client: 3. Session Cookie
    Client->>API: 4. API Request + Session Cookie
    API->>AuthServer: 5. Validate Session
    AuthServer->>API: 6. Session Valid
    API->>Service: 7. Call Service
    Service->>API: 8. Service Response
    API->>Client: 9. Response

Flow Description:

1. Client authenticates with one of the supported methods (username/password, JWT bearer, or client certificate)
2. Authentication server validates the provided credentials
3. Upon successful validation, session cookie is issued to the client
4. Client makes API request, including the session cookie
5. API server validates the session with Authentication Verifier
6. Authentication server confirms session is valid
7. API server calls the requested service
8. Service returns response to API server
9. API server returns final response to client

Cross-Scheme Session Lookup and Forced Logout

Once a session has been validated on the Authentication Verifier, the API can use that session to query all active sessions belonging to the same client identity — regardless of which authentication scheme was used to create them. This enables scenarios such as enforcing a single active session, detecting concurrent logins from unexpected locations, or explicitly logging a client out from all other devices and methods.

The POST /sessions/realms/{realm}/clients endpoint accepts a list of AuthenticatedClientScheme entries — each combining a username with one of the supported authentication schemes (up, jwt, cc, f2, dc). It returns the matching session IDs across all those schemes. The API can then call DELETE /sessions with any subset of those IDs to selectively revoke them.

sequenceDiagram
    autonumber
    participant C as Client
    participant API as Your API
    participant EA as Authentication Verifier
    participant SS as Session Store

    C->>API: GET /api/resource<br/>Cookie: _ea_=<encrypted_jwt>
    note over API: CookieAuthSameServer middleware<br/>validates cookie → ClientClaims{username, auth_scheme}

    API->>EA: POST /sessions/realms/{realm}/clients<br/>[{username, auth_scheme: "up"},<br/> {username, auth_scheme: "cc"},<br/> {username, auth_scheme: "jwt"}]
    note over EA: Query session store for all sessions<br/>matching any of the provided schemes
    EA->>SS: get_sessions_for_clients(realm, schemes)
    SS-->>EA: [session_id_A, session_id_B, session_id_C, …]
    EA-->>API: {"session_ids": ["session_id_A", "session_id_B", …]}

    note over API: API decides which sessions to keep<br/>(e.g. keep the current one, revoke all others)

    API->>EA: DELETE /sessions<br/>{"session_ids": ["session_id_B", "session_id_C"]}
    note over EA: Immediately invalidates the listed sessions
    EA->>SS: delete_sessions([session_id_B, session_id_C])
    SS-->>EA: OK
    EA-->>API: 200 OK

    API-->>C: 200 OK  {"data": …}
    note over C: Other sessions (other devices / schemes)<br/>are now invalidated — those clients<br/>will receive 401 on their next request

Typical use cases:

• Single active session enforcement — after a successful login, revoke all other sessions for the same user to prevent concurrent access.
• Security event response — if anomalous activity is detected, revoke all sessions for a user across every authentication scheme in one call.
• Account takeover mitigation — when a password or certificate change is detected, force re-authentication everywhere by revoking all existing sessions.

Application Programming Interfaces (APIs)

The Authentication Verifier exposes a RESTful API.

The API is separated into 3 sections:

• the realm management API, open to super admins,
• the admin management API, open to realm admins,
• and the authentication API, open to all clients.

Administrator clients authenticate against the special _ realm. The API endpoint to authenticate is /login?realm={realm}.

Terminology

Documentation Index