Package io.quarkus.oidc.runtime

Interface OidcTenantConfig.Authentication

All Known Implementing Classes:
OidcTenantConfig.Authentication
Enclosing interface:
OidcTenantConfig
public static interface OidcTenantConfig.Authentication
Defines the authorization request properties when authenticating users using the Authorization Code Grant Type.

  • Method Details

    • responseMode

      @ConfigDocDefault("query") Optional<OidcTenantConfig.Authentication.ResponseMode> responseMode()
      Authorization code flow response mode.

    • redirectPath

      Optional<String> redirectPath()
      The relative path for calculating a `redirect_uri` query parameter. It has to start from a forward slash and is appended to the request URI's host and port. For example, if the current request URI is `https://localhost:8080/service`, a `redirect_uri` parameter is set to `https://localhost:8080/` if this property is set to `/` and be the same as the request URI if this property has not been configured. Note the original request URI is restored after the user has authenticated if `restorePathAfterRedirect` is set to `true`.

    • restorePathAfterRedirect

      @WithDefault("false") boolean restorePathAfterRedirect()
      If this property is set to `true`, the original request URI which was used before the authentication is restored after the user has been redirected back to the application. Note if `redirectPath` property is not set, the original request URI is restored even if this property is disabled.

    • removeRedirectParameters

      @WithDefault("true") boolean removeRedirectParameters()
      Remove the query parameters such as `code` and `state` set by the OIDC server on the redirect URI after the user has authenticated by redirecting a user to the same URI but without the query parameters.

    • errorPath

      Optional<String> errorPath()
      Relative path to the public endpoint which processes the error response from the OIDC authorization endpoint. If the user authentication has failed, the OIDC provider returns an `error` and an optional `error_description` parameters, instead of the expected authorization `code`. If this property is set, the user is redirected to the endpoint which can return a user-friendly error description page. It has to start from a forward slash and is appended to the request URI's host and port. For example, if it is set as `/error` and the current request URI is `https://localhost:8080/callback?error=invalid_scope`, a redirect is made to `https://localhost:8080/error?error=invalid_scope`. If this property is not set, HTTP 401 status is returned in case of the user authentication failure.

    • sessionExpiredPath

      Optional<String> sessionExpiredPath()
      Relative path to the public endpoint which an authenticated user is redirected to when the session has expired.

      When the OIDC session has expired and the session can not be refreshed, a user is redirected to the OIDC provider to re-authenticate. The user experience may not be ideal in this case as it may not be obvious to the authenticated user why an authentication challenge is returned.

      Set this property if you would like the user whose session has expired be redirected to a public application specific page instead, which can inform that the session has expired and advise the user to re-authenticated by following a link to the secured initial entry page.

    • verifyAccessToken

      @ConfigDocDefault("true when access token is injected as the JsonWebToken bean, false otherwise") @WithDefault("false") boolean verifyAccessToken()
      Both ID and access tokens are fetched from the OIDC provider as part of the authorization code flow.

      ID token is always verified on every user request as the primary token which is used to represent the principal and extract the roles.

      Authorization code flow access token is meant to be propagated to downstream services and is not verified by default unless `quarkus.oidc.roles.source` property is set to `accesstoken` which means the authorization decision is based on the roles extracted from the access token.

      Authorization code flow access token verification is also enabled if this token is injected as JsonWebToken. Set this property to `false` if it is not required.

      Bearer access token is always verified.

    • forceRedirectHttpsScheme

      @ConfigDocDefault("false") Optional<Boolean> forceRedirectHttpsScheme()
      Force `https` as the `redirect_uri` parameter scheme when running behind an SSL/TLS terminating reverse proxy. This property, if enabled, also affects the logout `post_logout_redirect_uri` and the local redirect requests.

    • scopes

      Optional<List<String>> scopes()
      List of scopes

    • scopeSeparator

      Optional<String> scopeSeparator()
      The separator which is used when more than one scope is configured. A single space is used by default.

    • nonceRequired

      @WithDefault("false") boolean nonceRequired()
      Require that ID token includes a `nonce` claim which must match `nonce` authentication request query parameter. Enabling this property can help mitigate replay attacks. Do not enable this property if your OpenId Connect provider does not support setting `nonce` in ID token or if you work with OAuth2 provider such as `GitHub` which does not issue ID tokens.

    • addOpenidScope

      @ConfigDocDefault("true") Optional<Boolean> addOpenidScope()
      Add the `openid` scope automatically to the list of scopes. This is required for OpenId Connect providers, but does not work for OAuth2 providers such as Twitter OAuth2, which do not accept this scope and throw errors.

    • extraParams

      @ConfigDocMapKey("parameter-name") Map<String,String> extraParams()
      Additional properties added as query parameters to the authentication redirect URI.

    • forwardParams

      Optional<List<@WithConverter(io.quarkus.runtime.configuration.TrimmedStringConverter.class) String>> forwardParams()
      Request URL query parameters which, if present, are added to the authentication redirect URI.

    • cookieForceSecure

      @WithDefault("false") boolean cookieForceSecure()
      If enabled the state, session, and post logout cookies have their `secure` parameter set to `true` when HTTP is used. It might be necessary when running behind an SSL/TLS terminating reverse proxy. The cookies are always secure if HTTPS is used, even if this property is set to false.

    • cookieSuffix

      Optional<String> cookieSuffix()
      Cookie name suffix. For example, a session cookie name for the default OIDC tenant is `q_session` but can be changed to `q_session_test` if this property is set to `test`.

    • cookiePath

      @WithDefault("/") String cookiePath()
      Cookie path parameter value which, if set, is used to set a path parameter for the session, state and post logout cookies. The `cookie-path-header` property, if set, is checked first.

    • cookiePathHeader

      Optional<String> cookiePathHeader()
      Cookie path header parameter value which, if set, identifies the incoming HTTP header whose value is used to set a path parameter for the session, state and post logout cookies. If the header is missing, the `cookie-path` property is checked.

    • cookieDomain

      Optional<String> cookieDomain()
      Cookie domain parameter value which, if set, is used for the session, state and post logout cookies.

    • cookieSameSite

      @WithDefault("lax") OidcTenantConfig.Authentication.CookieSameSite cookieSameSite()
      SameSite attribute for the session cookie.

    • allowMultipleCodeFlows

      @WithDefault("true") boolean allowMultipleCodeFlows()
      If a state cookie is present, a `state` query parameter must also be present and both the state cookie name suffix and state cookie value must match the value of the `state` query parameter when the redirect path matches the current path. However, if multiple authentications are attempted from the same browser, for example, from the different browser tabs, then the currently available state cookie might represent the authentication flow initiated from another tab and not related to the current request. Disable this property to permit only a single authorization code flow in the same browser.

    • failOnMissingStateParam

      @WithDefault("false") boolean failOnMissingStateParam()
      Fail with the HTTP 401 error if the state cookie is present but no state query parameter is present.

      When either multiple authentications are disabled or the redirect URL matches the original request URL, the stale state cookie might remain in the browser cache from the earlier failed redirect to an OpenId Connect provider and be visible during the current request. For example, if Single-page application (SPA) uses XHR to handle redirects to the provider which does not support CORS for its authorization endpoint, the browser blocks it and the state cookie created by Quarkus remains in the browser cache. Quarkus reports an authentication failure when it detects such an old state cookie but find no matching state query parameter.

      Reporting HTTP 401 error is usually the right thing to do in such cases, it minimizes a risk of the browser redirect loop but also can identify problems in the way SPA or Quarkus application manage redirects. For example, enabling javaScriptAutoRedirect() or having the provider redirect to URL configured with redirectPath() might be needed to avoid such errors.

      However, setting this property to `false` might help if the above options are not suitable. It causes a new authentication redirect to OpenId Connect provider. Doing so might increase the risk of browser redirect loops.

    • failOnUnresolvedKid

      @WithDefault("true") boolean failOnUnresolvedKid()
      Fail with the HTTP 401 error if the ID token signature can not be verified during the re-authentication only due to an unresolved token key identifier (`kid`).

      This property might need to be disabled when multiple tab authentications are allowed, with one of the tabs keeping an expired ID token with its `kid` unresolved due to the verification key set refreshed due to another tab initiating an authorization code flow. In such cases, instead of failing with the HTTP 401 error, redirecting the user to re-authenticate with the HTTP 302 status may provide better user experience.

    • userInfoRequired

      @ConfigDocDefault("true when UserInfo bean is injected, false otherwise") Optional<Boolean> userInfoRequired()
      If this property is set to `true`, an OIDC UserInfo endpoint is called.

      This property is enabled automatically if `quarkus.oidc.roles.source` is set to `userinfo` or `quarkus.oidc.token.verify-access-token-with-user-info` is set to `true` or `quarkus.oidc.authentication.id-token-required` is set to `false`, the current OIDC tenant must support a UserInfo endpoint in these cases.

      It is also enabled automatically if `io.quarkus.oidc.UserInfo` injection point is detected but only if the current OIDC tenant supports a UserInfo endpoint.

    • sessionAgeExtension

      @WithDefault("5M") Duration sessionAgeExtension()
      Session age extension in minutes. The user session age property is set to the value of the ID token life-span by default and the user is redirected to the OIDC provider to re-authenticate once the session has expired. If this property is set to a nonzero value, then the expired ID token can be refreshed before the session has expired. This property is ignored if the `token.refresh-expired` property has not been enabled.

    • stateCookieAge

      @WithDefault("5M") Duration stateCookieAge()
      State cookie age in minutes. State cookie is created every time a new authorization code flow redirect starts and removed when this flow is completed. State cookie name is unique by default, see allowMultipleCodeFlows(). Keep its age to the reasonable minimum value such as 5 minutes or less.

    • javaScriptAutoRedirect

      @WithDefault("true") boolean javaScriptAutoRedirect()
      If this property is set to `true`, a normal 302 redirect response is returned if the request was initiated by a JavaScript API such as XMLHttpRequest or Fetch and the current user needs to be (re)authenticated, which might not be desirable for Single-page applications (SPA) since it automatically following the redirect might not work given that OIDC authorization endpoints typically do not support CORS.

      If this property is set to `false`, a status code of `499` is returned to allow SPA to handle the redirect manually if a request header identifying current request as a JavaScript request is found. `X-Requested-With` request header with its value set to either `JavaScript` or `XMLHttpRequest` is expected by default if this property is enabled. You can register a custom JavaScriptRequestChecker to do a custom JavaScript request check instead.

    • idTokenRequired

      @ConfigDocDefault("true") Optional<Boolean> idTokenRequired()
      Requires that ID token is available when the authorization code flow completes. Disable this property only when you need to use the authorization code flow with OAuth2 providers which do not return ID token - an internal IdToken is generated in such cases.

    • internalIdTokenLifespan

      Optional<Duration> internalIdTokenLifespan()
      Internal ID token lifespan. This property is only checked when an internal IdToken is generated when OAuth2 providers do not return IdToken. If this property is not configured then an access token `expires_in` property in the OAuth2 authorization code flow response is used to set an internal IdToken lifespan.

    • pkceRequired

      @ConfigDocDefault("false") Optional<Boolean> pkceRequired()
      Requires that a Proof Key for Code Exchange (PKCE) is used.

    • pkceSecret

      @Deprecated(forRemoval=true) Optional<String> pkceSecret()
      Deprecated, for removal: This API element is subject to removal in a future version.
      This field is deprecated. Use stateSecret() instead.
      Secret used to encrypt a Proof Key for Code Exchange (PKCE) code verifier in the code flow state. This secret should be at least 32 characters long.

    • stateSecret

      Optional<String> stateSecret()
      Secret used to encrypt Proof Key for Code Exchange (PKCE) code verifier and/or nonce in the code flow state. This secret should be at least 32 characters long.

      If this secret is not set, the client secret configured with either `quarkus.oidc.credentials.secret` or `quarkus.oidc.credentials.client-secret.value` is checked. Finally, `quarkus.oidc.credentials.jwt.secret` which can be used for `client_jwt_secret` authentication is checked. A client secret is not be used as a state encryption secret if it is less than 32 characters long.

      The secret is auto-generated if it remains uninitialized after checking all of these properties.

      Error is reported if the secret length is less than 16 characters.