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
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 Fully 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
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 false 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.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.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" Configure scopes to be requested by default. If the scope has a qualifier, it must be included here
redirect true 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.

  • Field Details

    • PARAM_HEADER_NAME

      public static final String PARAM_HEADER_NAME
      Default name of the header we expect JWT in.
      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

    • postJsonResponse

      public static <T> Single<T> postJsonResponse(WebClientRequestBuilder requestBuilder, Object toSubmit, Function<JsonObject,T> jsonProcessor, BiFunction<Http.ResponseStatus,String,Optional<T>> errorEntityProcessor, BiFunction<Throwable,String,Optional<T>> errorProcessor)
      Processing of WebClient submit using a POST method. This is a helper method to handle possible cases (success, failure with readable entity, failure).
      Type Parameters:
      T - type of the result the call
      Parameters:
      requestBuilder - WebClient request builder
      toSubmit - object to submit (such as FormParams
      jsonProcessor - processor of successful JSON response
      errorEntityProcessor - processor of an error that has an entity, to fail the single
      errorProcessor - processor of an error that does not have an entity
      Returns:
      a future that completes successfully if processed from json, or if an error processor returns a non-empty value, completes with error otherwise

    • signJwk

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

    • redirectUri

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

    • 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:

    • tokenEndpoint

      @Deprecated(forRemoval=true, since="2.4.0") public WebTarget tokenEndpoint()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Please use appWebClient() and tokenEndpointUri() instead; result of moving to reactive webclient from JAX-RS client
      Token endpoint of the OIDC server.
      Returns:
      target the endpoint is on
      See Also:

    • tokenEndpointUri

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

    • 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:

    • useCookie

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

    • cookieName

      @Deprecated(forRemoval=true, since="2.4.0") public String cookieName()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use tokenCookieHandler() instead
      Cookie name.
      Returns:
      name of the cookie to use
      See Also:

    • cookieOptions

      @Deprecated(forRemoval=true, since="2.4.0") public String cookieOptions()
      Deprecated, for removal: This API element is subject to removal in a future version.
      please use tokenCookieHandler() instead
      Additional options of the cookie to use.
      Returns:
      cookie options to use in cookie string
      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

    • 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:

    • cookieValuePrefix

      @Deprecated(forRemoval=true, since="2.4.0") public String cookieValuePrefix()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use OidcCookieHandler instead, this method will no longer be avilable
      Prefix of a cookie header formed by name and "=".
      Returns:
      prefix of cookie value
      See Also:

    • scopeAudience

      public String scopeAudience()
      Audience URI of custom scopes.
      Returns:
      scope audience
      See Also:

    • authorizationEndpointUri

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

    • logoutEndpointUri

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

    • clientId

      public String clientId()
      Client id of this client.
      Returns:
      client id
      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

    • baseScopes

      public String baseScopes()
      Base scopes to require from OIDC server.
      Returns:
      base scopes
      See Also:

    • validateJwtWithJwk

      public boolean validateJwtWithJwk()
      Whether to validate JWT with JWK information (e.g. verify signatures locally).
      Returns:
      if we should validate JWT with JWK
      See Also:

    • introspectEndpoint

      @Deprecated(forRemoval=true, since="2.4.0") public WebTarget introspectEndpoint()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Please use appWebClient() and introspectUri() instead; result of moving to reactive webclient from JAX-RS client
      Token introspection endpoint.
      Returns:
      introspection endpoint
      See Also:

    • introspectUri

      public URI introspectUri()
      Introspection endpoint URI.
      Returns:
      introspection endpoint URI
      See Also:

    • issuer

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

    • audience

      public String audience()
      Expected token audience.
      Returns:
      audience
      See Also:

    • identityUri

      public URI identityUri()
      Identity server URI.
      Returns:
      identity server URI
      See Also:

    • generalClient

      @Deprecated(forRemoval=true, since="2.4.0") public Client generalClient()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use generalWebClient() instead
      Client with configured proxy with no security.
      Returns:
      client for general use.

    • generalWebClient

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

    • appClient

      @Deprecated(forRemoval=true, since="2.4.0") public Client appClient()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use appWebClient()
      Client with configured proxy and security of this OIDC client.
      Returns:
      client for communication with OIDC server

    • appWebClient

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

    • shouldRedirect

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

    • realm

      public String realm()
      Realm to use for WWW-Authenticate response (if needed).
      Returns:
      realm name

    • 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

    • tokenEndpointAuthentication

      public OidcConfig.ClientAuthentication tokenEndpointAuthentication()
      Type of authentication mechanism used for token endpoint.
      Returns:
      client authentication type

    • updateRequest

      public void updateRequest(OidcConfig.RequestType type, WebClientRequestBuilder request, FormParams.Builder form)
      Update request that uses form params with authentication.
      Parameters:
      type - type of the request
      request - request builder
      form - form params builder

    • clientTimeout

      public Duration clientTimeout()
      Expected timeout of HTTP client operations.
      Returns:
      client timeout

    • crossOriginConfig

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