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.
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
complete the conversion of these credentials to
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
for JAX-RS or
JsonWebToken for JWT.
Quarkus supports several sources to load authentication information from.
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.
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 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.
See Using OpenID Connect Multi-Tenancy for more information about multiple tenants which can support
Authorization Code Flow authentication mechanism and configured statically or dynamically.
If you would like to have Quarkus OIDC extension enabled at runtime then set
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-smallrye-jwt provides Microprofile JWT 1.1.1 implementation and many more options to verify signed and encrypted
JWT tokens and represent them as
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
JWT tokens with ease.
See the Using SmallRye JWT guide for more information.
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.
Please see the Authenticate with LDAP guide for more information about LDAP authentication mechanism.
IdentityProvider converts the authentication credentials provided by
Some extensions such as
LDAP have the inlined
IdentityProvider implementations which are specific to the supported authentication flow.
quarkus-oidc uses its own
IdentityProvider to convert a token to
If you use
Form HTTP-based authentication then you have to add an
IdentityProvider which can convert a user name and password to
One can combine multiple authentication mechanisms if they get the authentication credentials from the different sources.
For example, combining built-in
Bearer authentication mechanisms is allowed, but combining
smallrye-jwt authentication mechanisms is not allowed because both will attempt to verify the token extracted from the HTTP
Authorization Bearer scheme.
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.
See Security Authorization for more information about Role Based Access Control and other authorization options.
Quarkus Security is highly customizable. One can register custom
See Security Customization for more information about customizing Quarkus Security and other useful tips about the reactive security, registering the security providers, etc.
See the Supporting secure connections with SSL guide for more information.
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.
Please see link:vertx#same-site-cookie for information about adding a SameSite cookie property to any of the cookies set by a Quarkus endpoint.
See Security Testing for more information about testing Quarkus Security.
Quarkus provides a very comprehensive HashiCorp Vault support, please see the Quarkus and HashiCorp Vault documentation for more information.