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

Class OidcConfig

java.lang.Object
io.helidon.security.providers.oidc.common.OidcConfig
All Implemented Interfaces:
TenantConfig
public final class OidcConfig extends Object
Configuration of OIDC usable from all resources that utilize OIDC specification, such as security provider, web server extension and IDCS connectivity.

Some of the configuration options below use "resource" type. The following configuration can be used for a resource (example for oidc-metadata key): oidc-metadata-path: "path/on/filesystem" oidc-metadata-resource-path: "class-path/resource" oidc-metadata-url: "URI on the net" oidc-metadata-content-plain: "Value of the resource in plain text" oidc-metadata-content: "Value in base64 encoded bytes"

Configuration options required (under security.providers[].${name}):

Mandatory configuration parameters
key description
client-id Client ID as generated by OIDC server
client-secret Client secret as generated by OIDC server
identity-uri URI of the identity server, base used to retrieve OIDC metadata
frontend-uri Full URI of the frontend for redirects back from OIDC server (e.g. http://myserver/myApp)
Optional configuration parameters
key default value description
proxy-protocol http Proxy protocol to use when proxy is used.
proxy-host null Proxy host to use. When defined, triggers usage of proxy for HTTP requests.
proxy-port 80 Port of the proxy server to use
relative-uris false Flag to force the use of relative URIs in all requests. By default, requests that use the Proxy will have absolute URIs. Set this flag to true if the host is unable to accept absolute URIs.
redirect-uri /oidc/redirect 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.
scope-audience empty string Audience of the scope required by this application. This is prefixed to the scope name when requesting scopes from the identity server.
cookie-use true Whether to use cookie to store JWT. If used, redirects happen only in case the user is not authenticated or has insufficient scopes
cookie-name JSESSIONID Name of the cookie
cookie-domain null Domain the cookie is valid for. Not used by default
cookie-path / Path the cookie is valid for.
cookie-max-age-seconds null When using cookie, used to set MaxAge attribute of the cookie, defining how long the cookie is valid.
cookie-http-only true When using cookie, if set to true, the HttpOnly attribute will be configured.
cookie-secure false When using cookie, if set to true, the Secure attribute will be configured.
cookie-same-site Lax When using cookie, used to set the SameSite cookie value. Can be "Strict" or "Lax". Setting this to "Strict" will result in infinite redirects when calling OIDC on a different host.
query-param-use false Whether to expect JWT in a query parameter
query-param-name accessToken Name of a query parameter that contains the JWT token when parameter is used.
header-use true Whether to expect JWT in a header field.
header-token "Authorization" header with prefix "bearer " A TokenHandler configuration to process header containing a JWT
oidc-metadata-well-known true If set to true, metadata will be loaded from default (well known) location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. token-endpoint-uri).
oidc-metadata.resource identity-uri/.well-known/openid-configuration Resource configuration for OIDC Metadata containing endpoints to various identity services, as well as information about the identity server. See Resource.create(io.helidon.common.config.Config)
token-endpoint-uri token_endpoint in OIDC metadata, or identity-url/oauth2/v1/token if not available URI of a token endpoint used to obtain a JWT based on the authentication code.
authorization-endpoint-uri "authorization_endpoint" in OIDC metadata, or identity-uri/oauth2/v1/authorize if not available URI of an authorization endpoint used to redirect users to for logging-in.
validate-with-jwk true When true - validate against jwk defined by "sign-jwk", when false validate JWT through OIDC Server endpoint "validation-endpoint-uri"
sign-jwk.resource "jwks-uri" in OIDC metadata, or identity-uri/admin/v1/SigningCert/jwk if not available, only needed when jwt validation is done by us A resource pointing to JWK with public keys of signing certificates used to validate JWT. See Resource.create(io.helidon.common.config.Config)
introspect-endpoint-uri "introspection_endpoint" in OIDC metadata, or identity-uri/oauth2/v1/introspect When validate-with-jwk is set to "false", this is the endpoint used
base-scopes "openid"<B extends io.helidon.security.providers.oidc.common.BaseBuilder<B,T>,T> Configure scopes to be requested by default. If the scope has a qualifier, it must be included here
redirect false Whether to redirect to identity server when authentication failed.
realm helidon Realm returned in HTTP response if redirect is not enabled or possible.
redirect-attempt-param "h_ra" Query parameter holding the number of times we redirected to an identity server. Customizable to prevent conflicts with application parameters
max-redirects 5 Maximal number of times we can redirect to an identity server. When the number is reached, no further redirects happen and the request finishes with an error (status 401)
server-type   Type of identity server. Currently supported is idcs or not configured (for default).
client-timeout-millis 30 seconds Timeout on HTTP client calls
cookie-encryption-enabled Depends on other configuration Whether cookies should be encrypted. Will be enabled if logout is enabled.
cookie-encryption-password Generated for this service (as a file) Encryption password to be used for symmetric cipher. Must be the same for all services that are intended to share a cookie as a form of authentication
cookie-encryption-name   Name of encryption configuration in Security. If used, security must be registered in curent context or in global context (this is done automatically in Helidon MP).
logout-endpoint-uri From well known metadata endpoint Endpoint to redirect user to log out from OIDC server.
post-logout-uri   Required if logout is enabled. Endpoint the OIDC server redirects back to after logging user out.
logout-enabled false Whether logout support should be enabled. Requires encryption of cookies (and cookies must be used).
cors   Cross-origin resource sharing settings. See CrossOriginConfig.
force-https-redirects   Force https for redirects to identity provider. This is helpful if you have a frontend SSL or cloud load balancer in front and Helidon is serving plain http.
optional-audience false Allow audience claim to be optional.
check-audience true Turn audience claim check on when true or off when false.

  • Field Details

    • PARAM_HEADER_NAME

      public static final String PARAM_HEADER_NAME
      Default name of the header we expect JWT in.
      See Also:

    • PARAM_ID_HEADER_NAME

      public static final String PARAM_ID_HEADER_NAME
      Default name of the header we expect JWT in.
      See Also:

    • DEFAULT_TENANT_PARAM_NAME

      public static final String DEFAULT_TENANT_PARAM_NAME
      Default tenant query param name.
      See Also:

  • Method Details

    • builder

      public static OidcConfig.Builder builder()
      Create a builder to programmatically construct OIDC configuration.
      Returns:
      a new builder instance usable for fluent API

    • create

      public static OidcConfig create(Config config)
      Create a new instance from Config. The config instance has to be on the node containing keys used by this class (e.g. client-id).
      Parameters:
      config - configuration used to obtain OIDC integration values
      Returns:
      a new instance of this class configured from provided config

    • useParam

      public boolean useParam()
      Whether to use query parameter to get the information from request.
      Returns:
      if query parameter should be used
      See Also:

    • paramName

      public String paramName()
      Query parameter name.
      Returns:
      name of the query parameter to use
      See Also:

    • idTokenParamName

      public String idTokenParamName()
      Query id token parameter name.
      Returns:
      name of the query parameter to use
      See Also:

    • tenantParamName

      public String tenantParamName()
      Tenant query parameter name.
      Returns:
      name of the tenant query parameter to use
      See Also:

    • useHeader

      public boolean useHeader()
      Whether to use HTTP header to get the information from request.
      Returns:
      if header should be used
      See Also:

    • headerHandler

      public TokenHandler headerHandler()
      TokenHandler to extract header information from request.
      Returns:
      handler to extract header
      See Also:

    • useCookie

      public boolean useCookie()
      Whether to use cooke to get the information from request.
      Returns:
      if cookie should be used
      See Also:

    • tokenCookieHandler

      public OidcCookieHandler tokenCookieHandler()
      Cookie handler to create cookies or unset cookies for token.
      Returns:
      a new cookie handler

    • idTokenCookieHandler

      public OidcCookieHandler idTokenCookieHandler()
      Cookie handler to create cookies or unset cookies for id token.
      Returns:
      a new cookie handler

    • tenantCookieHandler

      public OidcCookieHandler tenantCookieHandler()
      Cookie handler to create cookies or unset cookies for tenant name.
      Returns:
      a new cookie handler

    • refreshTokenCookieHandler

      public OidcCookieHandler refreshTokenCookieHandler()
      Cookie handler to create cookies or unset cookies for refresh token.
      Returns:
      a new cookie handler

    • stateCookieHandler

      public OidcCookieHandler stateCookieHandler()
      Cookie handler to create cookies or unset cookies for state value.
      Returns:
      a new cookie handler

    • redirectUri

      public String redirectUri()
      Redirection URI.
      Returns:
      uri the OIDC server redirects back to
      See Also:

    • forceHttpsRedirects

      public boolean forceHttpsRedirects()
      Whether to force https when redirecting to identity provider.
      Returns:
      true to force use of https

    • logoutEnabled

      public boolean logoutEnabled()
      Whether logout is enabled.
      Returns:
      true if logout is enabled

    • logoutUri

      public String logoutUri()
      Logout URI.
      Returns:
      uri that processes logout in Helidon and redirects to OIDC server logout
      See Also:

    • postLogoutUri

      public URI postLogoutUri()
      Post logout redirect URI.
      Returns:
      uri that OIDC server redirects to once logout is finished
      See Also:

    • redirectUriWithHost

      public String redirectUriWithHost()
      Redirect URI with host information.
      Returns:
      redirect URI
      See Also:

    • redirectUriWithHost

      public String redirectUriWithHost(String frontendUri)
      Redirect URI with host information taken from request, unless an explicit frontend uri is defined in configuration.
      Parameters:
      frontendUri - the frontend uri
      Returns:
      redirect URI

    • shouldRedirect

      public boolean shouldRedirect()
      Whether to redirect to identity server if user is not authenticated.
      Returns:
      whether to redirect, defaults to true

    • redirectAttemptParam

      public String redirectAttemptParam()
      Name of the parameter used in state passed to OIDC to store the number of attempted redirects. This is to prevent infinite redirects.
      Returns:
      name of the query parameter

    • maxRedirects

      public int maxRedirects()
      Maximal number of redirects allowed between Helidon and OIDC provider.
      Returns:
      maximal number of redirects

    • crossOriginConfig

      public CrossOriginConfig crossOriginConfig()
      Cross-origin resource sharing settings.
      Returns:
      CORS settings

    • tokenRefreshSkew

      public Duration tokenRefreshSkew()
      Amount of time access token should be refreshed before its expiration time.
      Returns:
      refresh time skew

    • relativeUris

      public boolean relativeUris()
      Determines whether to force the use of relative URIs in all requests, regardless of the presence or absence of proxies or no-proxy lists.
      Returns:
      true if we should use relative URIs

    • generalWebClient

      public WebClient generalWebClient()
      Client with configured proxy with no security.
      Returns:
      client for general use.

    • appWebClient

      public WebClient appWebClient()
      Client with configured proxy and security.
      Returns:
      client for communicating with OIDC identity server

    • tenantConfig

      public TenantConfig tenantConfig(String tenantId)
      Return TenantConfig bound to the provided tenant id. If no TenantConfig found, default OIDC configuration should be returned.
      Parameters:
      tenantId - tenant id of the configuration
      Returns:
      configuration bound to the tenant id, or default oidc configuration if not found

    • tokenEndpointUri

      public URI tokenEndpointUri()
      Token endpoint URI.
      Returns:
      endpoint URI

    • authorizationEndpointUri

      public String authorizationEndpointUri()
      Authorization endpoint.
      Returns:
      authorization endpoint uri as a string

    • logoutEndpointUri

      public URI logoutEndpointUri()
      Logout endpoint on OIDC server.
      Returns:
      URI of the logout endpoint
      See Also:
      • BaseBuilder.logoutEndpointUri(java.net.URI)

    • issuer

      public String issuer()
      Token issuer.
      Returns:
      token issuer
      See Also:
      • BaseBuilder.issuer(String)

    • signJwk

      public JwkKeys signJwk()
      JWK used for signature validation.
      Returns:
      set of keys used use to verify tokens

    • introspectUri

      public URI introspectUri()
      Introspection endpoint URI.
      Returns:
      introspection endpoint URI
      See Also:
      • BaseBuilder.introspectEndpointUri(java.net.URI)

    • tokenSignatureValidation

      public boolean tokenSignatureValidation()
      Whether access token signature should be validated.
      Returns:
      validate access token signature

    • idTokenSignatureValidation

      public boolean idTokenSignatureValidation()
      Whether id token signature should be validated.
      Returns:
      validate id token signature

    • tenantSignJwk

      public Optional<JwkKeys> tenantSignJwk()
      Description copied from interface: TenantConfig
      JWK used for signature validation. Empty if no jwk has been provided via configuration.
      Specified by:
      tenantSignJwk in interface TenantConfig
      Returns:
      set of keys used to verify tokens

    • tenantLogoutEndpointUri

      public Optional<URI> tenantLogoutEndpointUri()
      Description copied from interface: TenantConfig
      Logout endpoint on OIDC server. Empty if no logout endpoint uri has been provided via configuration.
      Specified by:
      tenantLogoutEndpointUri in interface TenantConfig
      Returns:
      URI of the logout endpoint

    • tenantTokenEndpointUri

      public Optional<URI> tenantTokenEndpointUri()
      Description copied from interface: TenantConfig
      Token endpoint URI. Empty if no token endpoint uri has been provided via configuration.
      Specified by:
      tenantTokenEndpointUri in interface TenantConfig
      Returns:
      endpoint URI

    • clientId

      public String clientId()
      Description copied from interface: TenantConfig
      Client id of this client.
      Specified by:
      clientId in interface TenantConfig
      Returns:
      client id

    • name

      public String name()
      Description copied from interface: TenantConfig
      Name of the tenant.
      Specified by:
      name in interface TenantConfig
      Returns:
      tenant name

    • baseScopes

      public String baseScopes()
      Description copied from interface: TenantConfig
      Base scopes to require from OIDC server.
      Specified by:
      baseScopes in interface TenantConfig
      Returns:
      base scopes

    • validateJwtWithJwk

      public boolean validateJwtWithJwk()
      Description copied from interface: TenantConfig
      Whether to validate JWT with JWK information (e.g. verify signatures locally).
      Specified by:
      validateJwtWithJwk in interface TenantConfig
      Returns:
      if we should validate JWT with JWK

    • tenantIntrospectUri

      public Optional<URI> tenantIntrospectUri()
      Description copied from interface: TenantConfig
      Introspection endpoint URI. Empty if no introspection endpoint has been provided via configuration.
      Specified by:
      tenantIntrospectUri in interface TenantConfig
      Returns:
      introspection endpoint URI

    • tenantIssuer

      public Optional<String> tenantIssuer()
      Description copied from interface: TenantConfig
      Return provided token issuer. Empty if no issuer has been provided via configuration.
      Specified by:
      tenantIssuer in interface TenantConfig
      Returns:
      token issuer

    • audience

      public String audience()
      Description copied from interface: TenantConfig
      Expected token audience.
      Specified by:
      audience in interface TenantConfig
      Returns:
      audience

    • checkAudience

      public boolean checkAudience()
      Description copied from interface: TenantConfig
      Whether to validate audience token.
      Specified by:
      checkAudience in interface TenantConfig
      Returns:
      audience

    • scopeAudience

      public String scopeAudience()
      Description copied from interface: TenantConfig
      Audience URI of custom scopes.
      Specified by:
      scopeAudience in interface TenantConfig
      Returns:
      scope audience

    • identityUri

      public URI identityUri()
      Description copied from interface: TenantConfig
      Identity server URI.
      Specified by:
      identityUri in interface TenantConfig
      Returns:
      identity server URI

    • realm

      public String realm()
      Description copied from interface: TenantConfig
      Realm to use for WWW-Authenticate response (if needed).
      Specified by:
      realm in interface TenantConfig
      Returns:
      realm name

    • tokenEndpointAuthentication

      public OidcConfig.ClientAuthentication tokenEndpointAuthentication()
      Description copied from interface: TenantConfig
      Type of authentication mechanism used for token endpoint.
      Specified by:
      tokenEndpointAuthentication in interface TenantConfig
      Returns:
      client authentication type

    • clientTimeout

      public Duration clientTimeout()
      Description copied from interface: TenantConfig
      Expected timeout of HTTP client operations.
      Specified by:
      clientTimeout in interface TenantConfig
      Returns:
      client timeout

    • authorizationEndpoint

      public Optional<URI> authorizationEndpoint()
      Description copied from interface: TenantConfig
      Authorization endpoint.
      Specified by:
      authorizationEndpoint in interface TenantConfig
      Returns:
      authorization endpoint uri as a string

    • clientSecret

      public String clientSecret()
      Description copied from interface: TenantConfig
      Client secret.
      Specified by:
      clientSecret in interface TenantConfig
      Returns:
      configured client secret

    • serverType

      public String serverType()
      Description copied from interface: TenantConfig
      Server type.
      Specified by:
      serverType in interface TenantConfig
      Returns:
      configured server type

    • oidcMetadata

      public JsonObject oidcMetadata()
      Description copied from interface: TenantConfig
      OIDC metadata.
      Specified by:
      oidcMetadata in interface TenantConfig
      Returns:
      configured oidc metadata

    • useWellKnown

      public boolean useWellKnown()
      Description copied from interface: TenantConfig
      Whether to use OIDC well known metadata.
      Specified by:
      useWellKnown in interface TenantConfig
      Returns:
      configured oidc metadata