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

Class OidcConfig.Builder

    • Constructor Detail

      • Builder

        protected Builder()

    • Method Detail

      • 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.
        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 its expiration time. Default is 5 seconds.
        Parameters:
        tokenRefreshSkew - time to refresh token before expiration
        Returns:
        updated builder

      • crossOriginConfig

        public OidcConfig.Builder crossOriginConfig​(CrossOriginConfig crossOriginConfig)
        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. When logout is enabled, we use two cookies (User token and user ID token) and we expose an endpoint logoutUri(String) that can be used to log the user out from Helidon session and also from OIDC session (uses logoutEndpointUri(java.net.URI) on OIDC server). Logout support is disabled by default.
        Parameters:
        logoutEnabled - whether to enable logout
        Returns:
        updated builder instance

      • redirect

        public OidcConfig.Builder redirect​(boolean redirect)
        By default, the client should redirect to the identity server for the user to log in. This behavior can be overridden by setting redirect to false. When token is not present in the request, the client will not redirect and just return appropriate error response code.
        Parameters:
        redirect - Whether to redirect to OIDC server in case the request does not contain sufficient information to authenticate the user, defaults to true
        Returns:
        updated builder instance

      • frontendUri

        public OidcConfig.Builder frontendUri​(String uri)
        Full URI of this application that is visible from user browser. Used to redirect request back from identity server after successful login.
        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. Defaults to false.
        Parameters:
        forceHttpsRedirects - flag to redirect with https
        Returns:
        updated builder instance

      • relativeUris

        public OidcConfig.Builder relativeUris​(boolean relativeUris)
        Can be set to true to force the use of relative URIs in all requests, regardless of the presence or absence of proxies or no-proxy lists. 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. Defaults to false.
        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 parameter used to store the number of attempts in redirect.

        Defaults to "h_ra"

        Parameters:
        paramName - name of the parameter used in the state parameter
        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

        public OidcConfig.Builder proxyProtocol​(String protocol)
        Proxy protocol to use when proxy is used. Defaults to "http".
        Parameters:
        protocol - protocol to use (such as https)
        Returns:
        updated builder instance

      • proxyHost

        public OidcConfig.Builder proxyHost​(String proxyHost)
        Proxy host to use. When defined, triggers usage of proxy for HTTP requests. Setting to empty String has the same meaning as setting to null - disables proxy.
        Parameters:
        proxyHost - host of the proxy
        Returns:
        updated builder instance
        See Also:
        proxyProtocol(String), proxyPort(int)

      • proxyPort

        public OidcConfig.Builder proxyPort​(int proxyPort)
        Proxy port. Defaults to 80
        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

      • paramName

        public OidcConfig.Builder paramName​(String paramName)
        Name of a query parameter that contains the JWT token when parameter is used.
        Parameters:
        paramName - 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 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:
        paramName(String)

      • 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.
        Parameters:
        cookieEncryptionPassword - encryption password
        Returns:
        updated builder

      • cookieEncryptionEnabled

        public OidcConfig.Builder cookieEncryptionEnabled​(boolean cookieEncryptionEnabled)
        Whether to encrypt token cookie created by this microservice. Defaults to false.
        Parameters:
        cookieEncryptionEnabled - whether cookie should be encrypted true, or as obtained from OIDC server false
        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

      • 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 obtained from 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)
        Name of the cookie to use for tenant name. Defaults to "HELIDON_TENANT".
        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

      • clientId

        public B clientId​(String clientId)
        Client ID as generated by OIDC server.
        Parameters:
        clientId - the client id of this application.
        Returns:
        updated builder instance

      • clientSecret

        public B clientSecret​(String clientSecret)
        Client secret as generated by OIDC server. Used to authenticate this application with the server when requesting JWT based on a code.
        Parameters:
        clientSecret - secret to use
        Returns:
        updated builder instance

      • identityUri

        public B identityUri​(URI uri)
        URI of the identity server, base used to retrieve OIDC metadata.
        Parameters:
        uri - full URI of an identity server (such as "http://tenantid.identity.oraclecloud.com")
        Returns:
        updated builder instance

      • realm

        public B realm​(String realm)
        Realm to return when not redirecting and an error occurs that sends back WWW-Authenticate header.
        Parameters:
        realm - realm name
        Returns:
        updated builder instance

      • audience

        public B audience​(String audience)
        Audience of issued tokens.
        Parameters:
        audience - audience to validate
        Returns:
        updated builder instance

      • issuer

        public B issuer​(String issuer)
        Issuer of issued tokens.
        Parameters:
        issuer - expected issuer to validate
        Returns:
        updated builder instance

      • validateJwtWithJwk

        public B validateJwtWithJwk​(Boolean useJwk)
        Use JWK (a set of keys to validate signatures of JWT) to validate tokens. Use this method when you want to use default values for JWK or introspection endpoint URI.
        Parameters:
        useJwk - when set to true, jwk is used, when set to false, introspect endpoint is used
        Returns:
        updated builder instance

      • introspectEndpointUri

        public B introspectEndpointUri​(URI uri)
        Endpoint to use to validate JWT. Either use this or set signJwk(JwkKeys) or signJwk(Resource).
        Parameters:
        uri - URI of introspection endpoint
        Returns:
        updated builder instance

      • signJwk

        public B signJwk​(Resource resource)
        A resource pointing to JWK with public keys of signing certificates used to validate JWT.
        Parameters:
        resource - Resource pointing to the JWK
        Returns:
        updated builder instance

      • signJwk

        public B signJwk​(JwkKeys jwk)
        Set JwkKeys to use for JWT validation.
        Parameters:
        jwk - JwkKeys instance to get public keys used to sign JWT
        Returns:
        updated builder instance

      • authorizationEndpointUri

        public B authorizationEndpointUri​(URI uri)
        URI of an authorization endpoint used to redirect users to for logging-in. If not defined, it is obtained from oidcMetadata(Resource), if that is not defined an attempt is made to use identityUri(URI)/oauth2/v1/authorize.
        Parameters:
        uri - URI to use for token endpoint
        Returns:
        updated builder instance

      • logoutEndpointUri

        public B logoutEndpointUri​(URI logoutEndpointUri)
        URI of a logout endpoint used to redirect users to for logging-out. If not defined, it is obtained from oidcMetadata(Resource), if that is not defined an attempt is made to use identityUri(URI)/oauth2/v1/userlogout.
        Parameters:
        logoutEndpointUri - URI to use to log out
        Returns:
        updated builder instance

      • tokenEndpointUri

        public B tokenEndpointUri​(URI uri)
        URI of a token endpoint used to obtain a JWT based on the authentication code. If not defined, it is obtained from oidcMetadata(Resource), if that is not defined an attempt is made to use identityUri(URI)/oauth2/v1/token.
        Parameters:
        uri - URI to use for token endpoint
        Returns:
        updated builder instance

      • oidcMetadata

        public B oidcMetadata​(Resource resource)
        Resource configuration for OIDC Metadata containing endpoints to various identity services, as well as information about the identity server.
        Parameters:
        resource - resource pointing to the JSON structure
        Returns:
        updated builder instance

      • oidcMetadata

        public B oidcMetadata​(JsonObject metadata)
        JsonObject with the OIDC Metadata.
        Parameters:
        metadata - metadata JSON
        Returns:
        updated builder instance
        See Also:
        oidcMetadata(Resource)

      • baseScopes

        public B baseScopes​(String scopes)
        Configure base scopes. By default, this is "openid". If scope has a qualifier, it must be used here.
        Parameters:
        scopes - Space separated scopes to be required by default from OIDC server
        Returns:
        updated builder instance

      • oidcMetadataWellKnown

        public B oidcMetadataWellKnown​(boolean useWellKnown)
        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).
        Parameters:
        useWellKnown - whether to use well known location for OIDC metadata
        Returns:
        updated builder instance

      • serverType

        public B serverType​(String type)
        Configure one of the supported types of identity servers. If the type does not have an explicit mapping, a warning is logged and the default implementation is used.
        Parameters:
        type - Type of identity server. Currently supported is idcs or not configured (for default).
        Returns:
        updated builder instance

      • clientTimeout

        public B clientTimeout​(Duration duration)
        Timeout of calls using web client.
        Parameters:
        duration - timeout
        Returns:
        updated builder

      • scopeAudience

        public B scopeAudience​(String audience)
        Audience of the scope required by this application. This is prefixed to the scope name when requesting scopes from the identity server. Defaults to empty string.
        Parameters:
        audience - audience, if provided, end with "/" to append the scope correctly
        Returns:
        updated builder instance

      • useWellKnown

        public boolean useWellKnown()