Class OidcConfig
java.lang.Object
io.helidon.security.providers.oidc.common.OidcConfig
- All Implemented Interfaces:
TenantConfig
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}):
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) |
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.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 | 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. |
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
A fluent APIBuilder
to build instances ofOidcConfig
.static enum
Client Authentication methods that are used by Clients to authenticate to the Authorization Server when using the Token Endpoint.static enum
Types of requests to identity provider. -
Field Summary
-
Method Summary
Modifier and TypeMethodDescriptionDeprecated, for removal: This API element is subject to removal in a future version.Client with configured proxy and security.audience()
Expected token audience.Authorization endpoint.Authorization endpoint.Base scopes to require from OIDC server.static OidcConfig.Builder
builder()
Create a builder to programmatically construct OIDC configuration.clientId()
Client id of this client.Client secret.Expected timeout of HTTP client operations.Deprecated, for removal: This API element is subject to removal in a future version.usetokenCookieHandler()
insteadDeprecated, for removal: This API element is subject to removal in a future version.please usetokenCookieHandler()
insteadDeprecated, for removal: This API element is subject to removal in a future version.useOidcCookieHandler
instead, this method will no longer be avilablestatic OidcConfig
Create a new instance fromConfig
.Cross-origin resource sharing settings.boolean
Whether to force https when redirecting to identity provider.Deprecated, for removal: This API element is subject to removal in a future version.UsegeneralWebClient()
insteadClient with configured proxy with no security.TokenHandler
to extract header information from request.Identity server URI.Cookie handler to create cookies or unset cookies for id token.Deprecated, for removal: This API element is subject to removal in a future version.Please useappWebClient()
andintrospectUri()
instead; result of moving to reactive webclient from JAX-RS clientIntrospection endpoint URI.issuer()
Token issuer.boolean
Whether logout is enabled.Logout endpoint on OIDC server.Logout URI.int
Maximal number of redirects allowed between Helidon and OIDC provider.name()
Name of the tenant.OIDC metadata.Query parameter name.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 ofWebClient
submit using a POST method.Post logout redirect URI.realm()
Realm to use for WWW-Authenticate response (if needed).Name of the parameter used in state passed to OIDC to store the number of attempted redirects.Redirection URI.Redirect URI with host information.redirectUriWithHost
(String frontendUri) Redirect URI with host information taken from request, unless an explicit frontend uri is defined in configuration.boolean
Determines whether to force the use of relative URIs in all requests, regardless of the presence or absence of proxies or no-proxy lists.Audience URI of custom scopes.Server type.boolean
Whether to redirect to identity server if user is not authenticated.signJwk()
JWK used for signature validation.tenantConfig
(String tenantId) ReturnTenantConfig
bound to the provided tenant id.Cookie handler to create cookies or unset cookies for tenant name.Introspection endpoint URI.Return provided token issuer.Logout endpoint on OIDC server.Tenant query parameter name.JWK used for signature validation.Token endpoint URI.Cookie handler to create cookies or unset cookies for token.Deprecated, for removal: This API element is subject to removal in a future version.Please useappWebClient()
andtokenEndpointUri()
instead; result of moving to reactive webclient from JAX-RS clientType of authentication mechanism used for token endpoint.Token endpoint URI.Amount of time access token should be refreshed before its expiration time.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 replacementboolean
Whether to use cooke to get the information from request.boolean
Whether to use HTTP header to get the information from request.boolean
useParam()
Whether to use query parameter to get the information from request.boolean
Whether to use OIDC well known metadata.boolean
Whether to validate JWT with JWK information (e.g.
-
Field Details
-
PARAM_HEADER_NAME
Default name of the header we expect JWT in.- See Also:
-
DEFAULT_TENANT_PARAM_NAME
Default tenant query param name.- See Also:
-
-
Method Details
-
builder
Create a builder to programmatically construct OIDC configuration.- Returns:
- a new builder instance usable for fluent API
-
create
Create a new instance fromConfig
. 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 ofWebClient
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 buildertoSubmit
- object to submit (such asFormParams
jsonProcessor
- processor of successful JSON responseerrorEntityProcessor
- processor of an error that has an entity, to fail the singleerrorProcessor
- 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:
-
paramName
Query parameter name.- Returns:
- name of the query parameter to use
- See Also:
-
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
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
Cookie handler to create cookies or unset cookies for token.- Returns:
- a new cookie handler
-
idTokenCookieHandler
Cookie handler to create cookies or unset cookies for id token.- Returns:
- a new cookie handler
-
tenantCookieHandler
Cookie handler to create cookies or unset cookies for tenant name.- Returns:
- a new cookie handler
-
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
Logout URI.- Returns:
- uri that processes logout in Helidon and redirects to OIDC server logout
- See Also:
-
postLogoutUri
Post logout redirect URI.- Returns:
- uri that OIDC server redirects to once logout is finished
- See Also:
-
redirectUriWithHost
Redirect URI with host information.- Returns:
- redirect URI
- See Also:
-
redirectUriWithHost
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
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
Cross-origin resource sharing settings.- Returns:
- CORS settings
-
tokenRefreshSkew
Amount of time access token should be refreshed before its expiration time.- Returns:
- refresh time skew
-
cookieName
Deprecated, for removal: This API element is subject to removal in a future version.usetokenCookieHandler()
insteadCookie name.- Returns:
- name of the cookie to use
- See Also:
-
cookieOptions
Deprecated, for removal: This API element is subject to removal in a future version.please usetokenCookieHandler()
insteadAdditional options of the cookie to use.- Returns:
- cookie options to use in cookie string
- See Also:
-
cookieValuePrefix
Deprecated, for removal: This API element is subject to removal in a future version.useOidcCookieHandler
instead, this method will no longer be avilablePrefix of a cookie header formed by name and "=".- Returns:
- prefix of cookie value
- See Also:
-
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, for removal: This API element is subject to removal in a future version.UsegeneralWebClient()
insteadClient with configured proxy with no security.- Returns:
- client for general use.
-
generalWebClient
Client with configured proxy with no security.- Returns:
- client for general use.
-
appClient
Deprecated, for removal: This API element is subject to removal in a future version.UseappWebClient()
Client with configured proxy and security of this OIDC client.- Returns:
- client for communication with OIDC server
-
appWebClient
Client with configured proxy and security.- Returns:
- client for communicating with OIDC identity server
-
tokenEndpoint
Deprecated, for removal: This API element is subject to removal in a future version.Please useappWebClient()
andtokenEndpointUri()
instead; result of moving to reactive webclient from JAX-RS clientToken endpoint of the OIDC server.- Returns:
- target the endpoint is on
- See Also:
-
BaseBuilder.tokenEndpointUri(URI)
-
introspectEndpoint
Deprecated, for removal: This API element is subject to removal in a future version.Please useappWebClient()
andintrospectUri()
instead; result of moving to reactive webclient from JAX-RS clientToken introspection endpoint.- Returns:
- introspection endpoint
- See Also:
-
BaseBuilder.introspectEndpointUri(URI)
-
tenantConfig
ReturnTenantConfig
bound to the provided tenant id. If noTenantConfig
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
Token endpoint URI.- Returns:
- endpoint URI
-
authorizationEndpointUri
Authorization endpoint.- Returns:
- authorization endpoint uri as a string
-
logoutEndpointUri
Logout endpoint on OIDC server.- Returns:
- URI of the logout endpoint
- See Also:
-
BaseBuilder.logoutEndpointUri(java.net.URI)
-
issuer
Token issuer.- Returns:
- token issuer
- See Also:
-
BaseBuilder.issuer(String)
-
signJwk
JWK used for signature validation.- Returns:
- set of keys used use to verify tokens
-
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 replacementUpdate request that uses form params with authentication.- Parameters:
type
- type of the requestrequest
- request builderform
- form params builder
-
tenantSignJwk
Description copied from interface:TenantConfig
JWK used for signature validation. Empty if no jwk has been provided via configuration.- Specified by:
tenantSignJwk
in interfaceTenantConfig
- Returns:
- set of keys used to verify tokens
-
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 interfaceTenantConfig
- Returns:
- URI of the logout endpoint
-
tenantTokenEndpointUri
Description copied from interface:TenantConfig
Token endpoint URI. Empty if no token endpoint uri has been provided via configuration.- Specified by:
tenantTokenEndpointUri
in interfaceTenantConfig
- Returns:
- endpoint URI
-
clientId
Description copied from interface:TenantConfig
Client id of this client.- Specified by:
clientId
in interfaceTenantConfig
- Returns:
- client id
-
name
Description copied from interface:TenantConfig
Name of the tenant.- Specified by:
name
in interfaceTenantConfig
- Returns:
- tenant name
-
baseScopes
Description copied from interface:TenantConfig
Base scopes to require from OIDC server.- Specified by:
baseScopes
in interfaceTenantConfig
- 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 interfaceTenantConfig
- Returns:
- if we should validate JWT with JWK
-
tenantIntrospectUri
Description copied from interface:TenantConfig
Introspection endpoint URI. Empty if no introspection endpoint has been provided via configuration.- Specified by:
tenantIntrospectUri
in interfaceTenantConfig
- Returns:
- introspection endpoint URI
-
tenantIssuer
Description copied from interface:TenantConfig
Return provided token issuer. Empty if no issuer has been provided via configuration.- Specified by:
tenantIssuer
in interfaceTenantConfig
- Returns:
- token issuer
-
audience
Description copied from interface:TenantConfig
Expected token audience.- Specified by:
audience
in interfaceTenantConfig
- Returns:
- audience
-
scopeAudience
Description copied from interface:TenantConfig
Audience URI of custom scopes.- Specified by:
scopeAudience
in interfaceTenantConfig
- Returns:
- scope audience
-
identityUri
Description copied from interface:TenantConfig
Identity server URI.- Specified by:
identityUri
in interfaceTenantConfig
- Returns:
- identity server URI
-
realm
Description copied from interface:TenantConfig
Realm to use for WWW-Authenticate response (if needed).- Specified by:
realm
in interfaceTenantConfig
- Returns:
- realm name
-
tokenEndpointAuthentication
Description copied from interface:TenantConfig
Type of authentication mechanism used for token endpoint.- Specified by:
tokenEndpointAuthentication
in interfaceTenantConfig
- Returns:
- client authentication type
-
clientTimeout
Description copied from interface:TenantConfig
Expected timeout of HTTP client operations.- Specified by:
clientTimeout
in interfaceTenantConfig
- Returns:
- client timeout
-
authorizationEndpoint
Description copied from interface:TenantConfig
Authorization endpoint.- Specified by:
authorizationEndpoint
in interfaceTenantConfig
- Returns:
- authorization endpoint uri as a string
-
clientSecret
Description copied from interface:TenantConfig
Client secret.- Specified by:
clientSecret
in interfaceTenantConfig
- Returns:
- configured client secret
-
serverType
Description copied from interface:TenantConfig
Server type.- Specified by:
serverType
in interfaceTenantConfig
- Returns:
- configured server type
-
oidcMetadata
Description copied from interface:TenantConfig
OIDC metadata.- Specified by:
oidcMetadata
in interfaceTenantConfig
- Returns:
- configured oidc metadata
-
useWellKnown
public boolean useWellKnown()Description copied from interface:TenantConfig
Whether to use OIDC well known metadata.- Specified by:
useWellKnown
in interfaceTenantConfig
- Returns:
- configured oidc metadata
-
appWebClient()