Class OidcClient

java.lang.Object
io.fluxzero.idp.client.OidcClient
public class OidcClient extends Object
Small OIDC client for authorization-code-with-PKCE application flows.

This client deliberately stops at protocol mechanics: building the authorization URL, exchanging a code for tokens and constructing a logout URL. It does not create application sessions, write cookies or map users. Fluxzero applications should keep that BFF responsibility in their own backend code so domain-specific user provisioning and roles stay close to the customer model.

  • Constructor Details

    • OidcClient

      public OidcClient(OidcTenantConfig config)
      Creates a client that discovers OIDC endpoints from the configured issuer.
      Parameters:
      config - tenant configuration for this application

    • OidcClient

      public OidcClient(OidcTenantConfig config, OidcDiscoveryDocument discovery)
      Creates a client with already discovered metadata.

      This constructor is useful for tests that want deterministic metadata without making a discovery HTTP request.

      Parameters:
      config - tenant configuration for this application
      discovery - resolved OIDC discovery document

    • OidcClient

      public OidcClient(OidcTenantConfig config, OidcTransport transport, OidcClientAuthentication authentication)
      Discovers through the explicit transport and uses only the supplied authentication capability.

    • OidcClient

      public OidcClient(OidcTenantConfig config, OidcDiscoveryDocument discovery, OidcTransport transport, OidcClientAuthentication authentication)
      Explicit application-owned protocol boundary. No fallback to the Runtime or credentials in config occurs. The transport must enforce destination/redirect/size/deadline policy; the authentication capability owns signing/key custody. Metadata must match the exact issuer.

  • Method Details

    • withRedirectUri

      public OidcClient withRedirectUri(String redirectUri)
      Returns an independent client for the callback URI resolved at login start. Discovery, transport and authentication are retained, without mutating this client or making another discovery request. Save the exact URI in the pending login and reuse it when exchanging its authorization code.

    • authorizationUrl

      public String authorizationUrl(Pkce pkce, String state)
      Builds the authorization endpoint URL for authorization-code flow with PKCE S256.
      Parameters:
      pkce - verifier/challenge pair for this login attempt
      state - CSRF correlation value stored by the application
      Returns:
      redirect URL for the user's browser

    • authorizationUrl

      public String authorizationUrl(Pkce pkce, String state, String nonce)
      Adds the independent, per-login nonce that the caller must verify in the validated ID token.

    • authorizationUrl

      public String authorizationUrl(Pkce pkce, String state, String nonce, Map<String,String> parameters)
      Explicit UI hints/extensions cannot override the configured protocol or its login bindings.

    • authorizationUrl

      public String authorizationUrl(OidcLoginState loginState)
      Builds the authorization endpoint URL from a stateless login transaction.
      Parameters:
      loginState - BFF login transaction with state and PKCE verifier
      Returns:
      redirect URL for the user's browser

    • exchangeCode

      public OidcClient.TokenResponse exchangeCode(String code, String codeVerifier)
      Exchanges an authorization code for ID and access tokens.
      Parameters:
      code - authorization code received on the application callback
      codeVerifier - PKCE verifier stored with the pending login
      Returns:
      token response from the tenant

    • refreshTokens

      public OidcClient.TokenResponse refreshTokens(String refreshToken)
      Performs one refresh request through the configured transport and a fresh client assertion. The caller must exclusively claim the refresh token before calling; this method never retries an uncertain rotation. A refreshed ID token and replacement refresh token are optional per OIDC.

    • exchangeToken

      public OidcClient.TokenResponse exchangeToken(String subjectToken, OidcClient.ResourceTokenRequest request)
      Exchanges this client's own access token for a short-lived resource token (RFC 8693). Resource and scopes must come from application configuration, never an unvalidated browser URL. The resource API remains responsible for current product rights and tenant authorization. This is an in-process protocol call; neither token belongs in a message or browser response.

    • endSessionUrl

      public String endSessionUrl(String postLogoutRedirectUri)
      Builds a tenant logout URL when the issuer advertises one.
      Parameters:
      postLogoutRedirectUri - application URL to return to after logout
      Returns:
      logout URL or the redirect URI when no logout endpoint is advertised

    • endSessionUrl

      public String endSessionUrl(String postLogoutRedirectUri, String idTokenHint)
      Builds a tenant logout URL with an optional ID token hint.
      Parameters:
      postLogoutRedirectUri - application URL to return to after logout
      idTokenHint - ID token for the session being closed
      Returns:
      logout URL or the redirect URI when no logout endpoint is advertised

    • config

      public OidcTenantConfig config()

    • discovery

      public OidcDiscoveryDocument discovery()