Protocol deep dive

Four steps from user input to authenticated proof.

The implementation handshake is intentionally explicit. Each phase maps directly to the production OAuth contracts documented in the integration guide.

Handshake timeline

Each step has one purpose: authorize safely, exchange tokens in backend, and validate identity before app-session binding.

01

Authorization redirect request

Client frontend redirects to `/api/oauth/authorize` with `client_id`, exact `redirect_uri`, `response_type=code`, `state`, and PKCE fields when required.

02

User authentication and consent

ZKAuth Identity authenticates the user, validates consent context, and returns a short-lived single-use authorization code to the registered callback.

03

Backend token exchange

Client backend validates state and exchanges the code at `/api/oauth/token` with `client_id`, `client_secret`, and `code_verifier` when PKCE is used.

04

JWT verification and local session bind

Backend verifies RS256 signature via JWKS, enforces `iss/aud/exp`, maps `sub` to local user identity, then issues app-specific session state.

Boundary checklist

Successful rollout depends on precise ownership boundaries between frontend redirects, backend token handling, and application authorization.

  • ZKAuth responsibility: authorize flow, consent, auth code issuance, and signing keys exposure through JWKS.
  • Client frontend responsibility: state generation, PKCE challenge generation, and safe redirect handling.
  • Client backend responsibility: token exchange, JWT validation, and local `sub` identity mapping.
  • Application responsibility: authorization policy, permissions, account recovery, and abuse controls.

Implementation guidance

Redirect contract discipline

Register exact redirect URIs only and reject wildcard or loosely matched callback values in all environments.

State and PKCE enforcement

Generate high-entropy state values, validate them exactly on callback, and enforce PKCE S256 for public clients.

Token validation policy

Fail closed on signature/claim validation errors and avoid using non-guaranteed claims like username/email as stable identifiers.

Current caveat handling

Design token exchange around current `client_secret` requirement and avoid depending on refresh/userinfo paths until released.

Continue to security posture

Pair flow implementation with the security boundary and caveat model before promoting to production.

Review security architecture