Package org.apache.juneau.rest.server.auth.oidc.rp

Class OidcRelyingParty.Builder

java.lang.Object
org.apache.juneau.rest.server.auth.oidc.rp.OidcRelyingParty.Builder
Enclosing class:
OidcRelyingParty
public static class OidcRelyingParty.Builder extends Object
Builder.

  • Constructor Details

    • Builder

      protected Builder()
      Constructor.

  • Method Details

    • issuer

      public OidcRelyingParty.Builder issuer(URI value)
      Sets the IdP issuer URL. OIDC discovery resolves the endpoints + JWKS URI lazily. Either this or metadata(OidcMetadata) is required.

      The issuer (and every endpoint discovered from it) must use "https" or target a loopback host; discovery, JWKS, and token exchanges carry trust-anchor key material and client credentials, so a plaintext transport to a non-loopback host is rejected.

      Parameters:
      value - The issuer URL. Must not be null and must use HTTPS or target a loopback host.
      Returns:
      This object.

    • metadata

      public OidcRelyingParty.Builder metadata(OidcMetadata value)
      Sets the IdP metadata explicitly, bypassing discovery. Either this or issuer(URI) is required.
      Parameters:
      value - The metadata. Must not be null.
      Returns:
      This object.

    • clientId

      public OidcRelyingParty.Builder clientId(String value)
      Sets the OAuth client id. Required.
      Parameters:
      value - The client id. Must not be null or blank.
      Returns:
      This object.

    • clientSecret

      public OidcRelyingParty.Builder clientSecret(String value)
      Sets the client secret. May be omitted for public clients (PKCE-only).
      Parameters:
      value - The client secret. Must not be null or blank.
      Returns:
      This object.

    • clientSecretSupplier

      public OidcRelyingParty.Builder clientSecretSupplier(Supplier<String> value)
      Sets the client secret via a supplier.
      Parameters:
      value - The supplier. Must not be null.
      Returns:
      This object.

    • redirectUri

      public OidcRelyingParty.Builder redirectUri(URI value)
      Sets the redirect URI registered with the IdP. Required.
      Parameters:
      value - The redirect URI. Must not be null.
      Returns:
      This object.

    • postLogoutRedirectUri

      public OidcRelyingParty.Builder postLogoutRedirectUri(URI value)
      Sets the post-logout redirect URI passed to the IdP end-session endpoint.
      Parameters:
      value - The post-logout redirect URI. Must not be null.
      Returns:
      This object.

    • postLoginRedirect

      public OidcRelyingParty.Builder postLoginRedirect(String value)
      Sets the default post-login redirect target (when the login request supplied no safe redirect parameter). Defaults to "/".
      Parameters:
      value - The default redirect path. Must not be null or blank.
      Returns:
      This object.

    • scope

      public OidcRelyingParty.Builder scope(String... values)
      Adds requested scopes. openid is always included.
      Parameters:
      values - The scopes.
      Returns:
      This object.

    • sessionStore

      public OidcRelyingParty.Builder sessionStore(SessionStore value)
      Sets the session store. Required.
      Parameters:
      value - The session store. Must not be null.
      Returns:
      This object.

    • rolesClaim

      public OidcRelyingParty.Builder rolesClaim(String value)
      Sets the claim roles are extracted from. Defaults to "scope" (whitespace-split); array claims are also accepted. Mirrors the OAuthFilter convention.
      Parameters:
      value - The claim name. Must not be null or blank.
      Returns:
      This object.

    • stateNonceTtl

      public OidcRelyingParty.Builder stateNonceTtl(Duration value)
      Sets the single-use TTL the framework enforces for the login-state (state / nonce / PKCE code_verifier) association. Defaults to 5 minutes.

      This is the RP-enforced policy applied to every consumed record — both the default InMemoryLoginStateStore and any custom injected store. The framework mints expiresAt = createdAt + stateNonceTtl on the record and re-checks it on consume, so the ceiling holds even for a shared store that fails to expire an entry. The (0, LoginStateStore.MAX_TTL] cap is enforced here (not only in the default impl's constructor, which is skipped when a custom store is injected).

      Parameters:
      value - The TTL. Must be positive and not exceed LoginStateStore.MAX_TTL (30 minutes).
      Returns:
      This object.

    • loginStateStore

      public OidcRelyingParty.Builder loginStateStore(LoginStateStore value)
      Sets an optional custom LoginStateStore for the pending-login (state → nonce / PKCE code_verifier / redirect) association.

      Optional (unlike sessionStore(SessionStore)): when omitted the RP uses the shipped per-JVM InMemoryLoginStateStore, and behavior is identical to a single-node deployment. Supply a shared (Redis / JDBC) implementation to support a clustered deployment where /login and /callback may land on different nodes without sticky sessions — the same motivation as a distributed SessionStore.

      The store is secret-bearing (code_verifier + nonce); read the LoginStateStore security contract before implementing one (TLS + locked-down ACL floor, encryption-at-rest recommended, never log the payload, atomic GETDEL/Lua single-use consume). The framework retains authority over the security-critical decisions regardless of the store: it re-validates redirectTarget via safeRelativePath and re-checks expiresAt against its own clock on consume, and enforces the stateNonceTtl(Duration) ceiling — the store persists the record and enforces single-use, but is treated as a blob store, not a trusted oracle.

      Parameters:
      value - The login-state store. Must not be null.
      Returns:
      This object.

    • sessionTtl

      public OidcRelyingParty.Builder sessionTtl(Duration value)
      Sets the session lifetime (bounded independently of token lifetime). Defaults to 8 hours.
      Parameters:
      value - The session TTL. Must be positive.
      Returns:
      This object.

    • cookieName

      public OidcRelyingParty.Builder cookieName(String value)
      Sets the session cookie name. Defaults to JUNEAU_OIDC_SESSION.
      Parameters:
      value - The cookie name. Must not be null or blank.
      Returns:
      This object.

    • cookieSecure

      public OidcRelyingParty.Builder cookieSecure(boolean value)
      Sets the cookie Secure flag. Defaults to true (fail-closed).
      Parameters:
      value - The flag.
      Returns:
      This object.

    • cookieHttpOnly

      public OidcRelyingParty.Builder cookieHttpOnly(boolean value)
      Sets the cookie HttpOnly flag. Defaults to true (fail-closed).
      Parameters:
      value - The flag.
      Returns:
      This object.

    • cookieSameSite

      public OidcRelyingParty.Builder cookieSameSite(String value)
      Sets the cookie SameSite attribute. Defaults to "Lax".
      Parameters:
      value - The SameSite value (e.g. "Lax" or "Strict"). Must not be null or blank.
      Returns:
      This object.

    • httpRequestConfigurator

      public OidcRelyingParty.Builder httpRequestConfigurator(Consumer<com.nimbusds.oauth2.sdk.http.HTTPRequest> value)
      Sets a Nimbus HTTPRequest configurator escape hatch (proxy / TLS / timeouts) applied to discovery + token + userinfo calls.
      Parameters:
      value - The callback. Must not be null.
      Returns:
      This object.

    • authenticationRequestCustomizer

      public OidcRelyingParty.Builder authenticationRequestCustomizer(Consumer<com.nimbusds.openid.connect.sdk.AuthenticationRequest.Builder> value)
      Sets a Nimbus AuthenticationRequest.Builder customizer escape hatch (e.g. prompt, max_age, acr_values) applied to the authorization redirect.
      Parameters:
      value - The callback. Must not be null.
      Returns:
      This object.

    • idTokenAlgorithms

      public OidcRelyingParty.Builder idTokenAlgorithms(com.nimbusds.jose.JWSAlgorithm... values)
      Sets the ID-token signing-algorithm allowlist. Defaults to [RS256, ES256].
      Parameters:
      values - The allowed algorithms.
      Returns:
      This object.

    • clockSkewSeconds

      public OidcRelyingParty.Builder clockSkewSeconds(int value)
      Sets the clock-skew tolerance (seconds) for ID-token validation. Defaults to 60.
      Parameters:
      value - The tolerance in seconds. Must be non-negative.
      Returns:
      This object.

    • jwkSet

      public OidcRelyingParty.Builder jwkSet(com.nimbusds.jose.jwk.JWKSet value)
      Injects a fixed JWK set for ID-token / logout-token signature verification, bypassing the JWKS endpoint. Useful for tests and static-key deployments.
      Parameters:
      value - The JWK set. Must not be null.
      Returns:
      This object.

    • jwkSource

      public OidcRelyingParty.Builder jwkSource(com.nimbusds.jose.jwk.source.JWKSource<com.nimbusds.jose.proc.SecurityContext> value)
      Injects a custom JWK source for ID-token / logout-token signature verification.
      Parameters:
      value - The JWK source. Must not be null.
      Returns:
      This object.

    • userInfoClaims

      public OidcRelyingParty.Builder userInfoClaims(String... values)
      Adds claim names to backfill from the UserInfo endpoint when absent from the ID token.

      When empty (the default) the UserInfo endpoint is never called — the Principal is built from ID-token claims only.

      Parameters:
      values - The claim names to backfill.
      Returns:
      This object.

    • clock

      public OidcRelyingParty.Builder clock(Clock value)
      Overrides the clock used for session expiry and the login-state store. Useful in tests.

      The login-state expiresAt is both minted (on startLogin) and re-checked (on completeLogin) against this clock. In a clustered deployment with a shared LoginStateStore, the ceiling is therefore only as trustworthy as clock synchronization across nodes; a backend EXPIRE/TTL is a GC hint, not the authoritative expiry decision.

      Parameters:
      value - The clock. Must not be null.
      Returns:
      This object.

    • build

      public OidcRelyingParty build()
      Builds the relying party.
      Returns:
      A new OidcRelyingParty.