Quarkus - Security Architecture and Guides

Quarkus Security provides the architecture, multiple authentication and authorization mechanisms, and other tools for the developers to build a production-quality security for their Quarkus applications.

This document provides a brief overview of Quarkus Security and links to the individual guides.

Architecture

HttpAuthenticationMechanism is the main entry into Quarkus HTTP Security.

Quarkus Security Manager uses HttpAuthenticationMechanism to extract the authentication credentials from the HTTP request and delegates to IdentityProvider to complete the conversion of these credentials to SecurityIdentity.

For example, the credentials may be coming with the HTTP Authorization header, client HTTPS certificates or cookies.

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

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

In some other contexts you may have other parallel representations of the same information (or parts of it) such as SecurityContext for JAX-RS or JsonWebToken for JWT.

Authentication mechanisms

Quarkus supports several sources to load authentication information from.

Basic and Form Authentication Mechanisms

Basic and Form HTTP-based authentication mechanisms are the core authentication mechanisms supported in Quarkus. Please see Basic HTTP Authentication and Form HTTP Authentication for more information.

Mutual TLS Authentication

Quarkus provides Mutual TLS authentication so that you can authenticate users based on their X.509 certificates.

Please see Mutual TLS Authentication for more information.

OpenId Connect, JWT, OAuth2

OpenId Connect

quarkus-oidc extension provides a reactive, interoperable, multi-tenant enabled OpenId Connect adapter which supports Bearer Token and Authorization Code Flow authentication mechanisms.

Bearer Token mechanism extracts the token from HTTP Authorization header. Authorization Code Flow mechanism uses OpenId Connect Authorization Code flow. It redirects the user to IDP to authenticate and completes the authentication process after the user has been redirected back to Quarkus by exchanging the provided code grant for ID, access and refresh tokens.

ID and access JWT tokens are verified with the refreshable JWK key set but both JWT and opaque (binary) tokens can be introspected remotely.

See the Using OpenID Connect to Protect Service Applications guide for more information about Bearer Token authentication mechanism.

See the Using OpenID Connect to Protect Web Application guide for more information about Authorization Code Flow authentication mechanism.

Both quarkus-oidc Bearer and Authorization Code Flow Authentication mechanisms use SmallRye JWT to represent JWT tokens as Microprofile JWT org.eclipse.microprofile.jwt.JsonWebToken.

See Using OpenID Connect Multi-Tenancy for more information about multiple tenants which can support Bearer or Authorization Code Flow authentication mechanism and configured statically or dynamically.

If you would like to have Quarkus OIDC extension enabled at runtime then set quarkus.oidc.tenant-enabled=false at build time and re-enable it at runtime using a system property. See also Disabling Tenant Configurations for more information about managing the individual tenant configurations in the multi-tenant OIDC deployments.

If you use Keycloak and Bearer tokens then also see the Using Keycloak to Centralize Authorization guide.

If you need to configure Keycloak programmatically then consider using Keycloak Admin REST API with the help of the quarkus-keycloak-admin-client extension.

OpenId Connect Client and Filters

quarkus-oidc-client extension provides OidcClient for acquiring and refreshing access tokens from OpenId Connect and OAuth2 providers which support client-credentials, password and refresh_token token grants.

quarkus-oidc-client-filter extension depends on the quarkus-oidc-client extension and provides JAX-RS OidcClientRequestFilter which sets the access token acquired by OidcClient as an HTTP Authorization header’s Bearer scheme value. 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 - the important point is that this Quarkus endpoint does not have to be protected itself with the Quarkus OpenId Connect adapter.

quarkus-oidc-token-propagation extension depends on the quarkus-oidc extension and provides JAX-RS TokenCredentialRequestFilter which sets the OpenId Connect Bearer or Authorization Code Flow access token as an HTTP Authorization header’s Bearer scheme value. This filter can be registered with MP RestClient implementations injected into the current Quarkus endpoint and the Quarkus endpoint must be protected itself with the Quarkus OpenId Connect adapter. This filter can be used to propagate the access token to the downstream services.

See the Using OpenID Connect and OAuth2 Client guide for more information.

SmallRye JWT

quarkus-smallrye-jwt provides Microprofile JWT 1.1.1 implementation and many more options to verify signed and encrypted JWT tokens and represent them as org.eclipse.microprofile.jwt.JsonWebToken.

It provides an alternative to quarkus-oidc Bearer Token Authentication Mechanism. It can currently verify only JWT tokens using the PEM keys or refreshable JWK key set.

Additionally it provides JWT Generation API for creating signed, inner-signed and/or encrypted JWT tokens with ease.

See the Using SmallRye JWT guide for more information.

OAuth2

quarkus-elytron-security-oauth2 provides an alternative to quarkus-oidc Bearer Token Authentication Mechanism. It is based on Elytron and is primarily meant for introspecting the opaque tokens remotely.

See the Using OAuth2 guide for more information.

Choosing between OpenId Connect, SmallRye JWT and OAuth2 extensions

quarkus-oidc extension 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 this OpenId Connect provider.

quarkus-oidc is the only option when the user authentication via Authorization Code flow or supporting multiple tenants is required. It can also request a UserInfo using both Authorization Code Flow and Bearer access tokens.

When the Bearer tokens have to be verified then quarkus-oidc, quarkus-smallrye-jwt and quarkus-elytron-security-oauth2 can be used.

If you have Bearer tokens in a JWT format then all these 3 extensions can be used. Both quarkus-oidc and quarkus-smallrye-jwt support refreshing the JsonWebKey (JWK) set when the OpenId Connect provider rotates the keys, therefore quarkus-oidc or quarkus-smallrye-jwt should be used for verifying JWT tokens if the remote token introspection has to be avoided or not supported by the providers.

quarkus-smallrye-jwt does not support the remote introspection of the opaque tokens or even JWT tokens - it always relies on the locally available keys - possibly fetched from the OpenId Connect provider. So if you need to introspect the JWT tokens remotely then both quarkus-oidc and quarkus-elytron-security-oauth2 will work. Both extensions also support the verification of the opaque/binary tokens via the remote introspection.

quarkus-oidc and quarkus-smallrye-jwt can have both JWT and opaque tokens injected into the endpoint code - the injected JWT tokens may offer a richer information about the user. All extensions can have the tokens injected as Principal.

quarkus-smallrye-jwt supports more key formats than quarkus-oidc. The latter will only use the JWK-formatted keys which are part of a JWK set. The former - can also work with PEM keys.

quarkus-smallrye-jwt can handle locally not only signed but also inner-signed-and-encrypted or only encrypted tokens. In fact quarkus-oidc and quarkus-elytron-security-oauth2 can verify such tokens too but only by treating them as opaque tokens and verifying them via the remote introspection.

quarkus-elytron-security-oauth2 is the best choice if you need a light weight library for the remote introspection of either opaque or JWT tokens.

Note that a choice of using the opaque versus JWT token format is often driven by the architectural considerations. Opaque tokens are usually much shorter than JWT tokens but they require maintaining most of the token associated state in the provider database - the opaque tokens are effectively the 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 and/or encrypting them.

Below is a summary of the options.

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

Bearer JWT verification is required

Local Verification or Introspection

Local Verification

Introspection

Bearer Opaque Token verification is required

Introspection

No

Introspection

Refreshing JsonWebKey set for verifying JWT tokens

Yes

Yes

No

Represent token as Principal

Yes

Yes

Yes

Inject JWT as MP JWT JsonWebToken

Yes

Yes

No

Authorization Code Flow

Yes

No

No

Multi-tenancy

Yes

No

No

UserInfo support

Yes

No

No

Pem Key format support

No

Yes

No

InnerSigned/Encrypted or Encrypted tokens

Introspection

Local Verification

Introspection

LDAP

Please see the Authenticate with LDAP guide for more information about LDAP authentication mechanism.

Identity Providers

IdentityProvider converts the authentication credentials provided by HttpAuthenticationMechanism to SecurityIdentity.

Some extensions such as OIDC, OAuth2, SmallRye JWT, LDAP have the inlined IdentityProvider implementations which are specific to the supported authentication flow. For example, quarkus-oidc uses its own IdentityProvider to convert a token to SecurityIdentity.

If you use Basic or Form HTTP-based authentication then you have to add an IdentityProvider which can convert a user name and password to SecurityIdentity.

See JPA IdentityProvider and JDBC IdentityProvider for more information. You can also use User Properties IdentityProvider for testing.

Combining Authentication Mechanisms

One can combine multiple authentication mechanisms if they get the authentication credentials from the different sources. For example, combining built-in Basic and quarkus-oidc Bearer authentication mechanisms is allowed, but combining quarkus-oidc Bearer and smallrye-jwt authentication mechanisms is not allowed because both will attempt to verify the token extracted from the HTTP Authorization Bearer scheme.

Proactive Authentication

By default, Quarkus does what we call proactive authentication. This means that if an incoming request has a credential then that request will always be authenticated (even if the target page does not require authentication).

See Proactive Authentication for more information.

Authorization

See Security Authorization for more information about Role Based Access Control and other authorization options.

Customization and other useful tips

Quarkus Security is highly customizable. One can register custom HttpAuthenticationMechanisms, IdentityProviders and SecurityidentityAugmentors.

See Security Customization for more information about customizing Quarkus Security and other useful tips about the reactive security, registering the security providers, etc.

Secure connections with SSL

See the Supporting secure connections with SSL guide for more information.

Cross-Origin Resource Sharing

If you plan to make your Quarkus application accessible to another application running on a different domain, you will need to configure CORS (Cross-Origin Resource Sharing). Please read the HTTP CORS documentation for more information.

SameSite cookies

Please see SameSite cookies for information about adding a SameSite cookie property to any of the cookies set by a Quarkus endpoint.

Testing

See Security Testing for more information about testing Quarkus Security.

Secret Engines

Vault

Quarkus provides a very comprehensive HashiCorp Vault support, please see the Quarkus and HashiCorp Vault documentation for more information.

National Vulnerability Database

Most of Quarkus tags have been registered in National Vulnerability Database (NVD) using a Common Platform Enumeration (CPE) name format. All registered Quarkus CPE names can be found using this search query. If a Quarkus tag represented by the given CPE name entry is affected by some CVE then you’ll be able to follow a provided link to that CVE.

We will be asking the NVD CPE team to update the list as well as link Quarkus CPE name entries with the related CVEs on a regular basis. If you work with a plugin like OWASP plugin which is using NVD feeds to detect the vulnerabilities at the application build time and you see a false positive reported then please re-open this issue and provide the details.