第 20 課：整合 Spring Boot 和 Quarkus

HTMLTAG_165__HTMLTAG_166___2.3 安全設定___HTMLTAG_167__HTMLTAG_168

預編碼_3

HTMLTAG_169__HTMLTAG_170___2.4 自訂 JwtAuthenticationConverter___HTMLTAG_171__HTMLTAG_172

Keycloak 根據特殊結構儲存 JWT 聲明中的角色。需要自訂轉換器來提取正確的角色：

預編碼_4

預編碼_5

角色映射的工作原理：

預編碼_6

HTMLTAG_177__HTMLTAG_178___2.5 具有 RBAC 的 REST 控制器___HTMLTAG_179__HTMLTAG_180

預編碼_7

HTMLTAG_181__HTMLTAG_182___2.6 CORS 設定___HTMLTAG_183__HTMLTAG_184

前端（React/Angular）呼叫後端API時，需要設定CORS：

預編碼_8

將 CORS 加入到 SecurityFilterChain:

預編碼_9

HTMLTAG_191__HTMLTAG_192___2.7 處理令牌過期___HTMLTAG_193__HTMLTAG_194

Spring Security 自動驗證 exp 聲明。當令牌過期時，伺服器傳回 HTTP 401:

預編碼_10

已在 SecurityFilterChain 中註冊：

// Trong SecurityConfig
@Autowired
private CustomAuthenticationEntryPoint authEntryPoint;

// Trong securityFilterChain()
.oauth2ResourceServer(oauth2 -> oauth2
    .jwt(jwt -> jwt
        .jwtAuthenticationConverter(jwtAuthenticationConverter())
    )
    .authenticationEntryPoint(authEntryPoint)
)

HTMLTAG_203__HTMLTAG_204___3。 Quarkus + Keycloak 整合___HTMLTAG_205__HTMLTAG_206

HTMLTAG_207__HTMLTAG_208___3.1 Quarkus OIDC 擴充___HTMLTAG_209__HTMLTAG_210

Quarkus 提供了 quarkus-oidc 與 Keycloak 整合的擴充：

<!-- pom.xml -->
<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-oidc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-rest</artifactId>
    </dependency>

    <!-- Optional: Keycloak Authorization Policy Enforcer -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-keycloak-authorization</artifactId>
    </dependency>

    <!-- Test -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-test-keycloak-server</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

HTMLTAG_215__HTMLTAG_216___3.2 應用程式屬性___HTMLTAG_217__HTMLTAG_218

# src/main/resources/application.properties

# ===== OIDC Configuration =====
quarkus.oidc.auth-server-url=http://localhost:8080/realms/my-realm
quarkus.oidc.client-id=my-quarkus-client
quarkus.oidc.credentials.secret=my-client-secret

# Application type: service (Resource Server) hoặc web-app (OIDC login)
quarkus.oidc.application-type=service

# Token verification
quarkus.oidc.token.issuer=http://localhost:8080/realms/my-realm
quarkus.oidc.token.audience=my-quarkus-client

# Role mapping - Keycloak roles source
quarkus.oidc.roles.role-claim-path=realm_access/roles
quarkus.oidc.roles.source=accesstoken

# ===== HTTP Configuration =====
quarkus.http.port=8081
quarkus.http.cors=true
quarkus.http.cors.origins=http://localhost:3000,http://localhost:4200
quarkus.http.cors.methods=GET,POST,PUT,DELETE,OPTIONS
quarkus.http.cors.headers=Authorization,Content-Type

HTMLTAG_219__HTMLTAG_220___3.3 具有 @RolesAllowed 的 REST 資源___HTMLTAG_221__HTMLTAG_222

package com.example.resource;

import io.quarkus.security.Authenticated;
import io.quarkus.security.identity.SecurityIdentity;
import jakarta.annotation.security.PermitAll;
import jakarta.annotation.security.RolesAllowed;
import jakarta.inject.Inject;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

import java.util.Map;
import java.util.Set;

import org.eclipse.microprofile.jwt.JsonWebToken;

@Path("/api")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class DemoResource {

    @Inject
    SecurityIdentity securityIdentity;

    @Inject
    JsonWebToken jwt;

    // ========== Public ==========

    @GET
    @Path("/public/health")
    @PermitAll
    public Response health() {
        return Response.ok(Map.of("status", "UP")).build();
    }

    // ========== Authenticated ==========

    @GET
    @Path("/me")
    @Authenticated
    public Response getCurrentUser() {
        return Response.ok(Map.of(
            "username", jwt.getClaim("preferred_username"),
            "email", jwt.getClaim("email"),
            "roles", securityIdentity.getRoles(),
            "token_id", jwt.getTokenID()
        )).build();
    }

    // ========== Role-based ==========

    @GET
    @Path("/users")
    @RolesAllowed({"USER", "ADMIN"})
    public Response getUsers() {
        return Response.ok(Map.of(
            "message", "User list - USER and ADMIN roles"
        )).build();
    }

    @POST
    @Path("/users")
    @RolesAllowed("ADMIN")
    public Response createUser(Map<String, String> user) {
        return Response.ok(Map.of(
            "message", "User created",
            "username", user.getOrDefault("username", "unknown")
        )).build();
    }

    @GET
    @Path("/admin/dashboard")
    @RolesAllowed("ADMIN")
    public Response adminDashboard() {
        return Response.ok(Map.of(
            "message", "Admin Dashboard - ADMIN only",
            "identity", securityIdentity.getPrincipal().getName()
        )).build();
    }
}

HTMLTAG_223__HTMLTAG_224___3.4 多租用戶 OIDC 設定___HTMLTAG_225__HTMLTAG_226

Quarkus 支援需要連接多個 Keycloak 領域的 SaaS 系統的多租戶 OIDC：

# application.properties - Multi-tenant setup

# Default tenant
quarkus.oidc.auth-server-url=http://localhost:8080/realms/default-realm
quarkus.oidc.client-id=default-client
quarkus.oidc.application-type=service

# Tenant A
quarkus.oidc.tenant-a.auth-server-url=http://localhost:8080/realms/tenant-a
quarkus.oidc.tenant-a.client-id=tenant-a-client
quarkus.oidc.tenant-a.credentials.secret=tenant-a-secret
quarkus.oidc.tenant-a.application-type=service

# Tenant B
quarkus.oidc.tenant-b.auth-server-url=http://localhost:8080/realms/tenant-b
quarkus.oidc.tenant-b.client-id=tenant-b-client
quarkus.oidc.tenant-b.credentials.secret=tenant-b-secret
quarkus.oidc.tenant-b.application-type=service

package com.example.config;

import io.quarkus.oidc.OidcTenantConfig;
import io.quarkus.oidc.TenantResolver;
import io.vertx.ext.web.RoutingContext;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class CustomTenantResolver implements TenantResolver {

    @Override
    public String resolve(RoutingContext context) {
        // Resolve tenant từ request path
        String path = context.request().path();

        if (path.startsWith("/api/tenant-a")) {
            return "tenant-a";
        }
        if (path.startsWith("/api/tenant-b")) {
            return "tenant-b";
        }

        // Hoặc resolve từ header
        String tenantHeader = context.request().getHeader("X-Tenant-ID");
        if (tenantHeader != null) {
            return tenantHeader;
        }

        // Default tenant
        return null;
    }
}

HTMLTAG_229__HTMLTAG_230___3.5 Keycloak 授權策略執行者___HTMLTAG_231__HTMLTAG_232

使用 quarkus-keycloak-authorization 強制執行 Keycloak 授權服務策略：

# application.properties
quarkus.keycloak.policy-enforcer.enable=true
quarkus.keycloak.policy-enforcer.enforcement-mode=ENFORCING

# Policy paths
quarkus.keycloak.policy-enforcer.paths.users.path=/api/users/*
quarkus.keycloak.policy-enforcer.paths.users.enforcement-mode=ENFORCING

quarkus.keycloak.policy-enforcer.paths.admin.path=/api/admin/*
quarkus.keycloak.policy-enforcer.paths.admin.enforcement-mode=ENFORCING

quarkus.keycloak.policy-enforcer.paths.public.path=/api/public/*
quarkus.keycloak.policy-enforcer.paths.public.enforcement-mode=DISABLED

HTMLTAG_237__HTMLTAG_238___4。使用測試容器進行測試___HTMLTAG_239__HTMLTAG_240

HTMLTAG_241__HTMLTAG_242___4.1 Spring Boot + Testcontainers Keycloak___HTMLTAG_243__HTMLTAG_244

使用 testcontainers-keycloak 在整合測試中執行真正的 Keycloak：

package com.example;
import com.github.dasniko.testcontainers.keycloak.KeycloakContainer;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.springframework.test.web.servlet.MockMvc;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
@SpringBootTest
@AutoConfigureMockMvc
@Testcontainers
class KeycloakIntegrationTest {
@Container
static KeycloakContainer keycloak = new KeycloakContainer("quay.io/keycloak/keycloak:25.0")
        .withRealmImportFile("test-realm.json");

@Autowired
MockMvc mockMvc;

@DynamicPropertySource
static void configureProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.security.oauth2.resourceserver.jwt.issuer-uri",
        () -> keycloak.getAuthServerUrl() + "/realms/test-realm");
    registry.add("spring.security.oauth2.resourceserver.jwt.jwk-set-uri",
        () -> keycloak.getAuthServerUrl()
            + "/realms/test-realm/protocol/openid-connect/certs");
}

static String adminToken;
static String userToken;

@BeforeAll
static void obtainTokens() {
    // Lấy admin token
    adminToken = getAccessToken("admin-user", "admin-pass");
    // Lấy user token
    userToken = getAccessToken("regular-user", "user-pass");
}

static String getAccessToken(String username, String password) {
    // Sử dụng Keycloak Admin Client hoặc HTTP request
    // để lấy token từ Keycloak container
    String tokenEndpoint = keycloak.getAuthServerUrl()
        + "/realms/test-realm/protocol/openid-connect/token";

    // HTTP POST to token endpoint
    // grant_type=password&client_id=test-client
    // &username=...&password=...
    // Return access_token from response

    // (Implementation chi tiết sử dụng RestTemplate hoặc WebClient)
    return ""; // Placeholder
}

@Test
void publicEndpoint_shouldReturnOk() throws Exception {
    mockMvc.perform(get("/api/public/health"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.status").value("UP"));
}

@Test
void protectedEndpoint_withoutToken_shouldReturn401() throws Exception {
    mockMvc.perform(get("/api/me"))
            .andExpect(status().isUnauthorized());
}

@Test
void protectedEndpoint_withValidToken_shouldReturnOk() throws Exception {
    mockMvc.perform(get("/api/me")
            .header(HttpHeaders.AUTHORIZATION, "Bearer " + userToken))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.username").exists());
}

@Test
void adminEndpoint_withUserToken_shouldReturn403() throws Exception {
    mockMvc.perform(get("/api/admin/dashboard")
            .header(HttpHeaders.AUTHORIZATION, "Bearer " + userToken))
            .andExpect(status().isForbidden());
}

@Test
void adminEndpoint_withAdminToken_shouldReturnOk() throws Exception {
    mockMvc.perform(get("/api/admin/dashboard")
            .header(HttpHeaders.AUTHORIZATION, "Bearer " + adminToken))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.message").exists());
}

}

HTMLTAG_249__HTMLTAG_250___4.2 測驗領域 JSON___HTMLTAG_251__HTMLTAG_252

建立檔案 src/test/resources/test-realm.json 匯入用於測試的領域：

{
  "realm": "test-realm",
  "enabled": true,
  "clients": [
    {
      "clientId": "test-client",
      "enabled": true,
      "publicClient": true,
      "directAccessGrantsEnabled": true,
      "redirectUris": ["*"]
    }
  ],
  "roles": {
    "realm": [
      { "name": "ADMIN", "composite": false },
      { "name": "USER", "composite": false }
    ]
  },
  "users": [
    {
      "username": "admin-user",
      "enabled": true,
      "credentials": [
        { "type": "password", "value": "admin-pass", "temporary": false }
      ],
      "realmRoles": ["ADMIN", "USER"]
    },
    {
      "username": "regular-user",
      "enabled": true,
      "credentials": [
        { "type": "password", "value": "user-pass", "temporary": false }
      ],
      "realmRoles": ["USER"]
    }
  ]
}

HTMLTAG_257__HTMLTAG_258___4.3 使用模擬 JWT 進行單元測試___HTMLTAG_259__HTMLTAG_260

對於沒有真正 Keycloak 的單元測試，請使用 @WithMockUser 或自訂 JWT:

預編碼_20

HTMLTAG_265__HTMLTAG_266___5。最佳實務與故障排除___HTMLTAG_267__HTMLTAG_268

HTMLTAG_269__HTMLTAG_270___5.1 最佳實務___HTMLTAG_271__HTMLTAG_272

Lỗi: "An error occurred while attempting to decode the Jwt"
→ Kiểm tra issuer-uri có đúng realm URL không
→ Đảm bảo Keycloak server đang chạy và accessible

Lỗi: "Jwt expired"
→ Token đã hết hạn, client cần refresh token
→ Kiểm tra Access Token Lifespan trong Keycloak Realm Settings

Lỗi: "Access Denied" dù đúng role
→ Kiểm tra role name trong JWT có match với @PreAuthorize không
→ Debug: log SecurityContext.getAuthentication().getAuthorities()
→ Kiểm tra KeycloakRoleConverter có prefix "ROLE_" đúng không

Lỗi: "CORS error" khi gọi từ frontend
→ Kiểm tra CorsConfiguration có include frontend origin không
→ Đảm bảo Authorization header được allow

# 1. Lấy Access Token từ Keycloak
ACCESS_TOKEN=$(curl -s -X POST \
  "http://localhost:8080/realms/my-realm/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=my-client" \
  -d "username=admin" \
  -d "password=admin" \
  | jq -r '.access_token')

echo $ACCESS_TOKEN

# 2. Decode JWT (kiểm tra claims)
echo $ACCESS_TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | jq .

# 3. Gọi public endpoint
curl -s http://localhost:8081/api/public/health | jq .

# 4. Gọi protected endpoint với token
curl -s http://localhost:8081/api/me \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .

# 5. Gọi admin endpoint
curl -s http://localhost:8081/api/admin/dashboard \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .

# 6. Gọi endpoint không có token (expect 401)
curl -s -o /dev/null -w "%{http_code}" http://localhost:8081/api/me