Quarkus - Security Guide

Quarkus security allows you to define security authorization requirements for your code using annotations and/or configuration, and providesseveral ways to load security authentication information using Quarkus extensions.

Authentication sources

Quarkus supports several sources to load authentication information from. You need to import at least one of the following extensionsin order for Quarkus to know how to find the authentication information to check for authorizations:

Please see the linked documents above for details on how to setup the various extensions.

Authenticating via HTTP

Quarkus has two built in authentication mechanisms for HTTP based FORM and BASIC auth. This mechanism is pluggablehowever so extensions can add additional mechanisms (most notably OpenID Connect for Keycloak based auth).

Basic Authentication

To enable basic authentication set quarkus.http.auth.basic=true. You must also have at least one extension installedthat provides a username/password based IdentityProvider, such as Elytron JDBC.

Form Based Authentication

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

The encryption key can be set using the quarkus.http.auth.session.encryption-key property, and it must be at least 16 characterslong. This key is hashed using SHA-256 and the resulting digest is used as a key for AES-256 encryption of the cookievalue. This cookie contains a expiry time as part of the encrypted value, so all nodes in the cluster must have theirclocks synchronised. At one minute intervals a new cookie will be generated with an updated expiry time if the sessionis in use.

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

Configuration property fixed at build time - ️ Configuration property overridable at runtime

Authorization in REST endpoints and CDI beans using annotations

Quarkus comes with built-in security to allow for Role-Based Access Control (RBAC)based on the common security annotations @RolesAllowed, @DenyAll, @PermitAll on REST endpoints and CDI beans.An example of an endpoint that makes use of both JAX-RS and Common Security annotations to describe and secure its endpoints is given in SubjectExposingResource Example. Quarkus also providesthe io.quarkus.security.Authenticated annotation that will permit any authenticated user to access the resource(equivalent to @RolesAllowed("*")).

SubjectExposingResource Example

import java.security.Principal;
import javax.annotation.security.DenyAll;
import javax.annotation.security.PermitAll;
import javax.annotation.security.RolesAllowed;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.SecurityContext;
@Path("subject")
public class SubjectExposingResource {
    @GET
    @Path("secured")
    @RolesAllowed("Tester") (1)
    public String getSubjectSecured(@Context SecurityContext sec) {
        Principal user = sec.getUserPrincipal(); (2)
        String name = user != null ? user.getName() : "anonymous";
        return name;
    }
    @GET
    @Path("unsecured")
    @PermitAll(3)
    public String getSubjectUnsecured(@Context SecurityContext sec) {
        Principal user = sec.getUserPrincipal(); (4)
        String name = user != null ? user.getName() : "anonymous";
        return name;
    }
    @GET
    @Path("denied")
    @DenyAll(5)
    public String getSubjectDenied(@Context SecurityContext sec) {
        Principal user = sec.getUserPrincipal();
        String name = user != null ? user.getName() : "anonymous";
        return name;
    }
}

Authorization of Web Endpoints using configuration

Quarkus has an integrated plugable web security layer. If security is enabled all HTTP requests will have a permissioncheck performed to make sure they are permitted to continue.

The default implementation allows you to define permissions using config in application.properties. An exampleconfig is shown below:

quarkus.http.auth.policy.role-policy1.roles-allowed=user,admin                      (1)
quarkus.http.auth.permission.roles1.paths=/roles-secured/*,/other/*,/api/*          (2)
quarkus.http.auth.permission.roles1.policy=role-policy1
quarkus.http.auth.permission.permit1.paths=/public/*                                (3)
quarkus.http.auth.permission.permit1.policy=permit
quarkus.http.auth.permission.permit1.methods=GET
quarkus.http.auth.permission.deny1.paths=/forbidden                                 (4)
quarkus.http.auth.permission.deny1.policy=deny

Permissions are defined in config using permission sets. These are arbitrarily named permission grouping. Each permissionset must specify a policy that is used to control access. There are three built in policies: deny, permit and authenticated,which permit all, deny all and only allow authenticated users respectively.

It is also possible to define role based policies, as shown in the example. These policies will only allow users with thespecified roles to access the resources.

Matching on paths, methods

Permission sets can also specify paths and methods as a comma separated list. If a path ends with '*' then it is consideredto be a wildcard match and will match all sub paths, otherwise it is an exact match and will only match that specific path:

quarkus.http.auth.permission.permit1.paths=/public/*,/css/*,/js/*,/robots.txt
quarkus.http.auth.permission.permit1.policy=permit
quarkus.http.auth.permission.permit1.methods=GET,HEAD

Matching path but not method

If a request would match one or more permission sets based on the path, but does not match any due to method requirementsthen the request is rejected.

Matching multiple paths: longest wins

Matching is always done on a longest path basis, less specific permission sets are not considered if a more specific onehas been matched:

quarkus.http.auth.permission.permit1.paths=/public/*
quarkus.http.auth.permission.permit1.policy=permit
quarkus.http.auth.permission.permit1.methods=GET,HEAD
quarkus.http.auth.permission.deny1.paths=/public/forbidden-folder/*
quarkus.http.auth.permission.deny1.policy=deny

Matching multiple paths: most specific method wins

If a path is registered with multiple permission sets then any permission sets that specify a HTTP method will takeprecedence and permissions sets without a method will not be considered (assuming of course the method matches). In thisinstance, the permission sets without methods will only come into effect if the request method does not match any of thesets with method permissions.

quarkus.http.auth.permission.permit1.paths=/public/*
quarkus.http.auth.permission.permit1.policy=permit
quarkus.http.auth.permission.permit1.methods=GET,HEAD
quarkus.http.auth.permission.deny1.paths=/public/*
quarkus.http.auth.permission.deny1.policy=deny

Matching multiple paths and methods: both win

If multiple permission sets specify the same path and method (or multiple have no method) then both permissions have toallow access for the request to proceed. Note that for this to happen both have to either have specified the method, orhave no method, method specific matches take precedence as stated above:

quarkus.http.auth.policy.user-policy1.roles-allowed=user
quarkus.http.auth.policy.admin-policy1.roles-allowed=admin
quarkus.http.auth.permission.roles1.paths=/api/*,/restricted/*
quarkus.http.auth.permission.roles1.policy=user-policy1
quarkus.http.auth.permission.roles2.paths=/api/*,/admin/*
quarkus.http.auth.permission.roles2.policy=admin-policy1

Authenticated representation

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 SecurityContextfor JAX-RS or JsonWebToken for JWT.

Configuration

There are two configuration settings that alter the RBAC behavior:

• quarkus.security.jaxrs.deny-unannotated-endpoints=true|false - if set to true, the access will be denied for all JAX-RS endpoints by default.That is if the security annotations do not define the access control. Defaults to false

• quarkus.security.deny-unannotated-members=true|false - if set to true, the access will be denied to all CDI methodsand JAX-RS endpoints that do not have security annotations but are defined in classes that contain methods withsecurity annotations. Defaults to false.

Registering Security Providers

When running in native mode the default behavior for Graal native image generation is to only include the main "SUN" providerunless you have enabled SSL, in which case all security providers are registered. If you are not using SSL, then you can selectivelyregister security providers by name using the quarkus.security.users.security-providers property. The following example illustratesconfiguration to register the "SunRsaSign" and "SunJCE" security providers:

Example Security Providers Configuration

quarkus.security.security-providers=SunRsaSign,SunJCE
...