Class 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 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
    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 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.
    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.
    • Field Detail

      • PARAM_HEADER_NAME

        public static final String PARAM_HEADER_NAME
        Default name of the header we expect JWT in.
        See Also:
        Constant Field Values
      • DEFAULT_TENANT_PARAM_NAME

        public static final String DEFAULT_TENANT_PARAM_NAME
        Default tenant query param name.
        See Also:
        Constant Field Values
    • Method Detail

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

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

        public boolean useHeader()
        Whether to use HTTP header to get the information from request.
        Returns:
        if header should be used
        See Also:
        OidcConfig.Builder.useHeader(Boolean)
      • 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
      • 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
      • 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
      • 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.
        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
      • 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:
        BaseBuilder.tokenEndpointUri(URI)
      • 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:
        BaseBuilder.introspectEndpointUri(URI)
      • 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
        See Also:
        BaseBuilder.tokenEndpointUri(java.net.URI)
      • authorizationEndpointUri

        public String authorizationEndpointUri()
        Authorization endpoint.
        Returns:
        authorization endpoint uri as a string
        See Also:
        BaseBuilder.authorizationEndpointUri(URI)
      • 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
        See Also:
        BaseBuilder.signJwk(JwkKeys)
      • introspectUri

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

        @Deprecated(since="2.5.5",
                    forRemoval=true)
        public void updateRequest​(OidcConfig.RequestType type,
                                  WebClientRequestBuilder request,
                                  FormParams.Builder form)
        Deprecated, for removal: This API element is subject to removal in a future version.
        this will be removed without replacement
        Update request that uses form params with authentication.
        Parameters:
        type - type of the request
        request - request builder
        form - form params builder
      • 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
        See Also:
        BaseBuilder.signJwk(JwkKeys)
      • 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
        See Also:
        BaseBuilder.logoutEndpointUri(java.net.URI)
      • 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
        See Also:
        BaseBuilder.tokenEndpointUri(java.net.URI)
      • clientId

        public String clientId()
        Description copied from interface: TenantConfig
        Client id of this client.
        Specified by:
        clientId in interface TenantConfig
        Returns:
        client id
        See Also:
        BaseBuilder.clientId(String)
      • 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
        See Also:
        BaseBuilder.baseScopes(String)
      • 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
        See Also:
        BaseBuilder.validateJwtWithJwk(Boolean)
      • 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
        See Also:
        BaseBuilder.introspectEndpointUri(java.net.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
        See Also:
        BaseBuilder.issuer(String)
      • audience

        public String audience()
        Description copied from interface: TenantConfig
        Expected token audience.
        Specified by:
        audience in interface TenantConfig
        Returns:
        audience
        See Also:
        BaseBuilder.audience(String)
      • scopeAudience

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

        public URI identityUri()
        Description copied from interface: TenantConfig
        Identity server URI.
        Specified by:
        identityUri in interface TenantConfig
        Returns:
        identity server URI
        See Also:
        BaseBuilder.identityUri(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
      • 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
        See Also:
        BaseBuilder.authorizationEndpointUri(URI)
      • clientSecret

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

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

        public JsonObject oidcMetadata()
        Description copied from interface: TenantConfig
        OIDC metadata.
        Specified by:
        oidcMetadata in interface TenantConfig
        Returns:
        configured oidc metadata
        See Also:
        BaseBuilder.oidcMetadata(JsonObject)
      • 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
        See Also:
        BaseBuilder.oidcMetadataWellKnown(boolean)