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.
Getting Started
Please see the Getting Started With Security guide for a quick walkthrough through Quarkus Security where you can learn how to use Basic HTTP Authentication mechanism and JPA Identity Provider
to create SecurityIdentity
and authorize a secure access to the endpoint with Role Based Access Control
.
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.
WebAuthn Authentication Mechanism
WebAuthn is an authentication mechanism designed to replace passwords. In short, every time you write a service for registering new users, or logging them in, instead of asking for a password, you use WebAuthn, which will replace the password.
Please see our dedicated WebAuthn documentation 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
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 authentication that is performed by the OIDC provider and retrieves 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 this user and, after the user is redirected back to Quarkus, the mechanism completes the authentication process by exchanging the provided code grant for ID, access, and refresh tokens.
You can verify ID and access JSON Web Token (JWT) tokens by using the refreshable JSON Web Key (JWK) set. However, both JWT and opaque (binary) tokens can 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 |
For information about the Bearer Token authentication mechanism, see Using OpenID Connect to Protect Service Applications.
For information about the Authorization Code Flow authentication mechanism, see Using OpenID Connect to Protect Web Application.
For information about multiple tenants that can support Bearer Token or Authorization Code Flow mechanisms, see Using OpenID Connect Multi-Tenancy.
For information about using Keycloak to Centralize Authorization, see the Using Keycloak to Centralize Authorization guide.
For information about configuring Keycloak programmatically, see the Keycloak Admin Client guide.
|
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 OpenID Connect and Token Propagation Quickstart and OpenID Connect and OAuth2 Client Reference guides 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 by using 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 by using 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 through the remote introspection.
quarkus-elytron-security-oauth2
is the best choice if you need a lightweight 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 |
SecretKey support |
No |
In JsonWebKey format |
No |
InnerSigned/Encrypted or Encrypted tokens |
Introspection |
Local Verification |
Introspection |
Custom Token Verification |
No |
With Injected JWTParser |
No |
Accept JWT as cookie |
No |
Yes |
No |
Identity Providers
IdentityProvider
converts the authentication credentials provided by HttpAuthenticationMechanism
to SecurityIdentity
.
Some extensions such as OIDC
, OAuth2
, SmallRye JWT
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 username and password to SecurityIdentity
.
-
For more information about
Basic
orForm
HTTP-based authentication, see: -
For a a Basic Authentication configuration walk-through using JPA, see:
-
For testing, use the User Properties IdentityProvider section with the
IdentityProvider
with already set usernames, passwords, and roles inapplication.properties
.
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.
Path Specific Authentication Mechanism
You can enforce that only a single authentication mechanism is selected for a given request path, for example:
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
The value of the auth-mechanism
property must match the authentication scheme supported by HttpAuthenticationMechanism such as basic
or bearer
or form
, etc.
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 HttpAuthenticationMechanism
s, IdentityProvider
s and SecurityidentityAugmentor
s.
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.
Cross-Site Request Forgery Prevention
Quarkus Security provides a RESTEasy Reactive filter which can help protect against a Cross-Site Request Forgery attack. Please read the Cross-Site Request Forgery Prevention guide 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.
Secure serialization
When using Security along with RESTEasy Reactive and Jackson, Quarkus can limit the fields that are included in JSON serialization based on the configured security. See the RESTEasy Reactive documentation for details.
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 the OWASP Dependency Check Plugin which is using NVD feeds to detect the vulnerabilities at the application build time and see a false positive reported then please re-open this issue and provide the details.
You can add OWASP Dependency Check Plugin
to your project’s pom.xml
like this:
<plugin>
<groupId>org.owasp</groupId>
<artifactId>dependency-check-maven</artifactId>
<version>${owasp-dependency-check-plugin.version}</version>
</plugin>
where owasp-dependency-check-plugin.version
should be set to 7.1.1
or later.
You can configure the plugin like this:
<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>
You can change failBuildOnCVSS
value to detect less severe issues as well.
A suppression list may vary depending on whether you’d like to keep checking the false positives to avoid missing something or not. For example, it can look like this:
<?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 it's 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:graal-sdk:.*$</gav>
<cpe>cpe:/a:oracle:graalvm</cpe>
</suppress>
</suppressions>
Such a suppression list has to be carefully prepared and revisited from time to time. You should consider making individual suppressions time limited by adding an until
attribute, for example: <suppress until="2022-01-01Z">…</suppress>
. It will let you doublecheck that only the same known false positives are reported when the suppression period expires, and after reviewing the report you can set a new expiry date.