IESF Central Auth Gateway

English integration documentation for platform teams that connect to the Central Auth Gateway (this backend). It describes only the backend contracts and flows you must implement. It does not document any specific frontend application.

New here?

Start with a complete working example of login, API calls and logout where the gateway token never reaches the browser:

• Quickstart: React SPA + Express BFF
• Quickstart: Next.js (App Router)

What this service is

The Central Auth Gateway is the only platform-facing OIDC client for IESF platforms. The IESF identity service (identity-api, one OIDC issuer per environment such as PROD or DEV) is the authentication authority (credentials, login/registration, e-mail verification, identity sessions, OIDC tokens). This service owns:

• platform routing and registry
• JIT local user / profile provisioning
• onboarding evaluation
• opaque gateway browser sessions
• one-time platform handoffs

API instances are stateless. PostgreSQL stores profile, onboarding, authentication transactions, gateway sessions, and handoffs.

What platforms implement

A platform never becomes an identity client and never receives an identity access token, refresh token, ID token, PKCE verifier, or nonce.

Your platform surface against Central Auth is deliberately small:

Step	Who	Endpoint / action
1	Browser	Redirect to GET /v1/auth/start
2	Gateway + identity service	Login / registration (opaque to the platform)
3	Browser	Lands on the callback of the matching redirect pair with code=handoff_… (after the identity login and, when something required is missing, an onboarding page)
4	Your BFF	POST /v1/auth/exchange with platform Basic credentials
5	Your BFF	Create your own local session from the exchange body
6	Your BFF	On logout: POST /v1/auth/logout (optionally with returnTo), then send the browser to logoutUrl

How to read this guide

1. Architecture — responsibility boundaries and system shape
2. Authentication flow — full start → callback → handoff / resume sequences
3. Platform integration — checklist your BFF must satisfy
4. Admin operations (IESF Card) — register platformKey and onboarding fields in Card
5. Identity operations — identity environments, platform admins, service API, troubleshooting
6. Onboarding — none / platform / central modes and APIs
7. Central onboarding — identity UI onboarding step, dynamic field rendering, completion, and resume
8. Security invariants — rules that must not be violated
9. API reference — endpoint map and exchange JSON (runtime-accurate)

Live machine-readable contracts stay on the running API: OpenAPI 3.1 at /openapi.json, Swagger UI at /docs. Where narrative docs and runtime diverge, runtime wins; known divergences are called out explicitly.