OIDC reference

The owned Go service implements an OIDC authorization-code issuer. Its registry resolves confidential web clients, and mounted development acceptance covers two synthetic clients. Configure a maintained OIDC library from the exact issuer’s discovery document. An application must not assume that a client approved in management is already registered with this issuer.

What the issuer means

OIDC_ISSUER tells an application which authentication authority to trust. Taifa Identity is intended to be that authority for Taifa AI, Mail, Support, Sign and future projects. Its Go service uses AUTH_ISSUER for the same exact server identity. Products redirect people to its custom sign-in UI and verify the returned signed identity against its public keys. A central session allows another registered project to sign in without repeating the login ceremony, subject to that project’s current access policy and assurance requirements.

The issuer URL must match discovery metadata and the token’s iss exactly. A hostname, origin or path change creates a different issuer identity; it does not automatically carry existing account authority across. The owned issuer remains restricted to isolated development while production acceptance is incomplete.

After a reviewed workforce migration, the trusted human issuer and owned target may coincide. Changing configuration alone does not migrate existing (issuer, subject) bindings, register clients or grant authority. Configure each service deliberately, retain the exact identity mappings, and complete migration acceptance before switching production traffic.

Discover endpoints

Read ISSUER/.well-known/openid-configuration. The local public handler exposes discovery, /authorize, /oauth/token, and /keys. Treat the discovery response as the endpoint source. The issuer signs RS256 tokens with a configured key ID and publishes the verification key. Pin the expected issuer in your deployment configuration and reject an unexpected discovery issuer.

Request a code

Use response_type=code, scope=openid profile as needed, a fresh state and nonce, an exact registered redirect, and code_challenge_method=S256. Store the matching verifier in the backend or platform-secure native transaction. Products use the public OIDC flow; they do not collect a central password or call private factor APIs.

In central browser SSO mode, the separate authentication UI runs at the issuer origin. Its backend calls the private central authentication API with a dedicated service credential and server-held flow capabilities. Each request has its own durable browser and CSRF binding. The product portal retains its own login transaction and callback; it does not supply the central UI’s cookie or factor state.

The earlier single-portal development exercise uses the portal BFF’s private challenge adapter instead, with its separate bearer key and X-Taifa-Auth-State binding. That flow remains the explicitly scoped quick start. Neither private adapter is a public product integration API.

The current issuer supports openid, profile, email, and offline_access. Include offline_access in the original request to obtain a rotating refresh token. A refresh token cannot extend beyond the original eight-hour session. Do not assume support for implicit flow, password grant, dynamic registration, or client credentials.

Validate the response

A library must verify the signature, iss, client aud, expiry, nonce, and subject. Match the callback state before token exchange. The ID token identifies the signed-in person for the client. It is not an access token for the management API or a product API. For management, use an access token with audience taifa-management and current authorization.

The issuer may set acr=taifa-mfa after password plus TOTP, or acr=taifa-phishing-resistant after a user-verified passkey. A requested assurance value is not evidence; inspect the verified token and current session. Platform administrator operations and catalog/client-policy proposals and approvals require the phishing-resistant value and an actual recent auth_time. Check the specific API operation’s authorization contract before presenting a review action.

Identifier stability

sub is the immutable account identifier within one issuer. The exact (iss, sub) pair is the durable key across products. Login names and email can change. The development service currently matches login identifiers exactly and rejects case-colliding reservations, while the final admission policy is still pending. Do not derive identity from username or email.