The English version of is the official project site. Translated sites are community supported on a best-effort basis.

Built-In Authentication Support

The following section describes the Quarkus built-in authentication mechanisms for HTTP based FORM, BASIC, and Mutual TLS authentication. Proactive authentication is also described.

Basic Authentication

HTTP Basic Authentication is one of the least resource-demanding techniques that enforce access controls to the Web resources. It uses fields in the HTTP header and does not require HTTP cookies, session identifiers, or login pages.

An HTTP user agent, such as a web browser, uses an Authorization header to provide a user name and password in each HTTP request. The header is specified as Authorization: Basic <credentials>, where credentials are the Base64 encoding of the user ID and password joined by a colon, as shown in the following example.


If the user name is Alice and the password is secret, the HTTP authorization header would be Authorization: Basic QWxjZTpzZWNyZXQ=, where QWxjZTpzZWNyZXQ= is a Base64 encoded representation of the Alice:secret string.

The Basic Authentication mechanism does not provide confidentiality protection for the transmitted credentials. The credentials are merely encoded with Base64 when in transit and not encrypted or hashed in any way. Therefore, Basic Authentication is used with HTTPS to provide confidentiality.

Basic Authentication is a well-specified, simple challenge and response scheme that all web browsers and most web servers understand. However, there are a few limitations associated with Basic Authentication, which include:

Credentials are sent as plain text

Use HTTPS with Basic Authentication to avoid exposing the credentials. The risk of exposing credentials as plain text increases if a load balancer terminates HTTPS, as the request is forwarded to Quarkus over HTTP.

Also, in multi-hop deployments, the credentials can be exposed if HTTPS is used between the client and the first Quarkus endpoint only, and the credentials are propagated to the next Quarkus endpoint over HTTP.

Credentials are sent with each request

In Basic Authentication, a username and password need to be sent with each request, which increases the risk of credentials being exposed.

Application complexity increases

The Quarkus application must validate that usernames, passwords, and roles are managed securely. This process, however, can introduce significant complexity to the application. Depending on the use case, other authentication mechanisms that delegate username, password, and role management to specialized services might be a better choice.

Form Based Authentication

Quarkus provides form based authentication that works in a similar manner to traditional Servlet form based auth. Unlike traditional form authentication, the authenticated user is not stored in an HTTP session, as Quarkus does not provide clustered HTTP session support. Instead, the authentication information is stored in an encrypted cookie, which can be read by all members of the cluster (provided they all share the same encryption key).

La clave de encriptación puede establecerse utilizando la propiedad quarkus.http.auth.session.encryption-key, y debe tener al menos 16 caracteres. Esta clave se convierte en hash utilizando SHA-256 y el resumen resultante se utiliza como clave para el cifrado AES-256 del valor de la cookie. Esta cookie contiene una hora de caducidad como parte del valor cifrado, por lo que todos los nodos del clúster deben tener sus relojes sincronizados. A intervalos de un minuto se generará una nueva cookie con una hora de caducidad actualizada si la sesión está en uso.

Single Page Application (SPA) typically wants to avoid redirects, this can be done by removing default page paths:

# do not redirect, respond with HTTP 200 OK

# do not redirect, respond with HTTP 401 Unauthorized

The following properties can be used to configure form based auth:

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property



If form authentication is enabled.




The login page. Redirect to login page can be disabled by setting quarkus.http.auth.form.login-page=.




The post location.




The username field name.




The password field name.




The error page. Redirect to error page can be disabled by setting quarkus.http.auth.form.error-page=.




The landing page to redirect to if there is no saved page to redirect back to. Redirect to landing page can be disabled by setting quarkus.http.auth.form.landing-page=.




Option to control the name of the cookie used to redirect the user back to where he wants to get access to.




The inactivity (idle) timeout When inactivity timeout is reached, cookie is not renewed and a new login is enforced.




How old a cookie can get before it will be replaced with a new cookie with an updated timeout, also referred to as "renewal-timeout". Note that smaller values will result in slightly more server load (as new encrypted cookies will be generated more often), however larger values affect the inactivity timeout as the timeout is set when a cookie is generated. For example if this is set to 10 minutes, and the inactivity timeout is 30m, if a users last request is when the cookie is 9m old then the actual timeout will happen 21m after the last request, as the timeout is only refreshed when a new cookie is generated. In other words no timeout is tracked on the server side; the timestamp is encoded and encrypted in the cookie itself, and it is decrypted and parsed with each request.




The cookie that is used to store the persistent session




The cookie path for the session and location cookies.




Set the HttpOnly attribute to prevent access to the cookie via JavaScript.




SameSite attribute for the session and location cookies.


strict, lax, none


About the Duration format

El formato de las duraciones utiliza el formato estándar java.time.Duration. Puede obtener más información al respecto en Duration#parse() javadoc.

También puede proporcionar valores de duración que empiecen por un número. En este caso, si el valor consiste sólo en un número, el conversor trata el valor como segundos. En caso contrario, PT se antepone implícitamente al valor para obtener un formato estándar java.time.Duration.

Mutual TLS Authentication

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

Para utilizar este método de autenticación, primero debe habilitar SSL para su aplicación. Para más detalles, consulte la guía Soporte de conexiones seguras con SSL.

Once your application is accepting secure connections, the next step is to configure a holding all the certificates that your application should trust as well as how your application should ask for certificates when a client (e.g.: browser or another service) tries to access one of its protected resources.

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks            (1)
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret        (2)
quarkus.http.ssl.client-auth=required                                      (3)

quarkus.http.auth.permission.default.paths=/*                              (4)
1 Configures a key store where the server’s private key is located.
2 Configures a trust store from where the trusted certificates are going to be loaded from.
3 Defines that the server should always ask certificates from clients. You can relax this behavior by using REQUEST so that the server should still accept requests without a certificate. Useful when you are also supporting authentication methods other than mTLS.
4 Defines a policy where only authenticated users should have access to resources from your application.

Once the incoming request matches a valid certificate in the truststore, your application should be able to obtain the subject by just injecting a SecurityIdentity as follows:

Obtaining the subject
SecurityIdentity identity;

public String hello() {
    return String.format("Hello, %s", identity.getPrincipal().getName());

You should also be able to get the certificate as follows:

Obtaining the certificate

CertificateCredential credential = identity.getCredential(CertificateCredential.class);
X509Certificate certificate = credential.getCertificate();


The information from the client certificate can be used to enhance Quarkus SecurityIdentity. For example, one can add new roles after checking a client certificate subject name, and so on. Please see the SecurityIdentity Customization section for more information about customizing Quarkus SecurityIdentity.

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).

This means that requests with an invalid credential will always be rejected, even for public pages. You can change this behavior and only authenticate when required by setting quarkus.http.auth.proactive=false.

If you disable proactive authentication then the authentication process will only be run when an identity is requested, either because there are security rules that requires the user to be authenticated, or due to programmatic access to the current identity.

Note that if proactive authentication is in use accessing the SecurityIdentity is a blocking operation. This is because authentication may not have happened yet, and accessing it may require calls to external systems such as databases that may block. For blocking applications this is no problem, however if you have disabled authentication in a reactive application this will fail (as you cannot do blocking operations on the IO thread). To work around this you need to @Inject an instance of, and call the Uni<SecurityIdentity> getDeferredIdentity(); method. You can then subscribe to the resulting Uni and will be notified when authentication is complete and the identity is available.

It’s still possible to access the SecurityIdentity synchronously with public SecurityIdentity getIdentity() in the RESTEasy Reactive from endpoints annotated with @RolesAllowed, @Authenticated, or with respective configuration authorization checks as authentication has already happened. The same is also valid for the Reactive routes if a route response is synchronous.

Standard security annotations on CDI beans are not supported on IO thread if a non-void secured method returns a value synchronously and proactive authentication is disabled, as they need to access the SecurityIdentity. In the example below, we have defined HelloResource and HelloService. It’s easy to see that any GET request to /hello will run on IO thread and throw BlockingOperationNotAllowedException exception. There is more than one way to fix the example:

  • switch to a worker thread (annotate hello endpoint with @Blocking)

  • change sayHello method return type (use reactive or asynchronous data type)

  • arguably the safest way is to move @RolesAllowed annotation to the endpoint, as accessing SecurityIdentity from endpoint methods is never the blocking operation

import javax.inject.Inject;

import io.smallrye.mutiny.Uni;

public class HelloResource {

    HelloService helloService;

    public Uni<String> hello() {
        return Uni.createFrom().item(helloService.sayHello());

import javax.enterprise.context.ApplicationScoped;

public class HelloService {

    public String sayHello() {
        return "Hello";


How to customize authentication exception responses

You can use JAX-RS ExceptionMapper to capture Quarkus Security authentication exceptions such as, for example:


import javax.annotation.Priority;


public class AuthenticationFailedExceptionMapper implements ExceptionMapper<AuthenticationFailedException> {

    UriInfo uriInfo;

    public Response toResponse(AuthenticationFailedException exception) {
        return Response.status(401).header("WWW-Authenticate", "Basic realm=\"Quarkus\"").build();
Some HTTP authentication mechanisms need to handle authentication exceptions themselves in order to create a correct authentication challenge. For example, io.quarkus.oidc.runtime.CodeAuthenticationMechanism which manages OpenId Connect authorization code flow authentication, needs to build a correct redirect URL, cookies, etc. For that reason, using custom exception mappers to customize authentication exceptions thrown by such mechanisms is not recommended. In such cases, a safer way to customize authentication exceptions is to make sure the proactive authentication is not disabled and use Vert.x HTTP route failure handlers, as events come to the handler with the correct response status and headers. To that end, the only thing that needs to be done is to customize the response like this:

import javax.enterprise.context.ApplicationScoped;
import javax.enterprise.event.Observes;

import io.vertx.core.Handler;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.RoutingContext;

public class AuthenticationFailedExceptionHandler {

    public void init(@Observes Router router) {
        router.route().failureHandler(new Handler<RoutingContext>() {
            public void handle(RoutingContext event) {
                if (event.failure() instanceof AuthenticationFailedException) {
                } else {