How it works

Stateless by design

Hub holds no session database. All state lives in Vault-signed tokens or short-lived, single-use cookies. Compromising the Hub process does not compromise the user population.

Token flow

Your client redirects the user to /oauth2/authorize (optionally via PAR for confidential clients, per RFC 9126). Hub determines which federation member the client uses and redirects there for authentication. The federation member authenticates the user and redirects back with a code. Hub exchanges the code, sets a short-lived FED_TOKEN cookie, and redirects back to /oauth2/authorize to finish issuing the authorization code. The client exchanges the code at /oauth2/token for access + refresh tokens, signed via HashiCorp Vault Transit.

PAR + PKCE

PAR (RFC 9126) lets confidential clients push the authorization request to the back channel, preventing request-object tampering in the browser. PKCE (RFC 7636) protects public clients from authorization-code interception. Hub supports both; a client can enable PAR to harden the flow for regulated use cases.

Federation-member discovery

Each OAuth2 client is mapped to a federation member — Okta, Azure AD, your identity service, or any OIDC-conformant IdP. Discovery happens at authorize time; the user is redirected to the member, authenticates, and returns with an ID token that Hub validates against the member's JWKS.

Refresh-token families

Tokens are issued in families. When a stolen refresh token is used, Hub detects the family mismatch and revokes the entire lineage, making all tokens in that family invalid. Strict rotation (new refresh token on every use) is configurable per client. Family tracking lives in Redis for multi-node correctness.

Vault Transit signing

Every JWT signature goes through HashiCorp Vault Transit. Hub never holds the private keys — a compromised Hub process cannot forge tokens. The trade-off is a Vault round-trip per token; acceptable for interactive flows.