Module io.helidon.security.providers.oidc.common
Package io.helidon.security.providers.oidc.common

Class OidcConfig.Builder

java.lang.Object
io.helidon.security.providers.oidc.common.BaseBuilder<OidcConfig.Builder,OidcConfig>
io.helidon.security.providers.oidc.common.OidcConfig.Builder
All Implemented Interfaces:
Builder<OidcConfig.Builder,OidcConfig>, Supplier<OidcConfig>
Enclosing class:
OidcConfig
public static class OidcConfig.Builder extends BaseBuilder<OidcConfig.Builder,OidcConfig>
A fluent API Builder to build instances of OidcConfig.

  • Constructor Details

    • Builder

      protected Builder()

  • Method Details

    • build

      public OidcConfig build()
      Description copied from interface: Builder
      Build the instance from this builder.
      Returns:
      instance of the built type

    • config

      public OidcConfig.Builder config(Config config)
      Update this builder with values from configuration.
      Overrides:
      config in class BaseBuilder<OidcConfig.Builder,OidcConfig>
      Parameters:
      config - configuration located on node with OIDC configuration keys (e.g. client-id)
      Returns:
      updated builder instance

    • tokenRefreshSkew

      public OidcConfig.Builder tokenRefreshSkew(Duration tokenRefreshSkew)
      Amount of time access token should be refreshed before expiration.
      Parameters:
      tokenRefreshSkew - time to refresh token before expiration
      Returns:
      updated builder

    • crossOriginConfig

      @Deprecated(forRemoval=true, since="4.4.0") public OidcConfig.Builder crossOriginConfig(CrossOriginConfig crossOriginConfig)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use config based CORS setup or the io.helidon.webserver.cors.CorsFeature server feature
      Assign cross-origin resource sharing settings.
      Parameters:
      crossOriginConfig - cross-origin settings to apply to the redirect endpoint
      Returns:
      updated builder instance

    • logoutEnabled

      public OidcConfig.Builder logoutEnabled(Boolean logoutEnabled)
      Whether to enable logout support.
      Parameters:
      logoutEnabled - whether to enable logout
      Returns:
      updated builder instance

    • redirect

      public OidcConfig.Builder redirect(boolean redirect)
      Whether to redirect to OIDC server when authentication information is missing.
      Parameters:
      redirect - whether to redirect
      Returns:
      updated builder instance

    • frontendUri

      public OidcConfig.Builder frontendUri(String uri)
      Full URI of this application that is visible from user browser.
      Parameters:
      uri - the frontend URI, such as "http://my.server.com/myApp
      Returns:
      updated builder instance

    • forceHttpsRedirects

      public OidcConfig.Builder forceHttpsRedirects(boolean forceHttpsRedirects)
      Force HTTPS for redirects to identity provider.
      Parameters:
      forceHttpsRedirects - flag to redirect with https
      Returns:
      updated builder instance

    • fallbackToDefaultTenantEnabled

      public OidcConfig.Builder fallbackToDefaultTenantEnabled(boolean enabled)
      Whether unknown tenant ids should use default tenant configuration.
      Parameters:
      enabled - whether unknown tenant ids fall back to default tenant
      Returns:
      updated builder instance

    • relativeUris

      @Deprecated(since="4.2.1", forRemoval=true) public OidcConfig.Builder relativeUris(boolean relativeUris)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use OIDC webclient configuration instead. See webclient(Consumer)
      Whether to force relative URIs in all requests.
      Parameters:
      relativeUris - relative URIs flag
      Returns:
      updated builder instance

    • redirectUri

      public OidcConfig.Builder redirectUri(String redirectUri)
      URI to register web server component on, used by the OIDC server to redirect authorization requests to after a user logs in or approves scopes. Note that usually the redirect URI configured here must be the same one as configured on OIDC server.

      Defaults to "/oidc/redirect"

      Parameters:
      redirectUri - the URI (path without protocol, host and port) used to redirect requests back to us
      Returns:
      updated builder instance

    • logoutUri

      public OidcConfig.Builder logoutUri(String logoutUri)
      Path to register web server for logout link. This should be used by application to redirect user to logout the current user from Helidon based session (when using cookies and redirection). This endpoint will logout user from Helidon session (remove Helidon cookies) and redirect user to logout screen of the OIDC server.
      Parameters:
      logoutUri - URI path for logout component
      Returns:
      updated builder instance

    • postLogoutUri

      public OidcConfig.Builder postLogoutUri(URI uri)
      URI to redirect to once the logout process is done. The endpoint should not be protected by OIDC (as this would serve no purpose, just to log the user in again). This endpoint usually must be registered with the application as the allowed post-logout redirect URI. Note that the URI should not contain any query parameters. You can obtain state using the state query parameter that must be provided to logoutUri(String).
      Parameters:
      uri - this will be used by the OIDC server to redirect user to once logout is done, can define just path, in which case the scheme, host and port will be taken from request.
      Returns:
      updated builder instance

    • redirectAttemptParam

      public OidcConfig.Builder redirectAttemptParam(String paramName)
      Configure the redirect attempt query parameter and cookie name prefix.
      Parameters:
      paramName - name of the parameter or cookie name prefix
      Returns:
      updated builder instance

    • redirectAttemptCounterStrategy

      public OidcConfig.Builder redirectAttemptCounterStrategy(RedirectAttemptCounterStrategy strategy)
      Configure the strategy used to count redirects to an identity server.
      Parameters:
      strategy - redirect attempt counter strategy
      Returns:
      updated builder instance

    • maxRedirects

      public OidcConfig.Builder maxRedirects(int maxRedirects)
      Configure maximal number of redirects when redirecting to an OIDC provider within a single authentication attempt.

      Defaults to 5

      Parameters:
      maxRedirects - maximal number of redirects from Helidon to OIDC provider
      Returns:
      updated builder instance

    • proxyProtocol

      @Deprecated(since="4.2.1", forRemoval=true) public OidcConfig.Builder proxyProtocol(String protocol)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use proxy configuration on the webclient. See webclient(Consumer)
      Proxy protocol to use when proxy is used.
      Parameters:
      protocol - protocol to use (such as https)
      Returns:
      updated builder instance

    • proxyHost

      @Deprecated(since="4.2.1", forRemoval=true) public OidcConfig.Builder proxyHost(String proxyHost)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use proxy configuration on the webclient. See webclient(Consumer)
      Proxy host to use.
      Parameters:
      proxyHost - host of the proxy
      Returns:
      updated builder instance
      See Also:

    • proxyPort

      @Deprecated(since="4.2.1", forRemoval=true) public OidcConfig.Builder proxyPort(int proxyPort)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use proxy configuration on the webclient. See webclient(Consumer)
      Proxy port.
      Parameters:
      proxyPort - port of the proxy server to use
      Returns:
      updated builder instance

    • headerTokenHandler

      public OidcConfig.Builder headerTokenHandler(TokenHandler tokenHandler)
      A TokenHandler to process header containing a JWT. Default is "Authorization" header with a prefix "bearer ".
      Parameters:
      tokenHandler - token handler to use
      Returns:
      updated builder instance

    • useHeader

      public OidcConfig.Builder useHeader(Boolean useHeader)
      Whether to expect JWT in a header field.
      Parameters:
      useHeader - set to true to use a header extracted with headerTokenHandler(TokenHandler)
      Returns:
      updated builder instance

    • paramName

      public OidcConfig.Builder paramName(String paramName)
      Name of a query parameter that contains the JWT access token when parameter is used.
      Parameters:
      paramName - name of the query parameter to expect
      Returns:
      updated builder instance

    • idTokenParamName

      public OidcConfig.Builder idTokenParamName(String idTokenParamName)
      Name of a query parameter that contains the JWT id token when parameter is used.
      Parameters:
      idTokenParamName - name of the query parameter to expect
      Returns:
      updated builder instance

    • paramTenantName

      public OidcConfig.Builder paramTenantName(String paramName)
      Name of a query parameter that contains the tenant name when the parameter is used. Defaults to OidcConfig.DEFAULT_TENANT_PARAM_NAME.
      Parameters:
      paramName - name of the query parameter to expect
      Returns:
      updated builder instance

    • useParam

      public OidcConfig.Builder useParam(Boolean useParam)
      Whether to use a query parameter to send JWT token from application to this server.
      Parameters:
      useParam - whether to use a query parameter (true) or not (false)
      Returns:
      updated builder instance
      See Also:

    • cookieEncryptionName

      public OidcConfig.Builder cookieEncryptionName(String cookieEncryptionName)
      Name of the encryption configuration available through Security.encrypt(String, byte[]) and Security.decrypt(String, String). If configured and encryption is enabled for any cookie, Security MUST be configured in global or current io.helidon.common.context.Context (this is done automatically in Helidon MP).
      Parameters:
      cookieEncryptionName - name of the encryption configuration in security used to encrypt/decrypt cookies
      Returns:
      updated builder

    • cookieEncryptionPassword

      public OidcConfig.Builder cookieEncryptionPassword(char[] cookieEncryptionPassword)
      Master password for encryption/decryption of cookies. This must be configured to the same value on each microservice using the cookie. If encrypted cookies are enabled and this method and cookieEncryptionName(String) are not used, Helidon creates or reads a fallback .helidon-oidc-secret file in the current working directory.
      Parameters:
      cookieEncryptionPassword - encryption password
      Returns:
      updated builder

    • legacyCookieEncryption

      public OidcConfig.Builder legacyCookieEncryption(boolean legacyCookieEncryption)
      Whether password-based encrypted OIDC cookies should be written without a version byte and with the legacy PBKDF2 iteration count. This can be enabled during rolling upgrades so upgraded nodes continue creating cookies that older nodes can decrypt. Leave disabled for steady-state deployments and reset to false after all nodes run the new version. This setting does not affect named Security encryption configured with cookieEncryptionName(String). Defaults to false.
      Parameters:
      legacyCookieEncryption - whether cookies should be written with legacy password-based encryption
      Returns:
      updated builder instance

    • legacyCookieFallback

      public OidcConfig.Builder legacyCookieFallback(boolean legacyCookieFallback)
      Whether password-based encrypted OIDC cookies should retry decryption with the alternate cookie format after primary decryption fails. This can be enabled after a rolling upgrade to accept older unversioned legacy cookies until they expire, or while legacy writes must read versioned current cookies. Leave disabled for steady-state deployments and reset to false after legacy cookies expire. This setting does not affect named Security encryption configured with cookieEncryptionName(String). Defaults to false.
      Parameters:
      legacyCookieFallback - whether legacy cookie decryption fallback should be enabled
      Returns:
      updated builder instance

    • cookieEncryptionEnabled

      public OidcConfig.Builder cookieEncryptionEnabled(boolean cookieEncryptionEnabled)
      Whether to encrypt token cookie created by this microservice. Defaults to true.
      Parameters:
      cookieEncryptionEnabled - whether cookie should be encrypted true, or left unencrypted false
      Returns:
      updated builder instance

    • cookieCompressionEnabled

      public OidcConfig.Builder cookieCompressionEnabled(boolean cookieCompressionEnabled)
      Whether to GZIP-compress the access token cookie when this reduces its size. When encryption is enabled, compression is applied before encryption. Defaults to true when the top-level server-type is idcs, and to false otherwise. Disabling compression affects newly written cookies only; compressed cookies remain readable.
      Parameters:
      cookieCompressionEnabled - whether the access token cookie should be compressed
      Returns:
      updated builder instance

    • cookieEncryptionEnabledIdToken

      public OidcConfig.Builder cookieEncryptionEnabledIdToken(boolean cookieEncryptionEnabled)
      Whether to encrypt id token cookie created by this microservice. Defaults to true.
      Parameters:
      cookieEncryptionEnabled - whether cookie should be encrypted true, or as obtained from OIDC server false
      Returns:
      updated builder instance

    • cookieCompressionEnabledIdToken

      public OidcConfig.Builder cookieCompressionEnabledIdToken(boolean cookieCompressionEnabled)
      Whether to GZIP-compress the ID token cookie when this reduces its size. When encryption is enabled, compression is applied before encryption. Defaults to true when the top-level server-type is idcs, and to false otherwise. Disabling compression affects newly written cookies only; compressed cookies remain readable.
      Parameters:
      cookieCompressionEnabled - whether the ID token cookie should be compressed
      Returns:
      updated builder instance

    • cookieEncryptionEnabledTenantName

      public OidcConfig.Builder cookieEncryptionEnabledTenantName(boolean cookieEncryptionEnabled)
      Whether to encrypt tenant name cookie created by this microservice. Defaults to true.
      Parameters:
      cookieEncryptionEnabled - whether cookie should be encrypted true, or as plain text name false
      Returns:
      updated builder instance

    • cookieEncryptionEnabledRefreshToken

      public OidcConfig.Builder cookieEncryptionEnabledRefreshToken(boolean cookieEncryptionEnabled)
      Whether to encrypt refresh token cookie created by this microservice. Defaults to true.
      Parameters:
      cookieEncryptionEnabled - whether cookie should be encrypted true, or as obtained from OIDC server false
      Returns:
      updated builder instance

    • cookieEncryptionEnabledState

      public OidcConfig.Builder cookieEncryptionEnabledState(boolean cookieEncryptionEnabled)
      Whether to encrypt state cookie created by this microservice. Defaults to true.
      Parameters:
      cookieEncryptionEnabled - whether cookie should be encrypted true, or as sent to OIDC server false
      Returns:
      updated builder instance

    • cookieSameSite

      public OidcConfig.Builder cookieSameSite(String sameSite)
      When using cookie, used to set the SameSite cookie value. Can be "Strict" or "Lax"
      Parameters:
      sameSite - SameSite cookie attribute value
      Returns:
      updated builder instance

    • cookieSameSite

      public OidcConfig.Builder cookieSameSite(SetCookie.SameSite sameSite)
      When using cookie, used to set the SameSite cookie value. Can be "Strict" or "Lax".
      Parameters:
      sameSite - SameSite cookie attribute
      Returns:
      updated builder instance

    • cookieSecure

      public OidcConfig.Builder cookieSecure(Boolean secure)
      When using cookie, if set to true, the Secure attribute will be configured. Defaults to false.
      Parameters:
      secure - whether the cookie should be secure (true) or not (false)
      Returns:
      updated builder instance

    • cookieHttpOnly

      public OidcConfig.Builder cookieHttpOnly(Boolean httpOnly)
      When using cookie, if set to true, the HttpOnly attribute will be configured. Defaults to true.
      Parameters:
      httpOnly - whether the cookie should be HttpOnly (true) or not (false)
      Returns:
      updated builder instance

    • cookieMaxAgeSeconds

      public OidcConfig.Builder cookieMaxAgeSeconds(long age)
      When using cookie, used to set MaxAge attribute of the cookie, defining how long the cookie is valid. Not used by default.
      Parameters:
      age - age in seconds
      Returns:
      updated builder instance

    • cookiePath

      public OidcConfig.Builder cookiePath(String path)
      Path the cookie is valid for. Defaults to "/".
      Parameters:
      path - the path to use as value of cookie "Path" attribute
      Returns:
      updated builder instance

    • cookieDomain

      public OidcConfig.Builder cookieDomain(String domain)
      Domain the cookie is valid for. Not used by default.
      Parameters:
      domain - domain to use as value of cookie "Domain" attribute
      Returns:
      updated builder instance

    • cookieName

      public OidcConfig.Builder cookieName(String cookieName)
      Name of the cookie to use. Defaults to "JSESSIONID".
      Parameters:
      cookieName - name of a cookie
      Returns:
      updated builder instance

    • cookieNameIdToken

      public OidcConfig.Builder cookieNameIdToken(String cookieName)
      Name of the cookie to use for id token. Defaults to "JSESSIONID"_2. This cookie is only used when logout is enabled, as otherwise it is not needed. Content of this cookie is encrypted.
      Parameters:
      cookieName - name of a cookie
      Returns:
      updated builder instance

    • cookieTenantName

      public OidcConfig.Builder cookieTenantName(String cookieName)
      The name of the cookie to use for the tenant name. Defaults to "HELIDON_TENANT".
      Parameters:
      cookieName - name of a cookie
      Returns:
      updated builder instance

    • cookieNameRefreshToken

      public OidcConfig.Builder cookieNameRefreshToken(String cookieName)
      The name of the cookie to use for the refresh token. Defaults to "JSESSIONID_3".
      Parameters:
      cookieName - name of a cookie
      Returns:
      updated builder instance

    • cookieNameState

      public OidcConfig.Builder cookieNameState(String cookieName)
      The name of the cookie to use for the state storage. Defaults to "OIDC_STATE".
      Parameters:
      cookieName - name of a cookie
      Returns:
      updated builder instance

    • useCookie

      public OidcConfig.Builder useCookie(Boolean useCookie)
      Whether to use cookie to store JWT between requests. Defaults to true.
      Parameters:
      useCookie - whether to use cookie to store JWT (true) or not (false))
      Returns:
      updated builder instance

    • addTenantConfig

      public OidcConfig.Builder addTenantConfig(TenantConfig tenantConfig)
      Add specific TenantConfig instance.
      Parameters:
      tenantConfig - tenant configuration
      Returns:
      updated builder instance

    • tokenSignatureValidation

      public OidcConfig.Builder tokenSignatureValidation(boolean enabled)
      Whether access token signature check should be enabled. Signature check is enabled by default, and it is highly recommended to not change that. Change this setting only when you really know what you are doing, otherwise it could case security issues.
      Parameters:
      enabled - whether access token signature check is enabled
      Returns:
      updated builder instance

    • idTokenSignatureValidation

      public OidcConfig.Builder idTokenSignatureValidation(boolean enabled)
      Whether id token signature check should be enabled. Signature check is enabled by default, and it is highly recommended to not change that. Change this setting only when you really know what you are doing, otherwise it could case security issues.
      Parameters:
      enabled - whether id token signature check is enabled
      Returns:
      updated builder instance

    • accessTokenIpCheck

      public OidcConfig.Builder accessTokenIpCheck(boolean enabled)
      Whether to check if current IP address matches the one access token was issued for. This check helps with cookie replay attack prevention.
      Parameters:
      enabled - whether to check if current IP address matches the one access token was issued for
      Returns:
      updated builder instance

    • pkceEnabled

      public OidcConfig.Builder pkceEnabled(boolean enabled)
      Whether this provider should support PKCE. Default value is false.
      Parameters:
      enabled - PKCE enabled
      Returns:
      updated builder instance

    • pkceChallengeMethod

      public OidcConfig.Builder pkceChallengeMethod(PkceChallengeMethod pkceChallengeMethod)
      Proof Key Code Exchange (PKCE) challenge creation method. Default value is PkceChallengeMethod.S256.
      Parameters:
      pkceChallengeMethod - challenge creation method
      Returns:
      updated builder instance

    • webclient

      public OidcConfig.Builder webclient(Consumer<WebClientConfig.Builder> builderConsumer)
      WebClient configuration consumer. This configuration is used for outbound requests to the identity server.
      Parameters:
      builderConsumer - webclient config builder consumer
      Returns:
      updated builder instance

    • clientTimeout

      public OidcConfig.Builder clientTimeout(Duration duration)
      Description copied from class: BaseBuilder
      Timeout of calls using web client.
      Overrides:
      clientTimeout in class BaseBuilder<OidcConfig.Builder,OidcConfig>
      Parameters:
      duration - timeout
      Returns:
      updated builder

    • clientCredentialsConfig

      public OidcConfig.Builder clientCredentialsConfig(ClientCredentialsConfig clientCredentialsConfig)
      Set the configuration related to the client credentials flow.
      Parameters:
      clientCredentialsConfig - client credentials configuration
      Returns:
      updated builder instance

    • clientCredentialsConfig

      public OidcConfig.Builder clientCredentialsConfig(Consumer<ClientCredentialsConfig.Builder> builderConsumer)
      Configure client credentials configuration over the builder consumer.
      Parameters:
      builderConsumer - builder consumer
      Returns:
      updated builder instance