Introduction to Quarkus Security

Quarkus provides a comprehensive security framework that integrates with standards like JWT, OAuth2, OpenID Connect, and MicroProfile JWT. It offers both traditional and reactive security approaches with minimal configuration.

Key Quarkus Security Features

• Built-in Authentication & Authorization
• JWT & OAuth2/OpenID Connect Support
• Role-Based Access Control (RBAC)
• MicroProfile JWT Integration
• Reactive Security
• Elytron Security
• Custom Security Extensions

Dependencies Setup

Maven Configuration

<properties>
<quarkus.version>3.2.0.Final</quarkus.version>
</properties>
<dependencies>
<!-- Quarkus Security -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-security</artifactId>
</dependency>
<!-- JWT Security -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-oidc</artifactId>
</dependency>
<!-- MicroProfile JWT -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-smallrye-jwt</artifactId>
</dependency>
<!-- Elytron Security -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-elytron-security</artifactId>
</dependency>
<!-- Reactive Routes Security -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-vertx-http</artifactId>
</dependency>
<!-- Database Security -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-security-jpa</artifactId>
</dependency>
<!-- Test Security -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-test-security</artifactId>
<scope>test</scope>
</dependency>
<!-- RESTEasy JSON-B -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-resteasy-jsonb</artifactId>
</dependency>
</dependencies>

Basic Security Configuration

Application Properties

# Application Configuration
quarkus.http.port=8080
# Basic Security
quarkus.security.enabled=true
# JWT Configuration
quarkus.oidc.auth-server-url=https://your-oidc-provider.com
quarkus.oidc.client-id=your-client-id
quarkus.oidc.credentials.secret=your-client-secret
# MP JWT Configuration
mp.jwt.verify.publickey.location=publicKey.pem
mp.jwt.verify.issuer=https://your-issuer.com
# Security Roles
quarkus.http.auth.permission.authenticated.paths=/*
quarkus.http.auth.permission.authenticated.policy=authenticated
# CORS Configuration
quarkus.http.cors=true
quarkus.http.cors.origins=*

JWT-Based Security Implementation

JWT Token Generator

package com.quarkus.security.jwt;
import io.smallrye.jwt.build.Jwt;
import org.eclipse.microprofile.jwt.Claims;
import java.time.Instant;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;
public class JWTGenerator {
public static String generateUserToken(String username, Set<String> roles) {
return Jwt.issuer("https://quarkus-app.com")
.upn(username)
.subject(username)
.groups(roles)
.claim(Claims.birthdate.name(), "2000-01-01")
.expiresAt(Instant.now().plusSeconds(3600))
.sign();
}
public static String generateAdminToken() {
Set<String> roles = new HashSet<>(Arrays.asList("admin", "user"));
return generateUserToken("[email protected]", roles);
}
public static String generateUserToken() {
Set<String> roles = new HashSet<>(Arrays.asList("user"));
return generateUserToken("[email protected]", roles);
}
}

JWT Protected Resource

package com.quarkus.security.resource;
import org.eclipse.microprofile.jwt.Claim;
import org.eclipse.microprofile.jwt.Claims;
import org.eclipse.microprofile.jwt.JsonWebToken;
import javax.annotation.security.RolesAllowed;
import javax.enterprise.context.RequestScoped;
import javax.inject.Inject;
import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.util.Set;
@Path("/secured")
@RequestScoped
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class SecuredResource {
@Inject
JsonWebToken jwt;
@Inject
@Claim(standard = Claims.upn)
String username;
@Inject
@Claim(standard = Claims.groups)
Set<String> groups;
@GET
@Path("/public")
public Response publicEndpoint() {
return Response.ok(
new Message("Public endpoint - no authentication required")
).build();
}
@GET
@Path("/user")
@RolesAllowed("user")
public Response userEndpoint() {
return Response.ok(
new Message("User endpoint - user role required. Current user: " + username)
).build();
}
@GET
@Path("/admin")
@RolesAllowed("admin")
public Response adminEndpoint() {
return Response.ok(
new Message("Admin endpoint - admin role required. Current user: " + username)
).build();
}
@GET
@Path("/profile")
@RolesAllowed({"user", "admin"})
public Response getUserProfile() {
UserProfile profile = new UserProfile(
username,
jwt.getSubject(),
groups,
jwt.getExpirationTime(),
jwt.getIssuer()
);
return Response.ok(profile).build();
}
@POST
@Path("/update")
@RolesAllowed("user")
public Response updateUserData(UpdateRequest request) {
// Business logic here
return Response.ok(new Message("Data updated for user: " + username)).build();
}
// DTO classes
public static class Message {
public String message;
public Message(String message) {
this.message = message;
}
}
public static class UserProfile {
public String username;
public String subject;
public Set<String> roles;
public long expiration;
public String issuer;
public UserProfile(String username, String subject, Set<String> roles, 
long expiration, String issuer) {
this.username = username;
this.subject = subject;
this.roles = roles;
this.expiration = expiration;
this.issuer = issuer;
}
}
public static class UpdateRequest {
public String data;
}
}

Custom Authentication Mechanism

Custom Identity Provider

package com.quarkus.security.identity;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.security.identity.AuthenticationRequestContext;
import io.quarkus.security.identity.IdentityProvider;
import io.quarkus.security.runtime.QuarkusSecurityIdentity;
import io.smallrye.mutiny.Uni;
import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import java.util.Set;
@ApplicationScoped
public class CustomIdentityProvider implements IdentityProvider<CustomAuthenticationRequest> {
@Inject
UserService userService;
@Override
public Class<CustomAuthenticationRequest> getRequestType() {
return CustomAuthenticationRequest.class;
}
@Override
public Uni<SecurityIdentity> authenticate(CustomAuthenticationRequest request, 
AuthenticationRequestContext context) {
return Uni.createFrom().item(() -> {
// Validate API key or custom token
User user = userService.validateToken(request.getToken());
if (user != null) {
return QuarkusSecurityIdentity.builder()
.setPrincipal(user::getUsername)
.addRoles(user.getRoles())
.addAttribute("user-id", user.getId())
.addCredential(request.getToken())
.build();
}
return null; // Authentication failed
});
}
}
// Custom Authentication Request
class CustomAuthenticationRequest implements io.quarkus.security.identity.request.AuthenticationRequest {
private final String token;
public CustomAuthenticationRequest(String token) {
this.token = token;
}
public String getToken() {
return token;
}
}
// User Service
@ApplicationScoped
class UserService {
public User validateToken(String token) {
// Implement token validation logic
if ("valid-api-key".equals(token)) {
return new User("1", "api-user", Set.of("user", "api-client"));
}
return null;
}
}
class User {
private final String id;
private final String username;
private final Set<String> roles;
public User(String id, String username, Set<String> roles) {
this.id = id;
this.username = username;
this.roles = roles;
}
public String getId() { return id; }
public String getUsername() { return username; }
public Set<String> getRoles() { return roles; }
}

Database-Backed Security

JPA Entity for Users

package com.quarkus.security.entity;
import javax.persistence.*;
import java.util.Set;
@Entity
@Table(name = "users")
@NamedQuery(
name = "User.findByUsername",
query = "SELECT u FROM User u WHERE u.username = :username"
)
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(unique = true, nullable = false)
private String username;
@Column(nullable = false)
private String password;
@ElementCollection(fetch = FetchType.EAGER)
@CollectionTable(name = "user_roles", joinColumns = @JoinColumn(name = "user_id"))
@Column(name = "role")
private Set<String> roles;
@Column(nullable = false)
private boolean active = true;
// Constructors
public User() {}
public User(String username, String password, Set<String> roles) {
this.username = username;
this.password = password;
this.roles = roles;
}
// Getters and Setters
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getUsername() { return username; }
public void setUsername(String username) { this.username = username; }
public String getPassword() { return password; }
public void setPassword(String password) { this.password = password; }
public Set<String> getRoles() { return roles; }
public void setRoles(Set<String> roles) { this.roles = roles; }
public boolean isActive() { return active; }
public void setActive(boolean active) { this.active = active; }
}

JPA Identity Provider

package com.quarkus.security.jpa;
import io.quarkus.elytron.security.common.BcryptUtil;
import io.quarkus.hibernate.orm.panache.PanacheEntityBase;
import io.quarkus.hibernate.orm.panache.PanacheRepository;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.security.identity.request.UsernamePasswordAuthenticationRequest;
import io.quarkus.security.runtime.QuarkusSecurityIdentity;
import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import javax.persistence.EntityManager;
import javax.transaction.Transactional;
import java.util.Optional;
@ApplicationScoped
public class UserRepository implements PanacheRepository<User> {
@Inject
EntityManager entityManager;
public Optional<User> findByUsername(String username) {
return find("username", username).firstResultOptional();
}
@Transactional
public User createUser(String username, String password, Set<String> roles) {
User user = new User();
user.setUsername(username);
user.setPassword(BcryptUtil.bcryptHash(password));
user.setRoles(roles);
user.setActive(true);
persist(user);
return user;
}
public SecurityIdentity validateUser(String username, String password) {
Optional<User> userOpt = findByUsername(username);
if (userOpt.isPresent()) {
User user = userOpt.get();
if (user.isActive() && BcryptUtil.matches(password, user.getPassword())) {
return QuarkusSecurityIdentity.builder()
.setPrincipal(() -> user.getUsername())
.addRoles(user.getRoles())
.addAttribute("user-id", user.getId())
.build();
}
}
return null;
}
}

Reactive Security Implementation

Reactive JWT Authentication

package com.quarkus.security.reactive;
import io.quarkus.security.identity.SecurityIdentity;
import io.smallrye.mutiny.Uni;
import org.eclipse.microprofile.jwt.JsonWebToken;
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
@Path("/reactive")
public class ReactiveSecurityResource {
@Inject
SecurityIdentity securityIdentity;
@Inject
JsonWebToken jwt;
@GET
@Path("/user-info")
@Produces(MediaType.APPLICATION_JSON)
public Uni<UserInfo> getUserInfo() {
return Uni.createFrom().item(() -> {
String username = securityIdentity.getPrincipal().getName();
Set<String> roles = securityIdentity.getRoles();
return new UserInfo(username, roles, jwt.getExpirationTime());
});
}
@GET
@Path("/admin-task")
public Uni<String> adminTask() {
return Uni.createFrom().item(() -> {
if (!securityIdentity.hasRole("admin")) {
throw new javax.ws.rs.ForbiddenException("Admin role required");
}
return "Admin task executed successfully";
});
}
public static class UserInfo {
public String username;
public Set<String> roles;
public long tokenExpiry;
public UserInfo(String username, Set<String> roles, long tokenExpiry) {
this.username = username;
this.roles = roles;
this.tokenExpiry = tokenExpiry;
}
}
}

Reactive Route Security

package com.quarkus.security.reactive;
import io.quarkus.vertx.web.Route;
import io.quarkus.vertx.web.RouteBase;
import io.quarkus.vertx.web.RouteFilter;
import io.vertx.core.http.HttpMethod;
import io.vertx.ext.web.RoutingContext;
import io.vertx.ext.web.handler.BodyHandler;
import javax.enterprise.context.ApplicationScoped;
@ApplicationScoped
@RouteBase(path = "/api/v1")
public class ReactiveRoutes {
@Route(path = "/public", methods = HttpMethod.GET)
public void publicRoute(RoutingContext rc) {
rc.response()
.putHeader("Content-Type", "application/json")
.end("{\"message\": \"Public route\"}");
}
@Route(path = "/secure", methods = HttpMethod.GET)
public void secureRoute(RoutingContext rc) {
// This will be secured by Quarkus security
rc.response()
.putHeader("Content-Type", "application/json")
.end("{\"message\": \"Secure route\"}");
}
@RouteFilter
public void addSecurityHeaders(RoutingContext rc) {
rc.response()
.putHeader("X-Security-Policy", "strict-origin-when-cross-origin")
.putHeader("X-Content-Type-Options", "nosniff");
rc.next();
}
}

OAuth2/OpenID Connect Integration

OIDC Configuration

# OIDC Configuration
quarkus.oidc.auth-server-url=https://keycloak.example.com/auth/realms/quarkus
quarkus.oidc.client-id=quarkus-app
quarkus.oidc.credentials.secret=your-secret
quarkus.oidc.application-type=service
quarkus.oidc.authentication.redirect-path=/oidc-success
quarkus.oidc.authentication.restore-path=/oidc-restore
quarkus.oidc.authentication.scopes=openid,profile,email
# Role Mapping
quarkus.oidc.roles.role-claim-path=realm_access.roles
quarkus.http.auth.permission.oidc.paths=/oidc/*
quarkus.http.auth.permission.oidc.policy=authenticated

OIDC Protected Resource

package com.quarkus.security.oidc;
import org.eclipse.microprofile.jwt.Claim;
import org.eclipse.microprofile.jwt.Claims;
import javax.annotation.security.RolesAllowed;
import javax.enterprise.context.RequestScoped;
import javax.inject.Inject;
import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.util.Set;
@Path("/oidc")
@RequestScoped
@Produces(MediaType.APPLICATION_JSON)
public class OIDCResource {
@Inject
@Claim(standard = Claims.email)
String email;
@Inject
@Claim(standard = Claims.preferred_username)
String username;
@Inject
@Claim(standard = Claims.groups)
Set<String> groups;
@GET
@Path("/profile")
@RolesAllowed("user")
public Response getOIDCProfile() {
OIDCProfile profile = new OIDCProfile(
username,
email,
groups
);
return Response.ok(profile).build();
}
@GET
@Path("/admin")
@RolesAllowed("admin")
public Response adminEndpoint() {
return Response.ok(new Message("OIDC Admin access granted for: " + email)).build();
}
public static class OIDCProfile {
public String username;
public String email;
public Set<String> roles;
public OIDCProfile(String username, String email, Set<String> roles) {
this.username = username;
this.email = email;
this.roles = roles;
}
}
public static class Message {
public String message;
public Message(String message) {
this.message = message;
}
}
}

Security Event Handling

Security Event Listeners

package com.quarkus.security.events;
import io.quarkus.security.spi.runtime.SecurityEvent;
import javax.enterprise.context.ApplicationScoped;
import javax.enterprise.event.Observes;
import java.time.LocalDateTime;
@ApplicationScoped
public class SecurityEventListener {
public void onAuthenticationSuccess(@Observes SecurityEvent.AuthenticationSuccess event) {
System.out.printf("[SECURITY] User %s authenticated successfully at %s%n",
event.getSecurityIdentity().getPrincipal().getName(),
LocalDateTime.now());
// Log to audit system, send notifications, etc.
}
public void onAuthenticationFailure(@Observes SecurityEvent.AuthenticationFailed event) {
System.out.printf("[SECURITY] Authentication failed for user %s at %s. Reason: %s%n",
event.getAuthenticationRequest().getClass().getSimpleName(),
LocalDateTime.now(),
event.getThrowable().getMessage());
}
public void onAuthorizationSuccess(@Observes SecurityEvent.AuthorizationSuccess event) {
System.out.printf("[SECURITY] User %s authorized for resource at %s%n",
event.getSecurityIdentity().getPrincipal().getName(),
LocalDateTime.now());
}
public void onAuthorizationFailure(@Observes SecurityEvent.AuthorizationFailure event) {
System.out.printf("[SECURITY] Authorization failed for user %s at %s%n",
event.getSecurityIdentity().getPrincipal().getName(),
LocalDateTime.now());
}
}

Custom Security Constraints

Method-Level Security

package com.quarkus.security.constraints;
import javax.annotation.security.DenyAll;
import javax.annotation.security.PermitAll;
import javax.annotation.security.RolesAllowed;
import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
@Path("/constraints")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class SecurityConstraintsResource {
@GET
@Path("/public")
@PermitAll
public Response publicMethod() {
return Response.ok("Public access allowed").build();
}
@GET
@Path("/user-only")
@RolesAllowed("user")
public Response userOnly() {
return Response.ok("User access allowed").build();
}
@GET
@Path("/admin-only")
@RolesAllowed("admin")
public Response adminOnly() {
return Response.ok("Admin access allowed").build();
}
@GET
@Path("/denied")
@DenyAll
public Response denied() {
return Response.ok("This should never be reached").build();
}
@GET
@Path("/multi-roles")
@RolesAllowed({"admin", "supervisor"})
public Response multiRoles() {
return Response.ok("Admin or supervisor access allowed").build();
}
}

Testing Security

Security Test Configuration

package com.quarkus.security.test;
import io.quarkus.test.junit.QuarkusTest;
import io.quarkus.test.security.TestSecurity;
import io.quarkus.test.security.jwt.Claim;
import io.quarkus.test.security.jwt.JwtSecurity;
import io.restassured.RestAssured;
import org.junit.jupiter.api.Test;
import static org.hamcrest.Matchers.*;
@QuarkusTest
public class SecurityTest {
@Test
@TestSecurity(user = "testuser", roles = "user")
public void testUserAccess() {
RestAssured.given()
.when().get("/secured/user")
.then()
.statusCode(200)
.body("message", containsString("testuser"));
}
@Test
@TestSecurity(user = "testadmin", roles = "admin")
public void testAdminAccess() {
RestAssured.given()
.when().get("/secured/admin")
.then()
.statusCode(200)
.body("message", containsString("testadmin"));
}
@Test
@TestSecurity(user = "testuser", roles = "user")
public void testUserAccessDeniedToAdminEndpoint() {
RestAssured.given()
.when().get("/secured/admin")
.then()
.statusCode(403);
}
@Test
@JwtSecurity(claims = {
@Claim(key = "upn", value = "jwtuser"),
@Claim(key = "groups", value = "user")
})
public void testJwtSecurity() {
RestAssured.given()
.when().get("/secured/user")
.then()
.statusCode(200)
.body("message", containsString("jwtuser"));
}
@Test
public void testUnauthenticatedAccess() {
RestAssured.given()
.when().get("/secured/user")
.then()
.statusCode(401);
}
}

Advanced Security Configuration

Custom Security Policy

package com.quarkus.security.policy;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.vertx.http.runtime.security.HttpSecurityPolicy;
import javax.enterprise.context.ApplicationScoped;
import java.util.Set;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.CompletableFuture;
@ApplicationScoped
public class IPWhitelistPolicy implements HttpSecurityPolicy {
private final Set<String> allowedIPs = Set.of(
"192.168.1.0/24",
"10.0.0.1",
"127.0.0.1"
);
@Override
public CompletionStage<CheckResult> checkPermission(
io.vertx.ext.web.RoutingContext routingContext, 
SecurityIdentity identity) {
String clientIP = routingContext.request().remoteAddress().host();
if (isIPAllowed(clientIP)) {
return CompletableFuture.completedFuture(CheckResult.PERMIT);
} else {
return CompletableFuture.completedFuture(CheckResult.DENY);
}
}
private boolean isIPAllowed(String ip) {
// Implement IP whitelist logic
return allowedIPs.stream().anyMatch(allowed -> matchesIP(ip, allowed));
}
private boolean matchesIP(String ip, String allowed) {
// Simple IP matching logic
return ip.equals(allowed) || allowed.endsWith("/24") && 
ip.startsWith(allowed.substring(0, allowed.length() - 4));
}
}

Rate Limiting Security

package com.quarkus.security.ratelimit;
import io.quarkus.redis.datasource.RedisDataSource;
import io.quarkus.redis.datasource.value.ValueCommands;
import javax.enterprise.context.ApplicationScoped;
import javax.ws.rs.container.ContainerRequestContext;
import javax.ws.rs.container.ContainerRequestFilter;
import javax.ws.rs.core.Response;
import javax.ws.rs.ext.Provider;
import java.io.IOException;
@Provider
@ApplicationScoped
public class RateLimitFilter implements ContainerRequestFilter {
private final ValueCommands<String, Integer> redisCommands;
private static final int MAX_REQUESTS = 100;
private static final int TIME_WINDOW = 3600; // 1 hour
public RateLimitFilter(RedisDataSource redis) {
this.redisCommands = redis.value(Integer.class);
}
@Override
public void filter(ContainerRequestContext requestContext) throws IOException {
String clientIP = requestContext.getHeaderString("X-Forwarded-For");
if (clientIP == null) {
clientIP = "unknown";
}
String key = "rate_limit:" + clientIP;
Integer currentCount = redisCommands.get(key);
if (currentCount == null) {
redisCommands.setex(key, TIME_WINDOW, 1);
} else if (currentCount >= MAX_REQUESTS) {
requestContext.abortWith(
Response.status(429)
.entity("Rate limit exceeded")
.build()
);
} else {
redisCommands.incr(key);
}
}
}

Production Security Configuration

Production Security Properties

# Production Security Settings
quarkus.security.users.embedded.enabled=false
# HTTPS Configuration
quarkus.http.ssl-port=8443
quarkus.http.ssl.certificate.files=server.crt
quarkus.http.ssl.certificate.key-files=server.key
# Security Headers
quarkus.http.cors=true
quarkus.http.cors.origins=https://yourdomain.com
quarkus.http.header.content-security-policy=default-src 'self'
quarkus.http.header.strict-transport-security=max-age=31536000
# JWT Production Settings
mp.jwt.verify.publickey.location=https://your-issuer.com/.well-known/jwks.json
mp.jwt.verify.issuer=https://your-issuer.com
# OIDC Production Settings
quarkus.oidc.tls.verification=required
quarkus.oidc.token.issuer=https://your-oidc-issuer.com
# Logging Security Events
quarkus.log.category."io.quarkus.security".level=INFO

Security Monitoring and Health Checks

Security Health Check

package com.quarkus.security.health;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Readiness;
import javax.enterprise.context.ApplicationScoped;
@Readiness
@ApplicationScoped
public class SecurityHealthCheck implements HealthCheck {
@Override
public HealthCheckResponse call() {
// Check security components status
boolean oidcAvailable = checkOIDCConnection();
boolean databaseAvailable = checkDatabaseConnection();
if (oidcAvailable && databaseAvailable) {
return HealthCheckResponse.up("security-components");
} else {
return HealthCheckResponse.down("security-components");
}
}
private boolean checkOIDCConnection() {
// Implement OIDC provider connectivity check
return true;
}
private boolean checkDatabaseConnection() {
// Implement database connectivity check
return true;
}
}

Conclusion

This comprehensive Quarkus security implementation provides:

1. JWT-based authentication with MicroProfile JWT
2. OAuth2/OpenID Connect integration
3. Database-backed security with JPA
4. Reactive security for non-blocking operations
5. Custom security providers and policies
6. Comprehensive testing strategies
7. Production-ready configurations

Quarkus security offers a robust, standards-compliant security framework that integrates seamlessly with modern cloud-native applications. The reactive nature of Quarkus ensures that security operations don't block the event loop, maintaining high performance while providing enterprise-grade security features.