config.io_helidon_security_providers_oidc_OidcProvider.adoc Maven / Gradle / Ivy
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2023, 2024 Oracle and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
ifndef::rootdir[:rootdir: {docdir}/..]
:description: Configuration of io.helidon.security.providers.oidc.OidcProvider
:keywords: helidon, config, io.helidon.security.providers.oidc.OidcProvider
:basic-table-intro: The table below lists the configuration keys that configure io.helidon.security.providers.oidc.OidcProvider
include::{rootdir}/includes/attributes.adoc[]
= OidcProvider (security.providers.oidc) Configuration
// tag::config[]
Open ID Connect security provider
Type: link:{javadoc-base-url}/io.helidon.security.providers.oidc/io/helidon/security/providers/oidc/OidcProvider.html[io.helidon.security.providers.oidc.OidcProvider]
[source,text]
.Config key
----
oidc
----
This type provides the following service implementations:
- `io.helidon.security.spi.AuthenticationProvider`
- `io.helidon.security.spi.SecurityProvider`
== Configuration options
.Optional configuration options
[cols="3,3a,2,5a"]
|===
|key |type |default value |description
|`audience` |string |{nbsp} |Audience of issued tokens.
|`authorization-endpoint-uri` |URI |{nbsp} |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.
|`base-scopes` |string |`openid` |Configure base scopes.
By default, this is `DEFAULT_BASE_SCOPES`.
If scope has a qualifier, it must be used here.
|`check-audience` |boolean |`false` |Configure audience claim check.
|`client-id` |string |{nbsp} |Client ID as generated by OIDC server.
|`client-secret` |string |{nbsp} |Client secret as generated by OIDC server.
Used to authenticate this application with the server when requesting
JWT based on a code.
|`client-timeout-millis` |Duration |`30000` |Timeout of calls using web client.
|`cookie-domain` |string |{nbsp} |Domain the cookie is valid for.
Not used by default.
|`cookie-encryption-enabled` |boolean |`false` |Whether to encrypt token cookie created by this microservice.
Defaults to `false`.
|`cookie-encryption-enabled-id-token` |boolean |`true` |Whether to encrypt id token cookie created by this microservice.
Defaults to `true`.
|`cookie-encryption-enabled-refresh-token` |boolean |`true` |Whether to encrypt refresh token cookie created by this microservice.
Defaults to `true`.
|`cookie-encryption-enabled-tenant-name` |boolean |`true` |Whether to encrypt tenant name cookie created by this microservice.
Defaults to `true`.
|`cookie-encryption-name` |string |{nbsp} |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).
|`cookie-encryption-password` |char[] |{nbsp} |Master password for encryption/decryption of cookies. This must be configured to the same value on each microservice
using the cookie.
|`cookie-http-only` |boolean |`true` |When using cookie, if set to true, the HttpOnly attribute will be configured.
Defaults to `OidcCookieHandler.Builder#DEFAULT_HTTP_ONLY`.
|`cookie-max-age-seconds` |long |{nbsp} |When using cookie, used to set MaxAge attribute of the cookie, defining how long
the cookie is valid.
Not used by default.
|`cookie-name` |string |`JSESSIONID` |Name of the cookie to use.
Defaults to `DEFAULT_COOKIE_NAME`.
|`cookie-name-id-token` |string |`JSESSIONID_2` |Name of the cookie to use for id token.
Defaults to `DEFAULT_COOKIE_NAME`_2.
This cookie is only used when logout is enabled, as otherwise it is not needed.
Content of this cookie is encrypted.
|`cookie-name-refresh-token` |string |`JSESSIONID_3` |The name of the cookie to use for the refresh token.
Defaults to `DEFAULT_REFRESH_COOKIE_NAME`.
|`cookie-name-tenant` |string |`HELIDON_TENANT` |The name of the cookie to use for the tenant name.
Defaults to `DEFAULT_TENANT_COOKIE_NAME`.
|`cookie-path` |string |`/` |Path the cookie is valid for.
Defaults to "/".
|`cookie-same-site` |SameSite (LAX, STRICT, NONE) |`LAX` |When using cookie, used to set the SameSite cookie value. Can be
"Strict" or "Lax".
|`cookie-secure` |boolean |`false` |When using cookie, if set to true, the Secure attribute will be configured.
Defaults to false.
|`cookie-use` |boolean |`true` |Whether to use cookie to store JWT between requests.
Defaults to `DEFAULT_COOKIE_USE`.
|`cors` |xref:{rootdir}/config/io_helidon_cors_CrossOriginConfig.adoc[CrossOriginConfig] |{nbsp} |Assign cross-origin resource sharing settings.
|`force-https-redirects` |boolean |`false` |Force HTTPS for redirects to identity provider.
Defaults to `false`.
|`frontend-uri` |string |{nbsp} |Full URI of this application that is visible from user browser.
Used to redirect request back from identity server after successful login.
|`header-token` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |{nbsp} |A TokenHandler to
process header containing a JWT.
Default is "Authorization" header with a prefix "bearer ".
|`header-use` |boolean |`true` |Whether to expect JWT in a header field.
|`id-token-signature-validation` |boolean |`true` |Whether id token signature check should be enabled.
Signature check is enabled by default, and it is highly recommended to not change that.
Change this setting only when you really know what you are doing, otherwise it could case security issues.
|`identity-uri` |URI |{nbsp} |URI of the identity server, base used to retrieve OIDC metadata.
|`introspect-endpoint-uri` |URI |{nbsp} |Endpoint to use to validate JWT.
Either use this or set #signJwk(JwkKeys) or #signJwk(Resource).
|`issuer` |string |{nbsp} |Issuer of issued tokens.
|`max-redirects` |int |`5` |Configure maximal number of redirects when redirecting to an OIDC provider within a single authentication
attempt.
Defaults to `DEFAULT_MAX_REDIRECTS`
|`oidc-metadata-well-known` |boolean |`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` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Resource configuration for OIDC Metadata
containing endpoints to various identity services, as well as information about the identity server.
|`optional` |boolean |`false` |Whether authentication is required.
By default, request will fail if the authentication cannot be verified.
If set to true, request will process and this provider will abstain.
|`optional-audience` |boolean |`false` |Allow audience claim to be optional.
|`outbound` |xref:{rootdir}/config/io_helidon_security_providers_common_OutboundTarget.adoc[OutboundTarget[]] |{nbsp} |Add a new target configuration.
|`propagate` |boolean |`false` |Whether to propagate identity.
|`proxy-host` |string |{nbsp} |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.
|`proxy-port` |int |`80` |Proxy port.
Defaults to `DEFAULT_PROXY_PORT`
|`proxy-protocol` |string |`http` |Proxy protocol to use when proxy is used.
Defaults to `DEFAULT_PROXY_PROTOCOL`.
|`query-id-token-param-name` |string |`id_token` |Name of a query parameter that contains the JWT id token when parameter is used.
|`query-param-name` |string |`accessToken` |Name of a query parameter that contains the JWT access token when parameter is used.
|`query-param-tenant-name` |string |`h_tenant` |Name of a query parameter that contains the tenant name when the parameter is used.
Defaults to #DEFAULT_TENANT_PARAM_NAME.
|`query-param-use` |boolean |`false` |Whether to use a query parameter to send JWT token from application to this
server.
|`redirect` |boolean |`false` |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.
|`redirect-attempt-param` |string |`h_ra` |Configure the parameter used to store the number of attempts in redirect.
Defaults to `DEFAULT_ATTEMPT_PARAM`
|`redirect-uri` |string |`/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.
Defaults to `DEFAULT_REDIRECT_URI`
|`relative-uris` |boolean |`false` |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 `DEFAULT_RELATIVE_URIS`.
|`scope-audience` |string |{nbsp} |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.
|`server-type` |string |`@default` |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.
|`sign-jwk.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |A resource pointing to JWK with public keys of signing certificates used
to validate JWT.
|`tenants` |xref:{rootdir}/config/io_helidon_security_providers_oidc_common_TenantConfig.adoc[TenantConfig] |{nbsp} |Configurations of the tenants
|`token-endpoint-auth` |ClientAuthentication (CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, CLIENT_SECRET_JWT, PRIVATE_KEY_JWT, NONE) |`CLIENT_SECRET_BASIC` |Type of authentication to use when invoking the token endpoint.
Current supported options:
- io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication#CLIENT_SECRET_BASIC
- io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication#CLIENT_SECRET_POST
- io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication#NONE
|`token-endpoint-uri` |URI |{nbsp} |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.
|`token-signature-validation` |boolean |`true` |Whether access token signature check should be enabled.
Signature check is enabled by default, and it is highly recommended to not change that.
Change this setting only when you really know what you are doing, otherwise it could case security issues.
|`use-jwt-groups` |boolean |`true` |Claim `groups` from JWT will be used to automatically add
groups to current subject (may be used with jakarta.annotation.security.RolesAllowed annotation).
|`validate-jwt-with-jwk` |boolean |`true` |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.
|===
// end::config[]© 2015 - 2025 Weber Informatics LLC | Privacy Policy