Integration drift creates security bugs
Teams often ship OAuth flows with inconsistent redirect validation, weak state handling, or frontend token exchange shortcuts.
Zero-knowledge authentication
Build login around proof, not secret custody.
ZKAuth provides a production OAuth Authorization Code integration surface with PKCE, backend token exchange, and JWKS-based verification so teams can ship secure login without guessing protocol boundaries.
15mcurrent access token lifetime (`expires_in`)
3public integration endpoints (authorize, token, JWKS)
1stable identity anchor for local mapping (`sub`)
One system. Zero custody.
VALIDATE PROOF, NOT SECRETS.
The implementation path is explicit: authorize in browser, exchange code in backend, verify JWT through JWKS, then map `sub` into your local user/session model.
Authorization Code + PKCEBackend-only token exchangeVerify JWT via JWKS
Why change authentication architecture
Credential custody should not be your default risk model.
The public guide mirrors current backend behavior so teams can avoid fragile assumptions and implement a reproducible secure flow from day one.
Assumed claims break production
Relying on non-guaranteed token fields like username/email leads to brittle account binding and rollout regressions.
Feature assumptions outpace platform reality
Depending on unavailable userinfo/refresh token capabilities introduces hidden coupling and delayed release risk.
Core design
A threat model built for breach containment.
Security posture comes from deterministic contracts: strict redirect matching, state validation, PKCE where required, backend-only code exchange, and claim validation.
Strict authorize contract
Frontend sends exact redirect_uri, high-entropy state, and PKCE parameters for public clients.
Backend token exchange
Authorization code exchange happens server-to-server with client credentials and optional code_verifier.
Deterministic token validation
Client backend verifies RS256 signatures through JWKS and validates issuer, audience, and expiry claims.
Session mapping boundary
Applications bind only the `sub` claim to local users and maintain authorization logic in their own domain.
Use cases
Where teams deploy this model
These implementation tracks map directly to real delivery teams: frontend auth redirects, backend token handling, and security validation gates in application infrastructure.
Client onboarding teams
Launch app registration through admin-managed or self-service provisioning with explicit credential outputs.
Backend platform squads
Centralize token exchange and claim validation in secure services instead of browser-facing code.
Security and compliance reviewers
Audit flow contracts where state, redirect URI matching, PKCE, and JWT verification are unambiguous.
Migration-heavy product orgs
Adopt the flow incrementally while keeping existing authorization and local session semantics intact.
Roll out in controlled stages
- Register client metadata: exact redirect URI, client type, and onboarding ownership mode.
- Implement frontend redirect to `/api/oauth/authorize` with `response_type=code`, `state`, and PKCE S256 when applicable.
- Validate callback state server-side and treat authorization code as short-lived single use.
- Exchange code at `/api/oauth/token` from backend only with `client_id`, `client_secret`, and `code_verifier` when used.
- Verify access token through JWKS, map `sub` locally, and issue your own app session boundary.
Public docs should stay public-safe
- Treat `client_secret` and private keys as backend-only assets; never expose in frontend bundles.
- Do not depend on uncommitted capabilities such as refresh tokens or userinfo for core login logic.
- Base local identity mapping on `sub` and validate issuer/audience/expiry on every token acceptance path.
FAQ
Common architecture and rollout questions
Does this replace OAuth, SSO, or your IdP?
No. The documented flow is OAuth Authorization Code. ZKAuth provides the identity authorization surface while your app keeps local session and authorization ownership.
Which token claims should we trust for user mapping?
Use `sub` as the stable local identity anchor. Validate RS256 signature and enforce `iss`, `aud`, and `exp` before creating an app session.
Where should token exchange happen?
Only in backend services. Frontend code should redirect for authorization but must not call the token endpoint with confidential credentials.
What limitations should teams design around today?
Assume token exchange currently requires `client_secret`, and treat refresh token and userinfo-driven flows as unavailable until explicitly documented.