GET /api/v1/auth/oidc/callback/{providerId}

OpenID Connect sign-in, step 3: the provider's redirect back; answers the completion page.

The provider's redirect URI. Requires the transaction cookie and the exact state; a provider error ends the sign-in with no key-server call. Otherwise the Gateway exchanges the code (PKCE verifier, client authentication), validates the ID token (signature by a key of the provider's JWKS, issuer, audience, azp, expiry, iat, the transaction's nonce, auth_time against maxAge), checks RFC 9207 iss where the provider sends it, and resolves the issuer and subject to an XAuth principal through the operator's mapping. Nothing is created at sign-in.

The answer is the completion page (text/html), under Content-Security-Policy: default-src 'none'; script-src 'sha256-<hash>'; frame-ancestors 'none'; base-uri 'none'. Its one constant script posts {te: 'oidc', flowId, ok} (with error on a failure: provider_denied, login_evidence_rejected, identity_not_mapped, idp_unavailable, binding_not_available) to window.opener with targetOrigin the binding's application origin, and nothing else. It carries no code, token or secret. Every answer from a recognised transaction clears the transaction cookie (Max-Age=0).

Authentication

No session required. This operation is reachable without an Authorization header. See Authenticating.

Parameters

Name	In	Required	Type	Description
providerId	path	yes	string
state	query	yes	string
code	query	no	string
iss	query	no	string
error	query	no	string

Request

No request body.

Responses

200

The completion page, ok true.

401

TRANSACTION_UNKNOWN (JSON) -- no pending sign-in at this provider has that state, or the transaction cookie is missing or another sign-in's (never which); the token endpoint is not reached. Or the completion page with error provider_denied or login_evidence_rejected (LOGIN_EVIDENCE_REJECTED class: the code or the ID token was not accepted).

403

The completion page with error identity_not_mapped (IDENTITY_NOT_MAPPED: the provider authenticated a subject this Gateway has no enabled mapping for) or binding_not_available (BINDING_NOT_AVAILABLE).

503

The completion page with error idp_unavailable (IDP_UNAVAILABLE, Retry-After). Or OIDC_NOT_CONFIGURED (JSON, Retry-After).

Error handling

Every failure answers JSON carrying at least code and detail. Match on code — detail is written for a human debugging the call and its wording is not part of the contract. See the error model.

Status	Meaning
401	TRANSACTION_UNKNOWN (JSON) -- no pending sign-in at this provider has that state, or the transaction cookie is missing or another sign-in's (never which); the token endpoint is not reached. Or the completion page with error provider_denied or login_evidence_rejected (LOGIN_EVIDENCE_REJECTED class: the code or the ID token was not accepted).
403	The completion page with error identity_not_mapped (IDENTITY_NOT_MAPPED: the provider authenticated a subject this Gateway has no enabled mapping for) or binding_not_available (BINDING_NOT_AVAILABLE).
503	The completion page with error idp_unavailable (IDP_UNAVAILABLE, Retry-After). Or OIDC_NOT_CONFIGURED (JSON, Retry-After).