By Version

Quarkus Security overview

Quarkus Security is a framework that provides the architecture, multiple authentication and authorization mechanisms, and other tools for you to build secure and production-quality Java applications.

Getting started with Quarkus Security

Before you start building security into your Quarkus applications, review the overview information to learn about the Quarkus Security architecture and the different authentication and authorization mechanisms that Quarkus supports.

To get started with security in Quarkus, we recommend that you first combine the Quarkus built-in Basic HTTP authentication with the JPA identity provider to enable role-based access control (RBAC). Complete the steps in the Secure a Quarkus application with Basic authentication tutorial. After you have successfully secured your Quarkus application with basic HTTP authentication, you can increase the security further by adding more advanced authentication mechanisms, for example, OpenID Connect (OIDC) authentication.

Security architecture

The HttpAuthenticationMechanism interface is the main entry mechanism for securing HTTP applications in Quarkus.

Quarkus Security uses HttpAuthenticationMechanism to extract the authentication credentials from the HTTP request and delegates them to IdentityProvider to convert the credentials to SecurityIdentity. For example, the credentials can come from the Authorization header, client HTTPS certificates, or cookies.

IdentityProvider verifies the authentication credentials and maps them to SecurityIdentity, which has the username, roles, original authentication credentials, and other attributes.

For every authenticated resource, you can inject a SecurityIdentity instance to get the authenticated identity information.

In other contexts, it is possible to have other parallel representations of the same information or parts of it, for example, SecurityContext for JAX-RS or JsonWebToken for JSON Web Tokens (JWT).

Authentication mechanisms

Quarkus supports multiple authentication mechanisms

Basic and Form HTTP authentication

Basic HTTP Authentication and Form HTTP authentication are the core authentication mechanisms supported in Quarkus.

WebAuthn authentication

WebAuthn is an authentication mechanism that replaces passwords. When you write a service for registering new users, or logging them in, instead of asking for a password, you can use WebAuthn, which replaces the password. For more information, see Secure a Quarkus application by using the WebAuthn authentication mechanism.

Mutual TLS (mTLS) authentication

Quarkus provides mutual TLS (mTLS) authentication so that you can authenticate users based on their X.509 certificates. For more information, see mutual TLS authentication.

OpenID Connect authentication

OpenID Connect (OIDC) is an identity layer that works on top of the OAuth 2.0 protocol. OIDC enables client applications to verify the identity of a user based on the authentication performed by the OIDC provider and to retrieve basic information about that user.

The Quarkus quarkus-oidc extension provides a reactive, interoperable, multitenant-enabled OIDC adapter that supports Bearer Token and Authorization Code Flow authentication mechanisms. The Bearer Token mechanism extracts the token from the HTTP Authorization header. The Authorization Code Flow mechanism redirects the user to an OIDC provider to authenticate the identity of the user. After the user is redirected back to Quarkus, the mechanism completes the authentication process by exchanging the provided code that was granted for the ID, access, and refresh tokens.

You can verify ID and access JWT tokens by using the refreshable JSON Web Key (JWK) set or you can introspect them remotely. However, opaque (binary) tokens can only be introspected remotely.

Using the Quarkus OIDC extension, both Bearer Token and Authorization Code Flow mechanisms use SmallRye JWT to represent JWT tokens as MicroProfile JWT org.eclipse.microprofile.jwt.JsonWebToken.

Additional Quarkus resources for OIDC authentication

For more information about OIDC authentication and authorization methods you can use to secure your Quarkus applications, see the following detailed resources:

OIDC topic	Quarkus information resource
Bearer Token authentication mechanism	Using OpenID Connect (OIDC) to protect service applications using Bearer Token authorization
Authorization Code Flow authentication mechanism	OpenID Connect (OIDC) authorization code flow mechanism
Multiple tenants that can support Bearer Token or Authorization Code Flow mechanisms	Using OpenID Connect (OIDC) multi-tenancy
Using Keycloak to centralize authorization	Using OpenID Connect (OIDC) and Keycloak to centralize authorization
Configuring Keycloak programmatically	Using the Keycloak admin client

OIDC topic

Quarkus information resource

Bearer Token authentication mechanism

Using OpenID Connect (OIDC) to protect service applications using Bearer Token authorization

Authorization Code Flow authentication mechanism

OpenID Connect (OIDC) authorization code flow mechanism

Multiple tenants that can support Bearer Token or Authorization Code Flow mechanisms

Using OpenID Connect (OIDC) multi-tenancy

Using Keycloak to centralize authorization

Using OpenID Connect (OIDC) and Keycloak to centralize authorization

Configuring Keycloak programmatically

Using the Keycloak admin client

If you need to enable the Quarkus OIDC extension at runtime, set quarkus.oidc.tenant-enabled=false at build time and then re-enable it at runtime by using a system property. For more information about managing the individual tenant configurations in multitenant OIDC deployments, see the Disabling tenant configurations section in the Using OpenID Connect (OIDC) multi-tenancy guide.

OpenID Connect client and filters

The quarkus-oidc-client extension provides OidcClient for acquiring and refreshing access tokens from OpenID Connect and OAuth2 providers that support the following token grants: * client-credentials * password * refresh_token

The quarkus-oidc-client-filter extension requires the quarkus-oidc-client extension and provides JAX-RS OidcClientRequestFilter, which sets the access token acquired by OidcClient as the Bearer scheme value of the HTTP Authorization header. This filter can be registered with MP RestClient implementations injected into the current Quarkus endpoint, but it is not related to the authentication requirements of this service endpoint. For example, it can be a public endpoint, or it can be protected with mTLS.

In this scenario, you do not need to protect your Quarkus endpoint by using the Quarkus OpenID Connect adapter.

The quarkus-oidc-token-propagation extension requires the quarkus-oidc extension and provides JAX-RS TokenCredentialRequestFilter, which sets the OpenID Connect Bearer or Authorization Code Flow access token as the Bearer scheme value of the HTTP Authorization header. This filter can be registered with MP RestClient implementations injected into the current Quarkus endpoint, which in turn must be protected by using the Quarkus OpenID Connect adapter. This filter can be used to propagate the access token to the downstream services.

For more information, see the OpenID Connect client and token propagation quickstart and OpenID Connect (OIDC) and OAuth2 client and filters reference guides.

SmallRye JWT authentication

The quarkus-smallrye-jwt extension provides a MicroProfile JSON Web Token (JWT) 1.2.1 implementation and multiple options to verify signed and encrypted JWT tokens and represents them as org.eclipse.microprofile.jwt.JsonWebToken.

quarkus-smallrye-jwt is an alternative to the quarkus-oidc Bearer Token authentication mechanism, and verifies only JWT tokens by using either PEM keys or the refreshable JWK key set. quarkus-smallrye-jwt also provides the JWT generation API, which you can use to easily create signed, inner-signed, and encrypted JWT tokens.

For more information, see Using SmallRye JWT role-based access control.

OAuth2 authentication

quarkus-elytron-security-oauth2 provides an alternative to the quarkus-oidc Bearer Token authentication mechanism. quarkus-elytron-security-oauth2 is based on Elytron and is primarily intended for introspecting opaque tokens remotely. For more information, see Using OAuth2.

Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms

Use the following information to help you to decide which authentication mechanism to use to secure your Quarkus applications:

quarkus-oidc requires an OpenID Connect provider such as Keycloak, which can be used to verify the Bearer tokens or authenticate the end users with the Authorization Code flow. In both cases, quarkus-oidc requires a connection to the specified OpenID Connect provider.
If the user authentication requires Authorization Code flow or you need to support multiple tenants, use quarkus-oidc. quarkus-oidc can also request user information by using both Authorization Code Flow and Bearer access tokens.
If your Bearer tokens must be verified, use quarkus-oidc, quarkus-smallrye-jwt, or quarkus-elytron-security-oauth2.
If your Bearer tokens are in a JWT format, you can use either of the three extensions. Both quarkus-oidc and quarkus-smallrye-jwt support refreshing the JsonWebKey (JWK) set when the OpenID Connect provider rotates the keys. Therefore, if remote token introspection must be avoided or is unsupported by the providers, use quarkus-oidc or quarkus-smallrye-jwt for verifying JWT tokens.
If you need to introspect the JWT tokens remotely, you can use either quarkus-oidc or quarkus-elytron-security-oauth2 because they support the verification of the opaque or binary tokens by using remote introspection. quarkus-smallrye-jwt does not support the remote introspection of both opaque or JWT tokens but instead relies on the locally available keys that are usually retrieved from the OpenID Connect provider.
quarkus-oidc and quarkus-smallrye-jwt support the injecting of JWT and opaque tokens into the endpoint code. Injected JWT tokens provide more information about the user. All extensions can have the tokens injected as Principal.
quarkus-smallrye-jwt supports more key formats than quarkus-oidc. quarkus-oidc uses only the JWK-formatted keys that are part of a JWK set, whereas quarkus-smallrye-jwt supports PEM keys.
quarkus-smallrye-jwt handles locally signed, inner-signed-and-encrypted, and encrypted tokens. While quarkus-oidc and quarkus-elytron-security-oauth2 can also verify such tokens but treats them as opaque tokens and verifies them through remote introspection.
If you need a lightweight library for the remote introspection of opaque or JWT tokens, use quarkus-elytron-security-oauth2.

Your decision to choose whether to use opaque or JWT token format will be driven by architectural considerations. Opaque tokens tend to be much shorter than JWT tokens but need most of the token-associated state to be maintained in the provider database. Opaque tokens are effectively database pointers. JWT tokens are significantly longer than the opaque tokens but the providers are effectively delegating storing most of the token-associated state to the client by storing it as the token claims and either signing or encrypting them.

The following table provides a summary of the options for each authentication mechanism:

quarkus-oidc quarkus-smallrye-jwt quarkus-elytron-security-oauth2

	quarkus-oidc	quarkus-smallrye-jwt	quarkus-elytron-security-oauth2
Requires Bearer JWT verification	Local verification or introspection	Local verification	Introspection
Requires Bearer opaque token verification	Introspection	No	Introspection
Refreshing `JsonWebKey` set for verifying JWT tokens	Yes	Yes	No
Represent token as `Principal`	Yes	Yes	Yes
Inject JWT as MP JSON Web Token (JWT)	Yes	Yes	No
Authorization Code Flow	Yes	No	No
Multi-tenancy	Yes	No	No
User info support	Yes	No	No
PEM key format support	No	Yes	No
SecretKey support	No	In JSON Web Key (JWK) format	No
Inner-signed and encrypted or encrypted tokens	Introspection	Local verification	Introspection
Custom token verification	No	With injected JWT parser	No
Accept JWT as a cookie	No	Yes	No

Requires Bearer JWT verification

Local verification or introspection

Local verification

Introspection

Requires Bearer opaque token verification

Introspection

Refreshing JsonWebKey set for verifying JWT tokens

Yes

Represent token as Principal

Yes

Inject JWT as MP JSON Web Token (JWT)

Yes

Authorization Code Flow

Yes

Multi-tenancy

Yes

User info support

Yes

PEM key format support

Yes

SecretKey support

In JSON Web Key (JWK) format

Inner-signed and encrypted or encrypted tokens

Introspection

Local verification

Introspection

Custom token verification

With injected JWT parser

Accept JWT as a cookie

Yes

Identity providers

The JPA IdentityProvider creates a SecurityIdentity instance, which is used during user authentication to verify and authorize access requests making your Quarkus application secure.

IdentityProvider converts the authentication credentials provided by HttpAuthenticationMechanism to a SecurityIdentity instance.

Some extensions, for example, OIDC, OAuth2, and SmallRye JWT have inline IdentityProvider implementations specific to the supported authentication flow. For example, quarkus-oidc uses its own IdentityProvider to convert a token to a SecurityIdentity instance.

If you use Basic or Form HTTP-based authentication then you must add an IdentityProvider instance that can convert a username and password to a SecurityIdentity instance.

For more information about Basic or Form HTTP-based authentication, see the following resources:

Authorization

Quarkus also supports role-based access control (RBAC). For more information about RBAC and other authorization options in Quarkus, see Security authorization.

Quarkus Security customization

Quarkus Security is highly customizable. You can customize the following core security components of Quarkus:

HttpAuthenticationMechanism
IdentityProvider
SecurityidentityAugmentor

For more information about customizing Quarkus Security including reactive security, and how to register a security provider, see Security customization.

Combining authentication mechanisms

If the user credentials are provided by different sources, you can combine authentication mechanisms. For example, you can combine built-in Basic and quarkus-oidc Bearer authentication mechanisms.

You cannot combine the quarkus-oidc Bearer and smallrye-jwt authentication mechanisms because both mechanisms attempt to verify the token extracted from the HTTP Authorization Bearer scheme.

Path-specific authentication mechanisms

The following configuration example demonstrates how you can enforce a single selectable authentication mechanism for a given request path:

quarkus.http.auth.permission.basic-or-bearer.paths=/service
quarkus.http.auth.permission.basic-or-bearer.policy=authenticated

quarkus.http.auth.permission.basic.paths=/basic-only
quarkus.http.auth.permission.basic.policy=authenticated
quarkus.http.auth.permission.basic.auth-mechanism=basic

quarkus.http.auth.permission.bearer.paths=/bearer-only
quarkus.http.auth.permission.bearer.policy=authenticated
quarkus.http.auth.permission.bearer.auth-mechanism=bearer

Ensure that the value of the auth-mechanism property matches the authentication scheme supported by HttpAuthenticationMechanism, for example, basic, bearer, or form.

Proactive authentication

By default, Quarkus does proactive authentication, which means that all incoming requests with credentials are authenticated regardless of whether the target page requires authentication. For more information, see Proactive authentication.

Secure connections with SSL/TLS

For more information about how Quarkus supports secure connections with SSL/TLS, see the HTTP reference information.

To make your Quarkus application accessible to another application running on a different domain, you need to configure cross-origin resource sharing (CORS). For more information about the CORS filter that is provided by Quarkus, see the HTTP reference information.

Cross-site Request Forgery (CSRF) prevention

Quarkus Security provides a RESTEasy Reactive filter that can protect your applications against a Cross-Site Request Forgery attack. For more information, see Cross-Site Request Forgery Prevention.

SameSite cookies

You can add a SameSite cookie property to any of the cookies set by a Quarkus endpoint. For more information, see SameSite cookies.

Secret engines

Secrets engines are components that store, generate, or encrypt data.

Quarkus provides comprehensive HashiCorp Vault support. For more information, see the Quarkus and HashiCorp Vault documentation.

Secure serialization

If your Quarkus Security architecture includes RESTEasy Reactive and Jackson, Quarkus can limit the fields that are included in JSON serialization based on the configured security. For more information, see Writing REST services with RESTEasy Reactive.

Secure auto-generated resources by REST Data with Panache

If you’re using the REST Data with Panache extension to auto-generate your resources, you can still use the Security annotations within the package javax.annotation.security. For more information, see Securing auto-generated resources.

National Vulnerability Database

Most of the Quarkus tags are registered in the US National Vulnerability Database (NVD) in Common Platform Enumeration (CPE) name format. To view the registered Quarkus CPE names, use this search query.

If the NVE database flags a CVE against a Quarkus tag, a link that provides more details about the CVE is added to the given CPE name entry.

The NVD CPE team updates the list regularly, but if you encounter a false positive, report the details by creating an issue in the quarkusio repository.

You can detect the vulnerabilities at the application build time with an NVD feed by using the Maven OWASP Dependency check plugin.

To add the OWASP Dependency check plugin to your Quarkus Maven project, add the following XML configuration to the pom.xml file:

<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>${owasp-dependency-check-plugin.version}</version>
</plugin>

Set the owasp-dependency-check-plugin.version value to 7.4.4 or later.

Next, configure the plugin as follows:

<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>${owasp-dependency-check-plugin.version}</version>
    <configuration>
        <!-- Fail only when detecting High Vulnerability issues -->
        <failBuildOnCVSS>7</failBuildOnCVSS>
        <suppressionFiles>
            <suppressionFile>${project.basedir}/dependency-cpe-suppression.xml</suppressionFile>
        </suppressionFiles>
    </configuration>
</plugin>

To detect less severe issues, adjust the value of failBuildOnCVSS to suppress the false positives, as demonstrated in the following code sample:

<?xml version="1.0" encoding="UTF-8"?>
<suppressions xmlns="https://jeremylong.github.io/DependencyCheck/dependency-suppression.1.2.xsd">
    <!--
        This is a CPE suppression file for the maven dependency check plugin.
        Each CPE that is found by error (false positive) needs to be suppressed for a specific jar using its' GAV.
        See https://jeremylong.github.io/DependencyCheck/general/suppression.html
     -->
    <suppress>
        <notes>
            <![CDATA[
                Suppress the false positive CPE for netty-tcnative-classes to netty
            ]]>
        </notes>
        <gav regex="true">^io\.netty:netty-tcnative-classes.*:.*$</gav>
        <cpe>cpe:/a:netty:netty</cpe>
    </suppress>
    <suppress>
        <notes>
            <![CDATA[
                Suppress the false positive CPE for Quarkus Mutiny to mutiny:mutiny
            ]]>
        </notes>
        <gav regex="true">^io\.quarkus:quarkus-mutiny.*:.*$</gav>
        <cpe>cpe:/a:mutiny:mutiny</cpe>
    </suppress>
    <suppress>
        <notes>
            <![CDATA[
                Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
            ]]>
        </notes>
        <gav regex="true">^io\.smallrye.reactive:mutiny.*:.*$</gav>
        <cpe>cpe:/a:mutiny:mutiny</cpe>
    </suppress>
    <suppress>
        <notes>
            <![CDATA[
                Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
            ]]>
        </notes>
        <gav regex="true">^io\.smallrye.reactive:smallrye-mutiny.*:.*$</gav>
        <cpe>cpe:/a:mutiny:mutiny</cpe>
    </suppress>
    <suppress>
        <notes>
            <![CDATA[
                Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
            ]]>
        </notes>
        <gav regex="true">^io\.smallrye.reactive:vertx-mutiny.*:.*$</gav>
        <cpe>cpe:/a:mutiny:mutiny</cpe>
    </suppress>
    <suppress>
        <notes>
            <![CDATA[
                Suppress the false positive CPE for graal-sdk to GraalVM (the JVM distribution)
            ]]>
        </notes>
        <gav regex="true">^org\.graalvm\.sdk:g like this
    </suppress>
</suppressions>

Ensure that you review and update the suppression list regularly to ensure that the results are up to date. You can optionally apply a time limit to individual suppressions by adding an expiry attribute, as outlined in the following example:

<suppress until="2022-01-01Z">…</suppress> You can adjust the expiry date if you need to.

Quarkus Security testing

When testing Quarkus security, ensure that your IdentityProvider is already set with usernames, passwords, and roles in application.properties. For more information about testing Quarkus Security, see Configuring user information.

Quarkus Security overview

Getting started with Quarkus Security

Security architecture

Authentication mechanisms

Basic and Form HTTP authentication

WebAuthn authentication

Mutual TLS (mTLS) authentication

OpenID Connect authentication

Additional Quarkus resources for OIDC authentication

OpenID Connect client and filters

SmallRye JWT authentication

OAuth2 authentication

Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms

Identity providers

Authorization

Quarkus Security customization

Combining authentication mechanisms

Path-specific authentication mechanisms

Proactive authentication

Secure connections with SSL/TLS

Cross-origin resource sharing

Cross-site Request Forgery (CSRF) prevention

SameSite cookies

Secret engines

Secure serialization

Secure auto-generated resources by REST Data with Panache

National Vulnerability Database

Quarkus Security testing