Skip to content

Latest commit

 

History

History
361 lines (257 loc) · 19.8 KB

security-authentication-mechanisms-concept.adoc

File metadata and controls

361 lines (257 loc) · 19.8 KB
Raw

Authentication mechanisms in Quarkus

The Quarkus Security framework supports multiple authentication mechanisms, which you can use to secure your applications. You can also combine authentication mechanisms.

Tip

Before you choose an authentication mechanism for securing your Quarkus applications, review the information provided.

Overview of supported authentication mechanisms

Some supported authentication mechanisms are built into Quarkus, and some require you to add an extension, all of which are detailed in the following sections on this page:

The following table maps specific authentication requirements to a supported mechanism that you can use in Quarkus:

Table 1. Authentication requirements and mechanisms
Authentication requirement Authentication mechanism

Username and password

Basic, Form

Bearer access token

OIDC Bearer authentication, JWT, OAuth2

Single sign-on (SSO)

OIDC Code Flow, Form

Client certificate

Mutual TLS (MTLS)

WebAuthn

WebAuthn

Kerberos ticket

Kerberos

See also the Token authentication mechanism comparison table featured later in this section.

Built-in authentication mechanisms

Quarkus Security provides the following built-in authentication support:

Basic authentication

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

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

To apply encryption, add the quarkus.http.auth.session.encryption-key property, and ensure that the value you set is at least 16 characters long. This key is hashed 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.

Single-page application (SPA) typically wants to avoid redirects, which can be done by removing default page paths, as outlined in the following example:

# do not redirect, respond with HTTP 200 OK
quarkus.http.auth.form.landing-page=

# do not redirect, respond with HTTP 401 Unauthorized
quarkus.http.auth.form.login-page=
quarkus.http.auth.form.error-page=

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

Mutual TLS 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 should first enable SSL for your application. For more details, check the Supporting secure connections with SSL guide.

Once your application is accepting secure connections, the next step is to configure a quarkus.http.ssl.certificate.trust-store-file 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
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks        (2)
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required                                      (3)

quarkus.http.auth.permission.default.paths=/*                              (4)
quarkus.http.auth.permission.default.policy=authenticated

  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
@Inject
SecurityIdentity identity;

@GET
@Produces(MediaType.TEXT_PLAIN)
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
import java.security.cert.X509Certificate;
import io.quarkus.security.credential.CertificateCredential;

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

Authorization

The information from the client certificate can be used to enhance Quarkus SecurityIdentity. For example, you can add new roles after checking a client certificate subject name, and so on. For more information about customizing Quarkus SecurityIdentity, see SecurityIdentity customization in the "Security customization" topic.

Other supported authentication mechanisms

Quarkus Security also supports the following authentication mechanisms through extensions:

WebAuthn authentication

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

OpenID Connect authentication

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 to 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 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 the user. 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 JWT tokens by using the refreshable JSON Web Key (JWK) set or you can introspect them remotely. However, opaque (binary) tokens can only be introspected remotely.

Note

Using the Quarkus OIDC extension, both Bearer Token and Authorization Code Flow mechanisms use SmallRye JWT to represent JWT tokens as MicroProfile JWT org.eclipse.microprofile.jwt.JsonWebToken.

Additional Quarkus resources for OIDC authentication

For more information about OIDC authentication and authorization methods you can use to secure your Quarkus applications, see the following detailed resources:

OIDC topic Quarkus information resource

Bearer token authentication mechanism

OIDC Bearer authentication

Authorization code flow authentication mechanism

OpenID Connect (OIDC) authorization code flow mechanism

Multiple tenants that can support bearer token or authorization code flow mechanisms

Using OpenID Connect (OIDC) multi-tenancy

Well-Known OpenID Connect Providers

Configuring Well-Known OpenID Connect Providers

Using Keycloak to centralize authorization

Using OpenID Connect (OIDC) and Keycloak to centralize authorization

Configuring Keycloak programmatically

Using the Keycloak admin client
Note

If you need to enable the Quarkus OIDC extension at runtime, set quarkus.oidc.tenant-enabled=false at build time and then re-enable it at runtime by using a system property.

For more information about managing the individual tenant configurations in multitenant OIDC deployments, see the Disabling tenant configurations section in the Using OpenID Connect (OIDC) multi-tenancy guide.

OpenID Connect client and filters

The quarkus-oidc-client extension provides OidcClient for acquiring and refreshing access tokens from OpenID Connect and OAuth2 providers that support the following token grants:

  • client-credentials

  • password

  • refresh_token

The quarkus-oidc-client-filter extension requires the quarkus-oidc-client extension and provides Jakarta REST OidcClientRequestFilter, which sets the access token acquired by OidcClient as the Bearer scheme value of the HTTP Authorization header. 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.

Important

In this scenario, you do not need to protect your Quarkus endpoint by using the Quarkus OpenID Connect adapter.

The quarkus-oidc-token-propagation extension requires the quarkus-oidc extension and provides Jakarta REST TokenCredentialRequestFilter, which sets the OpenID Connect Bearer or Authorization Code Flow access token as the Bearer scheme value of the HTTP Authorization header. This filter can be registered with MP RestClient implementations injected into the current Quarkus endpoint, which in turn must be protected by using the Quarkus OpenID Connect adapter. This filter can be used to propagate the access token to the downstream services.

SmallRye JWT authentication

The quarkus-smallrye-jwt extension provides a MicroProfile JSON Web Token (JWT) 1.2.1 implementation and multiple options to verify signed and encrypted JWT tokens and 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.

OAuth2 authentication

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

Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms

Use the following information to select the appropriate token authentication mechanism to secure your Quarkus applications.

List of authentication mechanism use-cases

  • quarkus-oidc 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 the specified OpenID Connect provider.

  • If the user authentication requires Authorization Code flow or you need to support multiple tenants, use quarkus-oidc. quarkus-oidc can also request user information by using both Authorization Code Flow and Bearer access tokens.

  • If your Bearer tokens must be verified, use quarkus-oidc, quarkus-smallrye-jwt, or quarkus-elytron-security-oauth2.

  • If your Bearer tokens are in a JSON web token (JWT) format, you can use any of the extensions listed above. Both quarkus-oidc and quarkus-smallrye-jwt support refreshing the JsonWebKey (JWK) set when the OpenID Connect provider rotates the keys. Therefore, if remote token introspection must be avoided or is unsupported by the providers, use quarkus-oidc or quarkus-smallrye-jwt for verifying JWT tokens.

  • If you need to introspect the JWT tokens remotely, you can use either quarkus-oidc or quarkus-elytron-security-oauth2 because they support the verification of the opaque or binary tokens by using remote introspection. quarkus-smallrye-jwt does not support the remote introspection of both opaque or JWT tokens but instead relies on the locally available keys that are usually retrieved from the OpenID Connect provider.

  • quarkus-oidc and quarkus-smallrye-jwt support the JWT and opaque tokens injection into the endpoint code. Injected JWT tokens provide more information about the user. All extensions can have the tokens injected as Principal.

  • quarkus-smallrye-jwt supports more key formats than quarkus-oidc. quarkus-oidc uses only the JWK-formatted keys that are part of a JWK set, whereas quarkus-smallrye-jwt supports PEM keys.

  • quarkus-smallrye-jwt handles locally signed, inner-signed-and-encrypted, and encrypted tokens. While quarkus-oidc and quarkus-elytron-security-oauth2 can also verify such tokens but treats them as opaque tokens and verifies them through remote introspection.

  • If you need a lightweight library for the remote introspection of opaque or JWT tokens, use quarkus-elytron-security-oauth2.

Note

Architectural considerations drive your decision to use opaque or JSON web token (JWT) token format. Opaque tokens tend to be much shorter than JWT tokens but need most of the token-associated state to be maintained in the provider database. Opaque tokens are effectively database pointers.

JWT tokens are significantly longer than opaque tokens. Still, the providers effectively delegate most of the token-associated state to the client by storing it as the token claims and either signing or encrypting them.
Table 2. Token authentication mechanism comparison
Feature required Authentication mechanism

quarkus-oidc

quarkus-smallrye-jwt

quarkus-elytron-security-oauth2

Bearer JWT verification

Local verification or introspection

Local verification

Introspection

Bearer opaque token verification

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

Yes

Yes

No

Authorization code flow

Yes

No

No

Multi-tenancy

Yes

No

No

User information support

Yes

No

No

PEM key format support

No

Yes

No

SecretKey support

No

In JSON Web Key (JWK) format

No

Inner-signed and encrypted or encrypted tokens

Introspection

Local verification

Introspection

Custom token verification

No

With injected JWT parser

No

JWT as a cookie support

No

Yes

Yes

Combining authentication mechanisms

If the user credentials are provided by different sources, you can combine authentication mechanisms. For example, you can combine built-in Basic and quarkus-oidc Bearer authentication mechanisms.

Important

You cannot combine the quarkus-oidc Bearer and smallrye-jwt authentication mechanisms because both mechanisms attempt to verify the token extracted from the HTTP Authorization Bearer scheme.

Path-specific authentication mechanisms

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

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

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

Proactive authentication

Proactive authentication is enabled in Quarkus by default. 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. For more information, see Proactive authentication.