OpenID Connect authorization code flow mechanism for protecting web applications

If client_secret_jwt, private_key_jwt, or an Apple post_jwt authentication methods are used, then you can customize the JWT signature algorithm, key identifier, audience, subject and issuer. For example:

The Apple OIDC provider uses a client_secret_post method whereby a secret is a JWT produced with a private_key_jwt authentication method, but with the Apple account-specific issuer and subject claims.

In Quarkus Security, quarkus-oidc supports a non-standard client_secret_post_jwt authentication method, which you can configure as follows:

Some OIDC providers might require that a client is authenticated as part of the mutual TLS authentication process.

The following example shows how you can configure quarkus-oidc to support mTLS:

Some providers, such as the Strava OAuth2 provider, require client credentials be posted as HTTP POST query parameters:

Some OIDC providers require authentication to its introspection endpoint by using Basic authentication and with credentials that are different from the client_id and client_secret. If you have previously configured security authentication to support either the client_secret_basic or client_secret_post client authentication methods as described in the OIDC provider client authentication section, you might need to apply the additional configuration as follows.

If the tokens have to be introspected and the introspection endpoint-specific authentication mechanism is required, you can configure quarkus-oidc as follows:

By default, only the response_type (set to code), scope (set to openid), client_id, redirect_uri, and state properties are passed as HTTP query parameters to the OIDC provider’s authorization endpoint when the user is redirected to it to authenticate.

You can add more properties to it with quarkus.oidc.authentication.extra-params. For example, some OIDC providers might choose to return the authorization code as part of the redirect URI’s fragment, which would break the authentication process. The following example shows how you can work around this issue:

See also the OIDC redirect filters section explaining how a custom OidcRedirectFilter can be used to customize OIDC redirects, including those to the OIDC authorization endpoint.

When the user is redirected to the OIDC authorization endpoint to authenticate and, if necessary, authorize the Quarkus application, this redirect request might fail, for example, when an invalid scope is included in the redirect URI. In such cases, the provider redirects the user back to Quarkus with error and error_description parameters instead of the expected code parameter.

For example, this can happen when an invalid scope or other invalid parameters are included in the redirect to the provider.

In such cases, an HTTP 401 error is returned by default. However, you can request that a custom public error endpoint be called to return a more user-friendly HTML error page. To do this, set the quarkus.oidc.authentication.error-path property, as shown in the following example:

Ensure that the property starts with a forward slash (/) character and the path is relative to the base URI of the current endpoint. For example, if it is set to '/error' and the current request URI is https://localhost:8080/callback?error=invalid_scope, then a final redirect is made to https://localhost:8080/error?error=invalid_scope.

The OIDC code authentication mechanism acquires three tokens during the authorization code flow: ID token, access token, and refresh token.

The ID token is always a JWT token and represents a user authentication with the JWT claims. You can use this to get the issuing OIDC endpoint, the username, and other information called claims. You can access ID token claims by injecting JsonWebToken with an IdToken qualifier:

The OIDC web-app application usually uses the access token to access other endpoints on behalf of the currently logged-in user. You can access the raw access token as follows:

Injection of the JsonWebToken and AccessTokenCredential is supported in both @RequestScoped and @ApplicationScoped contexts.

Quarkus OIDC uses the refresh token to refresh the current ID and access tokens as part of its session management process.

If the ID token does not provide enough information about the currently authenticated user, you can get more information from the UserInfo endpoint. Set the quarkus.oidc.authentication.user-info-required=true property to request a UserInfo JSON object from the OIDC UserInfo endpoint.

A request is sent to the OIDC provider UserInfo endpoint by using the access token returned with the authorization code grant response, and an io.quarkus.oidc.UserInfo (a simple jakarta.json.JsonObject wrapper) object is created. io.quarkus.oidc.UserInfo can be injected or accessed as a SecurityIdentity userinfo attribute.

quarkus.oidc.authentication.user-info-required is automatically enabled if one of these conditions is met:

The current tenant’s discovered OpenID Connect configuration metadata is represented by io.quarkus.oidc.OidcConfigurationMetadata and can be injected or accessed as a SecurityIdentity configuration-metadata attribute.

The default tenant’s OidcConfigurationMetadata is injected if the endpoint is public.

The way the roles are mapped to the SecurityIdentity roles from the verified tokens is identical to how it is done for the Bearer tokens. The only difference is that ID token is used as a source of the roles by default.

However, depending on your OIDC provider, roles might be stored in the access token or the user info.

If the access token contains the roles and this access token is not meant to be propagated to the downstream endpoints, then set quarkus.oidc.roles.source=accesstoken.

If UserInfo is the source of the roles, then set quarkus.oidc.roles.source=userinfo, and if needed, quarkus.oidc.roles.role-claim-path.

Additionally, you can also use a custom SecurityIdentityAugmentor to add the roles. For more information, see SecurityIdentity customization. You can also map SecurityIdentity roles created from token claims to deployment-specific roles with the HTTP Security policy.

The verification process of OIDC authorization code flow tokens follows the Bearer token authentication token verification and introspection logic. For more information, see the Token verification and introspection section of the "Quarkus OpenID Connect (OIDC) Bearer token authentication" guide.

Code flow access tokens are not introspected unless they are expected to be the source of roles. However, they will be used to get UserInfo. There will be one or two remote calls with the code flow access token if the token introspection, UserInfo, or both are required.

For more information about using the default token cache or registering a custom cache implementation, see Token introspection and UserInfo cache.

For information about the claim verification, including the iss (issuer) claim, see the JSON Web Token claim verification section. It applies to ID tokens and also to access tokens in a JWT format, if the web-app application has requested the access token verification.

You can register a custom [Jose4j Validator] to customize the JWT claim verification process. See Jose4j section for more information.

The OIDC adapter uses cookies to keep the session, code flow, and post-logout state. This state is a key element controlling the lifetime of authentication data.

Use the quarkus.oidc.authentication.cookie-path property to ensure that the same cookie is visible when you access protected resources with overlapping or different roots. For example:

By default, quarkus.oidc.authentication.cookie-path is set to / but you can change this to a more specific path if required, for example, /web-app.

To set the cookie path dynamically, configure the quarkus.oidc.authentication.cookie-path-header property. For example, to set the cookie path dynamically by using the value of the X-Forwarded-Prefix HTTP header, configure the property to quarkus.oidc.authentication.cookie-path-header=X-Forwarded-Prefix.

If quarkus.oidc.authentication.cookie-path-header is set but no configured HTTP header is available in the current request, then the quarkus.oidc.authentication.cookie-path will be checked.

If your application is deployed across multiple domains, set the quarkus.oidc.authentication.cookie-domain property so that the session cookie is visible to all protected Quarkus services. For example, if you have Quarkus services deployed on the following two domains, then you must set the quarkus.oidc.authentication.cookie-domain property to company.net:

State cookies are used to support authorization code flow completion. When an authorization code flow is started, Quarkus creates a state cookie and a matching state query parameter, before redirecting the user to the OIDC provider. When the user is redirected back to Quarkus to complete the authorization code flow, Quarkus expects that the request URI must contain the state query parameter and it must match the current state cookie value.

The default state cookie age is 5 mins and you can change it with a quarkus.oidc.authentication.state-cookie-age Duration property.

Quarkus creates a unique state cookie name every time a new authorization code flow is started to support multi-tab authentication. Many concurrent authentication requests on behalf of the same user may cause a lot of state cookies be created. If you do not want to allow your users use multiple browser tabs to authenticate then it is recommended to disable it with quarkus.oidc.authentication.allow-multiple-code-flows=false. It also ensures that the same state cookie name is created for every new user authentication.

OIDC CodeAuthenticationMechanism uses the default io.quarkus.oidc.TokenStateManager interface implementation to keep the ID, access, and refresh tokens returned in the authorization code or refresh grant responses in an encrypted session cookie.

It makes Quarkus OIDC endpoints completely stateless and it is recommended to follow this strategy to achieve the best scalability results.

Refer to the Database TokenStateManager section of this guide for information on storing tokens in the database or other server-side storage solutions. This approach is suitable if you prefer and have compelling reasons to store the token state on the server.

See the Session cookie and custom TokenStateManager section for alternative methods of token storage. This is ideal for those seeking customized solutions for token state management, especially when standard server-side storage does not meet your specific requirements.

You can configure the default TokenStateManager to avoid saving an access token in the session cookie and to only keep ID and refresh tokens or a single ID token only.

An access token is only required if the endpoint needs to do the following actions:

In such cases, use the quarkus.oidc.token-state-manager.strategy property to configure the token state strategy as follows:

If your chosen session cookie strategy combines tokens and generates a large session cookie value that is greater than 4KB, some browsers might not be able to handle such cookie sizes. This can occur when the ID, access, and refresh tokens are JWT tokens and the selected strategy is keep-all-tokens or with ID and refresh tokens when the strategy is id-refresh-token. To work around this issue, you can set quarkus.oidc.token-state-manager.split-tokens=true to create a unique session token for each token. An alternative solution is to have the tokens saved in the database. For more information, see Database TokenStateManager.

The default TokenStateManager encrypts the tokens before storing them in the session cookie. The following example shows how you configure it to split the tokens and encrypt them:

The token encryption secret must be at least 32 characters long. If this key is not configured, then either quarkus.oidc.credentials.secret or quarkus.oidc.credentials.jwt.secret will be hashed to create an encryption key.

Configure the quarkus.oidc.token-state-manager.encryption-secret property if Quarkus authenticates to the OIDC provider by using one of the following authentication methods:

Otherwise, a random key is generated, which can be problematic if the Quarkus application is running in the cloud with multiple pods managing the requests.

You can disable token encryption in the session cookie by setting quarkus.oidc.token-state-manager.encryption-required=false.

If you want to customize the way the tokens are associated with the session cookie, register a custom io.quarkus.oidc.TokenStateManager implementation as an @ApplicationScoped CDI bean.

For example, you might want to keep the tokens in a cache cluster and have only a key stored in a session cookie. Note that this approach might introduce some challenges if you need to make the tokens available across multiple microservices nodes.

Here is a simple example:

For information about the default TokenStateManager storing tokens in an encrypted session cookie, see Session cookie and default TokenStateManager.

For information about the custom Quarkus TokenStateManager implementation storing tokens in a database, see Database TokenStateManager.

If you prefer to follow a stateful token storage strategy, you can use a custom TokenStateManager provided by Quarkus to have your application store tokens in a database, instead of storing them in an encrypted session cookie, which is done by default as described in the Session cookie and default TokenStateManager section.

Para utilizar esta función, añada la siguiente extensión a su proyecto:

This extension will replace the default io.quarkus.oidc.TokenStateManager with a database-based one.

OIDC Database Token State Manager uses a Reactive SQL client under the hood to avoid blocking because the authentication is likely to happen on an IO thread.

Depending on your database, include and configure exactly one Reactive SQL client. The following Reactive SQL clients are supported:

For example, you already have an application that uses the Hibernate ORM extension together with a PostgreSQL JDBC Driver and your datasource is configured like this:

Now, if you decided to use OIDC Database Token State Manager, you must add the following dependencies and set a reactive driver URL:

Now, the tokens are ready to be stored in the database.

By default, a database table used for storing tokens is created for you, however, you can disable this option with the quarkus.oidc.db-token-state-manager.create-database-table-if-not-exists configuration property. Should you want the Hibernate ORM extension to create this table instead, you must just include an Entity, such as the following:

Users can request a logout by sending a request to the Quarkus endpoint logout path set with a quarkus.oidc.logout.path property. For example, if the endpoint address is https://application.com/webapp and the quarkus.oidc.logout.path is set to /logout, then the logout request must be sent to https://application.com/webapp/logout.

This logout request starts an RP-initiated logout. The user will be redirected to the OIDC provider to log out, where they can be asked to confirm the logout is indeed intended.

The user will be returned to the endpoint post-logout page once the logout has been completed and if the quarkus.oidc.logout.post-logout-path property is set. For example, if the endpoint address is https://application.com/webapp and the quarkus.oidc.logout.post-logout-path is set to /signin, then the user will be returned to https://application.com/webapp/signin. Note, this URI must be registered as a valid post_logout_redirect_uri in the OIDC provider.

If the quarkus.oidc.logout.post-logout-path is set, then a q_post_logout cookie will be created and a matching state query parameter will be added to the logout redirect URI and the OIDC provider will return this state once the logout has been completed. It is recommended for the Quarkus web-app applications to check that a state query parameter matches the value of the q_post_logout cookie, which can be done, for example, in a Jakarta REST filter.

Note that a cookie name varies when using OpenID Connect Multi-Tenancy. For example, it will be named q_post_logout_tenant_1 for a tenant with a tenant_1 ID, and so on.

Here is an example of how to configure a Quarkus application to initiate a logout flow:

You might also want to set quarkus.oidc.authentication.cookie-path to a path value common to all the application resources, which is / in this example. For more information, see the Cookies section.

The OIDC provider can force the logout of all applications by using the authentication data. This is known as back-channel logout. In this case, the OIDC will call a specific URL from each application to trigger that logout.

OIDC providers use Back-channel logout to log out the current user from all the applications into which this user is currently logged in, bypassing the user agent.

You can configure Quarkus to support Back-channel logout as follows:

The absolute back-channel logout URL is calculated by adding quarkus.oidc.back-channel-logout.path to the current endpoint URL, for example, http://localhost:8080/back-channel-logout. You will need to configure this URL in the admin console of your OIDC provider.

You will also need to configure a token age property for the logout token verification to succeed if your OIDC provider does not set an expiry claim in the current logout token. For example, set quarkus.oidc.token.age=10S to ensure that no more than 10 seconds elapse since the logout token’s iat (issued at) time.

You can use Front-channel logout to log out the current user directly from the user agent, for example, its browser. It is similar to Back-channel logout but the logout steps are executed by the user agent, such as the browser, and not in the background by the OIDC provider. This option is rarely used.

You can configure Quarkus to support Front-channel logout as follows:

This path will be compared to the current request’s path, and the user will be logged out if these paths match.

User-initiated logout will log the user out of the OIDC provider. If it is used as single sign-on, it might not be what you require. If, for example, your OIDC provider is Google, you will be logged out from Google and its services. Instead, the user might just want to log out of that specific application. Another use case might be when the OIDC provider does not have a logout endpoint.

By using OidcSession, you can support a local logout, which means that only the local session cookie is cleared, as shown in the following example:

io.quarkus.oidc.OidcSession is a wrapper around the current IdToken, which can help to perform a Local logout, retrieve the current session’s tenant identifier, and check when the session will expire. More useful methods will be added to it over time.

By default, logout is based on the expiration time of the ID token issued by the OIDC provider. When the ID token expires, the current user session at the Quarkus endpoint is invalidated, and the user is redirected to the OIDC provider again to authenticate. If the session at the OIDC provider is still active, users are automatically re-authenticated without needing to provide their credentials again.

The current user session can be automatically extended by enabling the quarkus.oidc.token.refresh-expired property. If set to true, when the current ID token expires, a refresh token grant will be used to refresh the ID token as well as access and refresh tokens.

If you work with a Quarkus OIDC web-app application, then the Quarkus OIDC code authentication mechanism manages the user session lifespan.

To use the refresh token, you should carefully configure the session cookie age. The session age should be longer than the ID token lifespan and close to or equal to the refresh token lifespan.

You calculate the session age by adding the lifespan value of the current ID token and the values of the quarkus.oidc.authentication.session-age-extension and quarkus.oidc.token.lifespan-grace properties.

When the current authenticated user returns to the protected Quarkus endpoint and the ID token associated with the session cookie has expired, then, by default, the user is automatically redirected to the OIDC Authorization endpoint to re-authenticate. The OIDC provider might challenge the user again if the session between the user and this OIDC provider is still active, which might happen if the session is configured to last longer than the ID token.

If the quarkus.oidc.token.refresh-expired is set to true, then the expired ID token (and the access token) is refreshed by using the refresh token returned with the initial authorization code grant response. This refresh token might also be recycled (refreshed) itself as part of this process. As a result, the new session cookie is created, and the session is extended.

You can go one step further and proactively refresh ID tokens or access tokens that are about to expire. Set quarkus.oidc.token.refresh-token-time-skew to the value you want to anticipate the refresh. If, during the current user request, it is calculated that the current ID token will expire within this quarkus.oidc.token.refresh-token-time-skew, then it is refreshed, and the new session cookie is created. This property should be set to a value that is less than the ID token lifespan; the closer it is to this lifespan value, the more often the ID token is refreshed.

You can further optimize this process by having a simple JavaScript function ping your Quarkus endpoint periodically to emulate the user activity, which minimizes the time frame during which the user might have to be re-authenticated.

You can have Quarkus OIDC web-app applications access Google Cloud services such as BigQuery on behalf of the currently authenticated users who have enabled OIDC authorization code flow permissions to such services in their Google developer consoles.

You can do so by using Quarkiverse Google Cloud Services. You need only to add the latest tag service dependency as shown in the following example:

Then, configure Google OIDC properties: