Authentication mechanisms in Quarkus

You can secure your Quarkus application endpoints with the built-in HTTP Basic authentication mechanism. For more information, see the following documentation:

Quarkus provides form-based authentication that works similarly to traditional Servlet form-based auth. Unlike traditional form authentication, the authenticated user is not stored in an HTTP session because Quarkus does not support clustered HTTP sessions. Instead, the authentication information is stored in an encrypted cookie, which can be read by all cluster members who share the same encryption key.

To apply encryption, add the quarkus.http.auth.session.encryption-key property, and ensure the value you set is at least 16 characters long. The encryption key is hashed by using SHA-256. The resulting digest is used as a key for AES-256 encryption of the cookie value. The cookie contains an expiry time as part of the encrypted value, so all nodes in the cluster must have their clocks synchronized. At one-minute intervals, a new cookie gets generated with an updated expiry time if the session is in use.

With single-page applications (SPA), you typically want to avoid redirects by removing default page paths, as shown in the following example:

Now that you have disabled redirects for the SPA, you must login and logout programmatically from your client. Below are example JavaScript methods for logging into the j_security_check endpoint and logging out of the application by destroying the cookie.

To logout of the SPA from the client the cookie must be set to quarkus.http.auth.form.http-only-cookie=false so you can destroy the cookie and possibly redirect back to your main page.

To logout of the SPA from the server the cookie can be set to quarkus.http.auth.form.http-only-cookie=true and use this example code to destroy the cookie.

The following properties can be used to configure form-based authentication:

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

To use this authentication method, you must first enable SSL/TLS for your application. For more information, see the Supporting secure connections with SSL section of the Quarkus "HTTP reference" guide.

After your application accepts secure connections, the next step is to configure the quarkus.http.ssl.certificate.trust-store-file property with the name of that file that holds all the certificates your application trusts. The specified file also includes information about how your application asks for certificates when a client, such as a browser or other service, tries to access one of its protected resources.

When the incoming request matches a valid certificate in the truststore, your application can obtain the subject by injecting a SecurityIdentity as follows:

You can also get the certificate by using the code outlined in the following example:

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 the Secure a Quarkus application by using the WebAuthn authentication mechanism guide.

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 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 authentication mechanism extracts the token from the HTTP Authorization header. The Authorization Code Flow mechanism redirects the user to an OIDC provider to authenticate the user’s identity. 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 JSON Web Token (JWT) tokens by using the refreshable JSON Web Key (JWK) set or introspect them remotely. However, opaque, also known as binary tokens, can only be introspected remotely.

The quarkus-smallrye-jwt extension provides a MicroProfile JSON Web Token (JWT) 2.1 implementation and multiple options to verify signed and encrypted JWT tokens. It 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 Privacy Enhanced Mail (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 the Using JWT RBAC guide.

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

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

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