Background
The server currently accepts and validates Bearer tokens from external IDPs
(configured per realm via JwtParams.idp_params), but it has no OIDC-compatible
surface of its own. As a result, the server cannot participate in standard OIDC
flows — it can only consume tokens that are already present in the request.
Building a minimal OIDC RP foundation would make the server a first-class
participant in the OIDC ecosystem and enable a broad class of integrations
(gateway-initiated redirects, token introspection by third parties,
discovery-based auto-configuration) without requiring those integrations to be
built ad hoc each time.
Goal
Add the standard OIDC endpoints that form the baseline for Relying Party
behaviour, prioritised by implementation cost vs. unlocked capability.
P0 — Token introspection (RFC 7662)
POST /realms/{realm_id}/introspect
Allows any OAuth2-aware client or gateway to validate a token by calling our
server rather than performing local JWT verification. The implementation is thin:
session store lookup + claims projection into the RFC 7662 response shape. This
unlocks the widest range of third-party integrations for the smallest
implementation cost.
P1 — Authorization Code flow as Relying Party
GET /realms/{realm_id}/oidc/authorize
Initiates an Authorization Code flow toward one of the realm's configured IDPs.
Generates state (CSRF + original URL), nonce, and a PKCE code_challenge
(RFC 7636), stores them in a short-lived session store entry, then redirects the
browser to the IDP's authorization_endpoint. When the realm has multiple
idp_params entries, the caller must supply ?issuer=<jwt_issuer_uri> to
identify the target IDP; a single configured IDP is selected automatically.
GET /realms/{realm_id}/oidc/callback
Receives the authorization code returned by the IDP. Validates state,
exchanges the code for tokens at the IDP's token_endpoint (server-to-server,
with PKCE verifier), validates the ID token using the existing JwksManager,
then creates a session through the existing login path, sets the _ea_ cookie,
and redirects the browser to the original URL recovered from state.
P2 — OIDC Discovery (RFC 8414)
GET /realms/{realm_id}/.well-known/openid-configuration
Publishes a discovery document advertising the realm's authorization_endpoint,
token_endpoint, jwks_uri (existing /public/jwks), and supported response
and grant types. This allows any OIDC-aware client or gateway to auto-configure
against the server without manual endpoint wiring.
P3 — RP-Initiated Logout (OIDC Session Management)
POST /realms/{realm_id}/oidc/logout
Invalidates the local session and propagates logout to the IDP's
end_session_endpoint if one is advertised in the IDP's discovery document.
Out of scope
Acting as a full OIDC Provider (issuing ID tokens, userinfo endpoint, dynamic
client registration). The existing Bearer token validation path is unchanged.
Background
The server currently accepts and validates Bearer tokens from external IDPs
(configured per realm via
JwtParams.idp_params), but it has no OIDC-compatiblesurface of its own. As a result, the server cannot participate in standard OIDC
flows — it can only consume tokens that are already present in the request.
Building a minimal OIDC RP foundation would make the server a first-class
participant in the OIDC ecosystem and enable a broad class of integrations
(gateway-initiated redirects, token introspection by third parties,
discovery-based auto-configuration) without requiring those integrations to be
built ad hoc each time.
Goal
Add the standard OIDC endpoints that form the baseline for Relying Party
behaviour, prioritised by implementation cost vs. unlocked capability.
P0 — Token introspection (RFC 7662)
POST /realms/{realm_id}/introspectAllows any OAuth2-aware client or gateway to validate a token by calling our
server rather than performing local JWT verification. The implementation is thin:
session store lookup + claims projection into the RFC 7662 response shape. This
unlocks the widest range of third-party integrations for the smallest
implementation cost.
P1 — Authorization Code flow as Relying Party
GET /realms/{realm_id}/oidc/authorizeInitiates an Authorization Code flow toward one of the realm's configured IDPs.
Generates
state(CSRF + original URL),nonce, and a PKCEcode_challenge(RFC 7636), stores them in a short-lived session store entry, then redirects the
browser to the IDP's
authorization_endpoint. When the realm has multipleidp_paramsentries, the caller must supply?issuer=<jwt_issuer_uri>toidentify the target IDP; a single configured IDP is selected automatically.
GET /realms/{realm_id}/oidc/callbackReceives the authorization code returned by the IDP. Validates
state,exchanges the code for tokens at the IDP's
token_endpoint(server-to-server,with PKCE verifier), validates the ID token using the existing
JwksManager,then creates a session through the existing login path, sets the
_ea_cookie,and redirects the browser to the original URL recovered from
state.P2 — OIDC Discovery (RFC 8414)
GET /realms/{realm_id}/.well-known/openid-configurationPublishes a discovery document advertising the realm's
authorization_endpoint,token_endpoint,jwks_uri(existing/public/jwks), and supported responseand grant types. This allows any OIDC-aware client or gateway to auto-configure
against the server without manual endpoint wiring.
P3 — RP-Initiated Logout (OIDC Session Management)
POST /realms/{realm_id}/oidc/logoutInvalidates the local session and propagates logout to the IDP's
end_session_endpointif one is advertised in the IDP's discovery document.Out of scope
Acting as a full OIDC Provider (issuing ID tokens,
userinfoendpoint, dynamicclient registration). The existing Bearer token validation path is unchanged.