Class OidcClient

java.lang.Object
com.revetsec.oidc.OidcClient

@ThreadSafe public final class OidcClient extends Object
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
  • 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

      Starts an OIDC client with explicit provider metadata.
      Parameters:
      metadata - trusted application configuration
      Returns:
      the builder
      Since:
      1.0.0
    • warmUp

      public void 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

      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

      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 callback
      source - browser-bound pending source
      actualCallbackUri - 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 authentication
      refreshed - 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 credential
      original - original session comparison reference, not proof of identity
      Returns:
      the refresh outcome
      Since:
      1.0.0
    • refreshResult

      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 credential
      original - original session comparison reference
      options - 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 null
      OidcLogoutException - 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 null
      OidcLogoutException - if ownership, profile, current issuer policy, interruption or the budget fails
      Since:
      1.0.0
    • beginLogout

      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 proof
      hint - 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 null
      OidcLogoutException - 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 most4096characters
      source - this browser's typed pending source
      actualCallbackUri - trusted actual callback route
      Returns:
      correlation-only Returned or a fixed value-free rejection
      Throws:
      NullPointerException - if a required argument is null
      OidcLogoutException - if configuration, budget, interruption, provider or store uncertainty prevents completion
      Since:
      1.0.0
    • toString

      Redacts client configuration.
      Overrides:
      toString in class Object
      Returns:
      a redacted description
      Since:
      1.0.0