Class OidcClient
java.lang.Object
com.revetsec.oidc.OidcClient
OpenID Connect authorization-code relying party. Provider discovery is lazy; explicit configuration and issuer settings are validated
without I/O or new threads in build. Authentication uses fresh nonce and PKCE S256 and validates the ID token before releasing
tokens or identity. The application supplies a fixed callback URI from trusted routing and clears pending cookies.
A sealed cookie inherits OAuth's concurrent replay boundary; use a durable atomic store for client-side single use.
- Since:
- 1.0.0
- Author:
- Mark Allen
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classMutable OIDC client configuration. -
Method Summary
Modifier and TypeMethodDescriptionStarts authentication with the client defaults.Starts authentication with replacement options.beginLogout(@NonNull OidcSessionReference original, @NonNull OidcLogoutHint hint) Prepares a browser GET/form POST request after the application has authorized its local POST/CSRF request and terminated its own session.completeAuthenticationResult(@NonNull AuthorizationResponse response, @NonNull PendingAuthorizationSource source, @NonNull URI actualCallbackUri) Completes authentication once, returning authenticated identity, checked authorization errors, rejected callback binding, rejected endpoint credentials, or a rejected ID token.completeLogoutResult(@NonNull String rawQuery, @NonNull PendingOidcLogoutSource source, @NonNull URI actualCallbackUri) Correlates a state-only browser return without discovery, JWKS, token POST, ID-token signature verification, retry or session creation.fetchUserInfoResult(@NonNull OidcAuthentication authentication) Fetches UserInfo and returns checked data or a fixed local or endpoint rejection.fetchUserInfoResult(@NonNull OidcAuthentication authentication, @NonNull OidcRefresh refreshed) Fetches UserInfo using a checked refresh result and the original authenticated identity.logoutHintFrom(@NonNull OidcAuthentication authentication) Explicitly retains this exact client's validated ID token as a logout hint.logoutHintFrom(@NonNull OidcRefresh refreshed) Explicitly retains a newly validated ID token from this exact client's refresh.refreshResult(@NonNull RefreshToken refreshToken, @NonNull OidcSessionReference original) Sends one refresh POST with default options and returns checked tokens or a fixed rejection.refreshResult(@NonNull RefreshToken refreshToken, @NonNull OidcSessionReference original, @NonNull TokenRequestOptions options) Sends one refresh POST with scope/resource options and returns checked tokens or a fixed rejection.toString()Redacts client configuration.voidwarmUp()Fetches lazy provider metadata and remote signing keys now.static @NonNull OidcClient.BuilderwithIssuer(@NonNull String issuer) Starts an OIDC client with lazy issuer-path discovery.static @NonNull OidcClient.BuilderwithProviderMetadata(@NonNull OidcProviderMetadata metadata) Starts an OIDC client with explicit provider metadata.
-
Method Details
-
withIssuer
Starts an OIDC client with lazy issuer-path discovery. Build performs no discovery or key lookup.- Parameters:
issuer- exact issuer identifier, without query or fragment- Returns:
- the builder
- Since:
- 1.0.0
-
withProviderMetadata
public static @NonNull OidcClient.Builder withProviderMetadata(@NonNull OidcProviderMetadata metadata) Starts an OIDC client with explicit provider metadata.- Parameters:
metadata- trusted application configuration- Returns:
- the builder
- Since:
- 1.0.0
-
warmUp
Fetches lazy provider metadata and remote signing keys now. Explicit metadata and static keys perform no I/O. Metadata and key lookup share the total deadline.- Since:
- 1.0.0
-
beginAuthentication
Starts authentication with the client defaults. This prepares the authorization URL.- Returns:
- redirect and pending record
- Since:
- 1.0.0
-
beginAuthentication
public @NonNull AuthorizationRedirect beginAuthentication(@NonNull OidcAuthenticationOptions options) Starts authentication with replacement options. Openid is emitted exactly once and nonce is generated internally.- Parameters:
options- per-login options- Returns:
- redirect and pending record
- Since:
- 1.0.0
-
completeAuthenticationResult
@CheckReturnValue public @NonNull OidcAuthenticationResult completeAuthenticationResult(@NonNull AuthorizationResponse response, @NonNull PendingAuthorizationSource source, @NonNull URI actualCallbackUri) Completes authentication once, returning authenticated identity, checked authorization errors, rejected callback binding, rejected endpoint credentials, or a rejected ID token. Rejected outcomes release no identity, claims or endpoint credentials. Pending-store failures return a fixed failure result. Metadata, transport, malformed responses, transient endpoint failures and invalid HMAC-secret failures remain exceptions. Clear the pending cookie on every outcome; the original completion's atomic-consumption and observer behavior is preserved.- Parameters:
response- parsed callbacksource- browser-bound pending sourceactualCallbackUri- receiving route URI from trusted routing configuration- Returns:
- the authentication outcome
- Since:
- 1.0.0
-
fetchUserInfoResult
@CheckReturnValue public @NonNull OidcUserInfoResult fetchUserInfoResult(@NonNull OidcAuthentication authentication) Fetches UserInfo and returns checked data or a fixed local or endpoint rejection. Issuer/client binding, subject, format and token lifetime checks precede release of any UserInfo. Transport, metadata, transient endpoint failures and invalid HMAC configuration remain exceptions. No request is automatically retried.- Parameters:
authentication- previously validated authentication for this issuer and client- Returns:
- the UserInfo outcome
- Since:
- 1.0.0
-
fetchUserInfoResult
@CheckReturnValue public @NonNull OidcUserInfoResult fetchUserInfoResult(@NonNull OidcAuthentication authentication, @NonNull OidcRefresh refreshed) Fetches UserInfo using a checked refresh result and the original authenticated identity. The original session must match before I/O. Rejection releases no UserInfo; infrastructure failures remain exceptions.- Parameters:
authentication- original validated authenticationrefreshed- checked refresh result for that original session- Returns:
- the UserInfo outcome
- Since:
- 1.0.0
-
refreshResult
@CheckReturnValue public @NonNull OidcRefreshResult refreshResult(@NonNull RefreshToken refreshToken, @NonNull OidcSessionReference original) Sends one refresh POST with default options and returns checked tokens or a fixed rejection. Persist the original session reference in trusted storage and serialize refreshes to avoid token-rotation races. Infrastructure failures and invalid HMAC configuration remain exceptions; no request is retried.- Parameters:
refreshToken- current refresh credentialoriginal- original session comparison reference, not proof of identity- Returns:
- the refresh outcome
- Since:
- 1.0.0
-
refreshResult
@CheckReturnValue public @NonNull OidcRefreshResult refreshResult(@NonNull RefreshToken refreshToken, @NonNull OidcSessionReference original, @NonNull TokenRequestOptions options) Sends one refresh POST with scope/resource options and returns checked tokens or a fixed rejection. The caller restricts scopes to the original grant. Any returned ID token must pass original-session continuity checks before tokens are released. Infrastructure failures and invalid HMAC configuration remain exceptions; no request is automatically retried.- Parameters:
refreshToken- current refresh credentialoriginal- original session comparison referenceoptions- per-request scope and resources- Returns:
- the refresh outcome
- Since:
- 1.0.0
-
logoutHintFrom
Explicitly retains this exact client's validated ID token as a logout hint. This does not extend identity lifetime or change the comparison-only original reference. A token may later be used after authentication expiry.- Parameters:
authentication- genuine completed authentication produced by this exact client instance- Returns:
- credential-bearing logout companion for trusted storage
- Throws:
NullPointerException- if authentication is nullOidcLogoutException- if ownership, profile, current issuer policy, interruption or the budget fails- Since:
- 1.0.0
-
logoutHintFrom
Explicitly retains a newly validated ID token from this exact client's refresh. Omitted ID tokens yield empty; the original session reference is always retained and no new authenticated identity is created.- Parameters:
refreshed- genuine refresh result produced by this exact client instance- Returns:
- optional replacement credential, never a replacement original reference
- Throws:
NullPointerException- if refreshed is nullOidcLogoutException- if ownership, profile, current issuer policy, interruption or the budget fails- Since:
- 1.0.0
-
beginLogout
public @NonNull OidcLogoutRequest beginLogout(@NonNull OidcSessionReference original, @NonNull OidcLogoutHint hint) Prepares a browser GET/form POST request after the application has authorized its local POST/CSRF request and terminated its own session. Failures never undo local termination. No end-session server request or automatic retry is sent. The original reference and retained hint must match before discovery, entropy or output.- Parameters:
original- original continuity reference for this session, not identity proofhint- explicitly retained logout credential bound to that reference- Returns:
- credential-bearing browser request and independent pending correlation state
- Throws:
NullPointerException- if a required argument is nullOidcLogoutException- if configuration, binding, discovery, URI policy, time, entropy or the budget fails- Since:
- 1.0.0
-
completeLogoutResult
@CheckReturnValue public @NonNull OidcLogoutResult completeLogoutResult(@NonNull String rawQuery, @NonNull PendingOidcLogoutSource source, @NonNull URI actualCallbackUri) Correlates a state-only browser return without discovery, JWKS, token POST, ID-token signature verification, retry or session creation. The actual callback comes from trusted routing configuration, never headers. Clear a pending cookie on every callback, including rejection/exception paths. Returned proves correlation only.- Parameters:
rawQuery- raw query without the leading question mark, at most4096characterssource- this browser's typed pending sourceactualCallbackUri- trusted actual callback route- Returns:
- correlation-only Returned or a fixed value-free rejection
- Throws:
NullPointerException- if a required argument is nullOidcLogoutException- if configuration, budget, interruption, provider or store uncertainty prevents completion- Since:
- 1.0.0
-
toString
-