feat(ap2): hand off access token only

.gitignore

@@ -4,7 +4,7 @@
 *.iml
 
 backend/target/
-bff/target/
+token-mediator/target/
 **/node_modules/
 frontend/dist/
 build/

README.md

@@ -97,16 +97,21 @@ Keycloak을 잠시 중지하고 export한 뒤 자동으로 다시 올립니다.
 runtime export에는 실제 client secret과 credential hash가 포함될 수 있어
 gitignored `build/keycloak-export/`에 권한 `0600`으로만 저장됩니다.
 
-## AP3: Backend-for-Frontend
+## AP2: Token-Mediating Backend
 
-`develop-keycloak-pattern3`의 Spring BFF는 `http://localhost:8083`에서
-실행됩니다. 브라우저에는 HttpOnly session cookie만 두고 access/refresh
-token은 BFF가 서버에 보관합니다. `/bff/api/me`는 BFF가 보유 access
-token을 붙여 Resource Server로 proxy합니다.
+`develop-keycloak-pattern2`의 Spring confidential client는
+`http://localhost:8082`에서 실행됩니다. 브라우저는 로그인 redirect와
+HttpOnly `AP2_SESSION`만 사용하고, authorization code 교환과
+access/refresh token 보관은 backend가 담당합니다.
 
 ```bash
-./scripts/verify-pattern3.sh
+./scripts/verify-pattern2.sh
 ```
 
-자세한 경계와 session 저장소 trade-off는
-[`docs/ap3-bff-boundary.md`](docs/ap3-bff-boundary.md)를 참고하세요.
+`/token/boundary`는 실제 token 값을 반환하지 않고 서버 저장 여부만 보여줍니다.
+`/token/access`는 access token과 만료 메타데이터만 `no-store`로 전달하며,
+refresh token은 반환하지 않습니다. 브라우저는 이 access token으로
+`http://localhost:8081/api/me`를 직접 호출합니다.
+
+자세한 token 경계와 실험 항목은
+[`docs/ap2-token-boundary.md`](docs/ap2-token-boundary.md)를 참고하세요.

backend/src/main/java/com/example/keycloakpattern/SecurityConfig.java

@@ -1,11 +1,16 @@
 package com.example.keycloakpattern;
 
+import java.util.List;
+
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.http.SessionCreationPolicy;
 import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.web.cors.CorsConfiguration;
+import org.springframework.web.cors.CorsConfigurationSource;
+import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
 
 @Configuration
 public class SecurityConfig {
@@ -13,6 +18,7 @@ public class SecurityConfig {
     @Bean
     SecurityFilterChain apiSecurity(HttpSecurity http) throws Exception {
         return http
+            .cors(Customizer.withDefaults())
             .csrf(csrf -> csrf.disable())
             .sessionManagement(session ->
                 session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
@@ -24,4 +30,16 @@ public class SecurityConfig {
             .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
             .build();
     }
+
+    @Bean
+    CorsConfigurationSource corsConfigurationSource() {
+        CorsConfiguration configuration = new CorsConfiguration();
+        configuration.setAllowedOrigins(List.of("http://localhost:8082"));
+        configuration.setAllowedMethods(List.of("GET", "OPTIONS"));
+        configuration.setAllowedHeaders(List.of("Authorization", "Content-Type"));
+
+        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+        source.registerCorsConfiguration("/api/**", configuration);
+        return source;
+    }
 }

bff/src/main/java/com/example/keycloakpattern/bff/BffController.java

@@ -1,112 +0,0 @@
-package com.example.keycloakpattern.bff;
-
-import java.util.LinkedHashMap;
-import java.util.Map;
-import java.util.concurrent.atomic.AtomicReference;
-
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.http.CacheControl;
-import org.springframework.http.HttpHeaders;
-import org.springframework.http.ResponseEntity;
-import org.springframework.security.core.Authentication;
-import org.springframework.security.oauth2.client.OAuth2AuthorizeRequest;
-import org.springframework.security.oauth2.client.OAuth2AuthorizedClient;
-import org.springframework.security.oauth2.client.OAuth2AuthorizedClientManager;
-import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
-import org.springframework.web.bind.annotation.GetMapping;
-import org.springframework.web.bind.annotation.PostMapping;
-import org.springframework.web.bind.annotation.RequestParam;
-import org.springframework.web.bind.annotation.RestController;
-import org.springframework.web.client.RestClient;
-import org.springframework.web.server.ResponseStatusException;
-
-import static org.springframework.http.HttpStatus.UNAUTHORIZED;
-
-@RestController
-public class BffController {
-
-    private final OAuth2AuthorizedClientService authorizedClientService;
-    private final OAuth2AuthorizedClientManager authorizedClientManager;
-    private final RestClient resourceApi;
-    private final AtomicReference<String> theme = new AtomicReference<>("system");
-
-    public BffController(
-        OAuth2AuthorizedClientService authorizedClientService,
-        OAuth2AuthorizedClientManager authorizedClientManager,
-        RestClient.Builder restClientBuilder,
-        @Value("${resource-api.base-url}") String resourceApiBaseUrl
-    ) {
-        this.authorizedClientService = authorizedClientService;
-        this.authorizedClientManager = authorizedClientManager;
-        this.resourceApi = restClientBuilder.baseUrl(resourceApiBaseUrl).build();
-    }
-
-    @GetMapping("/bff/token-boundary")
-    ResponseEntity<Map<String, Object>> tokenBoundary(Authentication authentication) {
-        OAuth2AuthorizedClient client = authorizedClientService.loadAuthorizedClient(
-            "keycloak",
-            authentication.getName()
-        );
-
-        Map<String, Object> response = new LinkedHashMap<>();
-        response.put("pattern", "AP3-backend-for-frontend");
-        response.put("principal", authentication.getName());
-        response.put("accessTokenStoredOnServer", client != null
-            && client.getAccessToken() != null);
-        response.put("refreshTokenStoredOnServer", client != null
-            && client.getRefreshToken() != null);
-        response.put("browserTokenCount", 0);
-        response.put("csrfProtectionEnabled", false);
-
-        return ResponseEntity.ok()
-            .cacheControl(CacheControl.noStore())
-            .header("Pragma", "no-cache")
-            .body(response);
-    }
-
-    @GetMapping("/bff/api/me")
-    ResponseEntity<?> currentUser(Authentication authentication) {
-        OAuth2AuthorizedClient client = authorizedClient(authentication);
-        return resourceApi.get()
-            .uri("/api/me")
-            .header(
-                HttpHeaders.AUTHORIZATION,
-                "Bearer " + client.getAccessToken().getTokenValue()
-            )
-            .retrieve()
-            .toEntity(Map.class);
-    }
-
-    @PostMapping("/bff/api/preferences")
-    Map<String, Object> updatePreference(
-        Authentication authentication,
-        @RequestParam(defaultValue = "system") String theme
-    ) {
-        this.theme.set(theme);
-        return Map.of(
-            "updated", true,
-            "theme", this.theme.get(),
-            "principal", authentication.getName()
-        );
-    }
-
-    @GetMapping("/bff/api/preferences")
-    Map<String, String> preference() {
-        return Map.of("theme", theme.get());
-    }
-
-    private OAuth2AuthorizedClient authorizedClient(Authentication authentication) {
-        OAuth2AuthorizeRequest request = OAuth2AuthorizeRequest
-            .withClientRegistrationId("keycloak")
-            .principal(authentication)
-            .build();
-        OAuth2AuthorizedClient client = authorizedClientManager.authorize(request);
-        if (client == null || client.getAccessToken() == null) {
-            throw new ResponseStatusException(
-                UNAUTHORIZED,
-                "No authorized Keycloak client is available"
-            );
-        }
-        return client;
-    }
-}

bff/src/main/resources/static/app.js

@@ -1,39 +0,0 @@
-const result = document.querySelector("#result");
-
-function render(value) {
-  result.textContent = JSON.stringify(value, null, 2);
-}
-
-async function request(path, options = {}) {
-  const response = await fetch(path, {
-    ...options,
-    headers: { Accept: "application/json", ...options.headers },
-  });
-  if (response.redirected || response.status === 401) {
-    window.location.assign("/oauth2/authorization/keycloak");
-    return null;
-  }
-  const body = await response.json();
-  render({ status: response.status, ...body });
-  return { response, body };
-}
-
-document.querySelector("#login").addEventListener("click", () => {
-  window.location.assign("/oauth2/authorization/keycloak");
-});
-
-document.querySelector("#inspect").addEventListener("click", () => {
-  void request("/bff/token-boundary");
-});
-
-document.querySelector("#call-bff").addEventListener("click", () => {
-  void request("/bff/api/me");
-});
-
-document.querySelector("#change-without-csrf").addEventListener("click", () => {
-  void request("/bff/api/preferences", {
-    method: "POST",
-    body: new URLSearchParams({ theme: "dark" }),
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-  });
-});

bff/src/main/resources/static/index.html

@@ -1,31 +0,0 @@
-<!doctype html>
-<html lang="ko">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>AP3 · Backend-for-Frontend</title>
-  <style>
-    :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
-    body { max-width: 58rem; margin: 6vh auto; padding: 0 1.5rem; line-height: 1.6; }
-    button { margin: 0 0.5rem 0.5rem 0; padding: 0.6rem 0.9rem; cursor: pointer; }
-    pre { min-height: 9rem; padding: 1rem; border-radius: 0.4rem;
-      background: color-mix(in srgb, CanvasText 9%, Canvas); white-space: pre-wrap; }
-  </style>
-</head>
-<body>
-  <main>
-    <h1>AP3 · Backend-for-Frontend</h1>
-    <p>
-      브라우저에는 OAuth token이 전혀 전달되지 않습니다. HttpOnly session
-      cookie로 BFF만 호출하고, BFF가 서버 보관 access token을 Resource
-      Server 요청에 붙입니다.
-    </p>
-    <button id="login" type="button">Keycloak 로그인</button>
-    <button id="inspect" type="button">token 경계 확인</button>
-    <button id="call-bff" type="button">BFF 경유 API 호출</button>
-    <button id="change-without-csrf" type="button">CSRF token 없이 상태 변경</button>
-    <pre id="result" aria-live="polite"></pre>
-  </main>
-  <script type="module" src="/app.js"></script>
-</body>
-</html>

docker-compose.yml

@@ -86,24 +86,21 @@ services:
       - keycloak-net
     restart: unless-stopped
 
-  bff:
+  token-mediator:
     build:
-      context: ./bff
+      context: ./token-mediator
     environment:
-      SERVER_PORT: "8083"
-      KEYCLOAK_CLIENT_SECRET: ${BFF_CLIENT_SECRET:?set BFF_CLIENT_SECRET in .env}
-      RESOURCE_API_BASE_URL: http://app:8081
+      SERVER_PORT: "8082"
+      KEYCLOAK_CLIENT_SECRET: ${TOKEN_MEDIATING_CLIENT_SECRET:?set TOKEN_MEDIATING_CLIENT_SECRET in .env}
     ports:
-      - "127.0.0.1:8083:8083"
+      - "127.0.0.1:8082:8082"
     depends_on:
       keycloak:
         condition: service_healthy
-      app:
-        condition: service_healthy
     healthcheck:
       test:
         - CMD-SHELL
-        - wget -q -O - http://127.0.0.1:8083/actuator/health | grep -q '"status":"UP"'
+        - wget -q -O - http://127.0.0.1:8082/actuator/health | grep -q '"status":"UP"'
       interval: 10s
       timeout: 5s
       retries: 12

docs/ap2-token-boundary.md

@@ -0,0 +1,38 @@
+# AP2 · Token-Mediating Backend
+
+## 책임 경계
+
+1. 브라우저는 Spring backend의 `/oauth2/authorization/keycloak`로 로그인을
+   시작합니다.
+2. Keycloak은 authorization code를 Spring callback으로 전달합니다.
+3. confidential client인 Spring backend가 client secret을 사용해 code를
+   교환하고 access/refresh token을 `OAuth2AuthorizedClientService`에
+   보관합니다.
+4. 브라우저가 `/token/access`를 호출하면 backend는 현재 access token,
+   token type, 만료 시각만 `Cache-Control: no-store`로 반환합니다.
+5. 브라우저는 전달받은 access token을 메모리에서만 사용해 Resource
+   Server를 직접 호출합니다.
+
+refresh token은 브라우저 응답, Web Storage, cookie에 전달되지 않습니다.
+access token이 만료되면 `OAuth2AuthorizedClientManager`가 서버에 보관된
+refresh token으로 갱신한 뒤 새 access token만 전달할 수 있습니다.
+
+## 확인할 보안 속성
+
+- Keycloak client는 `client_secret_basic`을 사용하는 confidential client입니다.
+- Resource Server는 서명, issuer, timestamp와 함께
+  `aud=keycloak-pattern-api`를 검증합니다.
+- CORS는 AP2 UI origin인 `http://localhost:8082`의 `GET`만 허용합니다.
+- access-token 응답에는 `refresh_token` 필드가 없고 `no-store`가 적용됩니다.
+- 브라우저 cookie에는 HttpOnly, SameSite=Lax인 `AP2_SESSION` 식별자만
+  저장됩니다. 실제 OAuth token은 session cookie 안에 들어가지 않습니다.
+
+## 실행
+
+```bash
+./scripts/verify-pattern2.sh
+```
+
+검증은 실제 Keycloak 로그인 후 서버 token 보관 여부, access-only 응답의
+필드 집합과 audience, 브라우저의 직접 Resource Server 호출, Web Storage
+비사용을 확인합니다.

docs/ap3-bff-boundary.md

@@ -1,28 +0,0 @@
-# AP3 · Backend-for-Frontend
-
-## 요청과 token 경계
-
-1. 브라우저는 BFF의 `/oauth2/authorization/keycloak`로 로그인을 시작합니다.
-2. Spring `oauth2Login`은 PKCE S256 authorization code flow를 수행합니다.
-3. BFF가 client secret으로 code를 교환하고 access/refresh token을 서버의
-   `OAuth2AuthorizedClientService`에 보관합니다.
-4. 브라우저에는 OAuth token 대신 HttpOnly `AP3_SESSION` 식별자만 남습니다.
-5. 브라우저가 `/bff/api/me`를 cookie로 호출하면 BFF가 access token을
-   `Authorization: Bearer`로 붙여 Resource Server에 fan-out합니다.
-
-Resource Server는 `aud=keycloak-pattern-api`를 검증합니다. 브라우저에서는
-8081로 직접 요청하거나 Keycloak token endpoint를 호출하지 않습니다.
-
-학습용 구성은 단일 인스턴스 메모리에 session과 authorized client를
-보관합니다. BFF를 재시작하면 세션이 사라집니다. 다중 인스턴스 운영에서는
-Spring Session/Redis 같은 공유 저장소와 저장 token 암호화 정책이 필요합니다.
-
-## 방어 전 CSRF 재현
-
-이 feature 브랜치에서는 다음 CSRF 방어 feature와 비교하기 위해 CSRF를
-의도적으로 끕니다. 다른 origin의 자동 제출 form이 브라우저 cookie를
-자동으로 포함해 `/bff/api/preferences` 상태를 바꾸는 것을 E2E에서
-재현합니다.
-
-이 취약 상태는 `feature/keycloak-bff-csrf-samesite-defense`에서 Spring
-CSRF token과 명시적 SameSite=Lax를 적용해 차단합니다.

e2e/package.json

@@ -4,7 +4,7 @@
   "version": "1.0.0",
   "type": "module",
   "scripts": {
-    "test:pattern3": "node pattern3.mjs"
+    "test:pattern2": "node pattern2.mjs"
   },
   "devDependencies": {
     "playwright-core": "1.62.0"

e2e/pattern2.mjs

@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import { chromium } from "playwright-core";
+
+const password = process.env.E2E_PASSWORD;
+assert.ok(password, "E2E_PASSWORD must be set");
+
+async function completeKeycloakLogin(page) {
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    await page.locator("#username").fill(
+      process.env.E2E_USERNAME ?? "regular-user",
+    );
+    await page.locator("#password").fill(password);
+    await page.locator("#kc-login").click();
+    await page.waitForLoadState("domcontentloaded");
+
+    if (page.url() === "http://localhost:8082/") {
+      return;
+    }
+    if (attempt === 1) {
+      await page.goto(
+        "http://localhost:8082/oauth2/authorization/keycloak",
+      );
+      await page.waitForURL(/localhost:8080/u);
+    }
+  }
+  throw new Error(`Keycloak login did not return to AP2: ${page.url()}`);
+}
+
+const browser = await chromium.launch({
+  executablePath: process.env.CHROME_BIN ?? "/usr/bin/google-chrome",
+  headless: true,
+  args: ["--no-sandbox"],
+});
+
+try {
+  const context = await browser.newContext();
+  const page = await context.newPage();
+
+  await page.goto("http://localhost:8082");
+  await page.locator("#login").click();
+  await page.waitForURL(/localhost:8080/u);
+  await completeKeycloakLogin(page);
+
+  const boundaryResponsePromise = page.waitForResponse((response) =>
+    response.url().endsWith("/token/boundary"),
+  );
+  await page.locator("#inspect").click();
+  const boundaryResponse = await boundaryResponsePromise;
+  assert.equal(boundaryResponse.status(), 200);
+  const boundary = await boundaryResponse.json();
+
+  assert.equal(boundary.accessTokenStored, true);
+  assert.equal(boundary.refreshTokenStored, true);
+  assert.equal(boundary.browserReceivesRefreshToken, false);
+  assert.equal(JSON.stringify(boundary).includes("refresh_token"), false);
+
+  const accessResponsePromise = page.waitForResponse((response) =>
+    response.url().endsWith("/token/access"),
+  );
+  const resourceResponsePromise = page.waitForResponse(
+    (response) =>
+      response.url() === "http://localhost:8081/api/me" &&
+      response.request().method() === "GET",
+  );
+  await page.locator("#call-api").click();
+
+  const accessResponse = await accessResponsePromise;
+  assert.equal(accessResponse.status(), 200);
+  assert.match(accessResponse.headers()["cache-control"], /no-store/u);
+  const accessHandoff = await accessResponse.json();
+  assert.deepEqual(
+    Object.keys(accessHandoff).sort(),
+    ["access_token", "expires_at", "token_type"],
+  );
+  assert.equal(accessHandoff.token_type, "Bearer");
+  assert.equal(typeof accessHandoff.access_token, "string");
+  assert.ok(accessHandoff.access_token.length > 100);
+  assert.equal(JSON.stringify(accessHandoff).includes("refresh_token"), false);
+
+  const [, payload] = accessHandoff.access_token.split(".");
+  const claims = JSON.parse(
+    Buffer.from(payload, "base64url").toString("utf8"),
+  );
+  const audience = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+  assert.ok(audience.includes("keycloak-pattern-api"));
+
+  const resourceResponse = await resourceResponsePromise;
+  assert.equal(resourceResponse.status(), 200);
+  const resource = await resourceResponse.json();
+  assert.equal(resource.username, "regular-user");
+  assert.ok(resource.audience.includes("keycloak-pattern-api"));
+  await page.locator("#result").getByText('"resourceApiStatus": 200').waitFor();
+
+  const cookies = await context.cookies("http://localhost:8082/");
+  const sessionCookie = cookies.find((cookie) => cookie.name === "AP2_SESSION");
+  assert.ok(sessionCookie);
+  assert.equal(sessionCookie.httpOnly, true);
+  assert.equal(sessionCookie.sameSite, "Lax");
+
+  const storage = await page.evaluate(() => ({
+    localStorage: Object.values(localStorage),
+    sessionStorage: Object.values(sessionStorage),
+  }));
+  assert.equal(JSON.stringify(storage).includes("refresh_token"), false);
+  assert.equal(
+    JSON.stringify(storage).includes(accessHandoff.access_token),
+    false,
+  );
+
+  console.log(
+    "pattern2 verified: server refresh custody, access-only handoff, direct browser resource call",
+  );
+} finally {
+  await browser.close();
+}

e2e/pattern3.mjs

@@ -1,140 +0,0 @@
-import assert from "node:assert/strict";
-import { chromium } from "playwright-core";
-
-const password = process.env.E2E_PASSWORD;
-assert.ok(password, "E2E_PASSWORD must be set");
-
-async function completeKeycloakLogin(page) {
-  for (let attempt = 1; attempt <= 2; attempt += 1) {
-    await page.locator("#username").fill(
-      process.env.E2E_USERNAME ?? "regular-user",
-    );
-    await page.locator("#password").fill(password);
-    await page.locator("#kc-login").click();
-    await page.waitForLoadState("domcontentloaded");
-
-    if (page.url() === "http://localhost:8083/") {
-      return;
-    }
-    if (attempt === 1) {
-      await page.goto(
-        "http://localhost:8083/oauth2/authorization/keycloak",
-      );
-      await page.waitForURL(/localhost:8080/u);
-    }
-  }
-  throw new Error(`Keycloak login did not return to AP3: ${page.url()}`);
-}
-
-const browser = await chromium.launch({
-  executablePath: process.env.CHROME_BIN ?? "/usr/bin/google-chrome",
-  headless: true,
-  args: ["--no-sandbox"],
-});
-
-try {
-  const context = await browser.newContext();
-  const page = await context.newPage();
-  const browserRequests = [];
-  page.on("request", (request) => browserRequests.push(request.url()));
-
-  await page.goto("http://localhost:8083");
-  const authorizationRequestPromise = page.waitForRequest((request) =>
-    request.url().includes(
-      "/protocol/openid-connect/auth?response_type=code",
-    ),
-  );
-  await page.locator("#login").click();
-  const authorizationRequest = await authorizationRequestPromise;
-  const authorizationUrl = new URL(authorizationRequest.url());
-  assert.equal(authorizationUrl.searchParams.get("client_id"), "bff-confidential");
-  assert.equal(authorizationUrl.searchParams.get("code_challenge_method"), "S256");
-  assert.ok(authorizationUrl.searchParams.get("code_challenge"));
-
-  await page.waitForURL(/localhost:8080/u);
-  await completeKeycloakLogin(page);
-  const callbackRequest = browserRequests.find((url) =>
-    url.startsWith("http://localhost:8083/login/oauth2/code/keycloak?"),
-  );
-  assert.ok(callbackRequest, "authorization response must use the BFF callback");
-
-  const boundaryResponsePromise = page.waitForResponse((response) =>
-    response.url().endsWith("/bff/token-boundary"),
-  );
-  await page.locator("#inspect").click();
-  const boundaryResponse = await boundaryResponsePromise;
-  assert.equal(boundaryResponse.status(), 200);
-  const boundary = await boundaryResponse.json();
-  assert.equal(boundary.accessTokenStoredOnServer, true);
-  assert.equal(boundary.refreshTokenStoredOnServer, true);
-  assert.equal(boundary.browserTokenCount, 0);
-  assert.equal(boundary.csrfProtectionEnabled, false);
-  assert.equal(JSON.stringify(boundary).includes("access_token"), false);
-  assert.equal(JSON.stringify(boundary).includes("refresh_token"), false);
-
-  const proxyResponsePromise = page.waitForResponse((response) =>
-    response.url().endsWith("/bff/api/me"),
-  );
-  await page.locator("#call-bff").click();
-  const proxyResponse = await proxyResponsePromise;
-  assert.equal(proxyResponse.status(), 200);
-  const resource = await proxyResponse.json();
-  assert.equal(resource.username, "regular-user");
-  assert.ok(resource.audience.includes("keycloak-pattern-api"));
-
-  assert.equal(
-    browserRequests.some((url) => url.startsWith("http://localhost:8081/")),
-    false,
-    "the browser must not bypass the BFF",
-  );
-  assert.equal(
-    browserRequests.some((url) =>
-      url.includes("/protocol/openid-connect/token"),
-    ),
-    false,
-    "the token exchange must be server-to-server",
-  );
-
-  const cookies = await context.cookies("http://localhost:8083/");
-  const sessionCookie = cookies.find((cookie) => cookie.name === "AP3_SESSION");
-  assert.ok(sessionCookie);
-  assert.equal(sessionCookie.httpOnly, true);
-
-  const storage = await page.evaluate(() => ({
-    localStorage: Object.values(localStorage),
-    sessionStorage: Object.values(sessionStorage),
-    readableCookies: document.cookie,
-  }));
-  assert.deepEqual(storage.localStorage, []);
-  assert.deepEqual(storage.sessionStorage, []);
-  assert.equal(storage.readableCookies.includes("AP3_SESSION"), false);
-
-  await page.goto("http://localhost:8088");
-  const forgedResponsePromise = page.waitForResponse(
-    (response) =>
-      response.url() === "http://localhost:8083/bff/api/preferences" &&
-      response.request().method() === "POST",
-  );
-  await page.evaluate(() => {
-    const form = document.createElement("form");
-    form.method = "POST";
-    form.action = "http://localhost:8083/bff/api/preferences";
-    const input = document.createElement("input");
-    input.name = "theme";
-    input.value = "attacker";
-    form.append(input);
-    document.body.append(form);
-    form.submit();
-  });
-  const forgedResponse = await forgedResponsePromise;
-  assert.equal(forgedResponse.status(), 200);
-  const forgedResult = await forgedResponse.json();
-  assert.equal(forgedResult.updated, true);
-  assert.equal(forgedResult.theme, "attacker");
-
-  console.log(
-    "pattern3 BFF verified: browser token 0, session-only proxy 200, pre-defense CSRF reproduced",
-  );
-} finally {
-  await browser.close();
-}

keycloak/import/keycloak-patterns-realm.json

@@ -75,7 +75,22 @@
       ],
       "attributes": {
         "post.logout.redirect.uris": "http://localhost:8082/*"
-      }
+      },
+      "protocolMappers": [
+        {
+          "name": "keycloak-pattern-api-audience",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-audience-mapper",
+          "consentRequired": false,
+          "config": {
+            "included.custom.audience": "keycloak-pattern-api",
+            "id.token.claim": "false",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "false",
+            "introspection.token.claim": "true"
+          }
+        }
+      ]
     },
     {
       "clientId": "bff-confidential",
@@ -98,24 +113,8 @@
         "http://localhost:8083"
       ],
       "attributes": {
-        "pkce.code.challenge.method": "S256",
         "post.logout.redirect.uris": "http://localhost:8083/*"
-      },
-      "protocolMappers": [
-        {
-          "name": "keycloak-pattern-api-audience",
-          "protocol": "openid-connect",
-          "protocolMapper": "oidc-audience-mapper",
-          "consentRequired": false,
-          "config": {
-            "included.custom.audience": "keycloak-pattern-api",
-            "id.token.claim": "false",
-            "access.token.claim": "true",
-            "userinfo.token.claim": "false",
-            "introspection.token.claim": "true"
-          }
-        }
-      ]
+      }
     },
     {
       "clientId": "edge-proxy",

scripts/verify-pattern2.sh

@@ -16,6 +16,6 @@ docker compose up --build -d --wait
 npm --prefix e2e ci
 E2E_USERNAME=regular-user \
 E2E_PASSWORD="$REGULAR_USER_PASSWORD" \
-  npm --prefix e2e run test:pattern3
+  npm --prefix e2e run test:pattern2
 
-echo "AP3 BFF session and CSRF behavior verified"
+echo "AP2 confidential client boundary verified"

token-mediator/Dockerfile

@@ -1,4 +1,5 @@
 FROM maven:3.9.11-eclipse-temurin-21-alpine AS build
+
 WORKDIR /workspace
 COPY pom.xml .
 RUN mvn --batch-mode dependency:go-offline
@@ -6,9 +7,11 @@ COPY src src
 RUN mvn --batch-mode verify
 
 FROM eclipse-temurin:21-jre-alpine
+
 RUN addgroup -S spring && adduser -S spring -G spring
 WORKDIR /app
-COPY --from=build /workspace/target/keycloak-bff.jar app.jar
+COPY --from=build /workspace/target/keycloak-token-mediator.jar app.jar
 USER spring:spring
-EXPOSE 8083
+
+EXPOSE 8082
 ENTRYPOINT ["java", "-jar", "/app/app.jar"]

token-mediator/pom.xml

@@ -12,9 +12,9 @@
     </parent>
 
     <groupId>com.example</groupId>
-    <artifactId>keycloak-bff</artifactId>
+    <artifactId>keycloak-token-mediator</artifactId>
     <version>0.0.1-SNAPSHOT</version>
-    <name>keycloak-bff</name>
+    <name>keycloak-token-mediator</name>
 
     <properties>
         <java.version>21</java.version>
@@ -47,7 +47,7 @@
     </dependencies>
 
     <build>
-        <finalName>keycloak-bff</finalName>
+        <finalName>keycloak-token-mediator</finalName>
         <plugins>
             <plugin>
                 <groupId>org.springframework.boot</groupId>

token-mediator/src/main/java/com/example/keycloakpattern/mediator/AccessTokenController.java

@@ -0,0 +1,56 @@
+package com.example.keycloakpattern.mediator;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import org.springframework.http.CacheControl;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.oauth2.client.OAuth2AuthorizeRequest;
+import org.springframework.security.oauth2.client.OAuth2AuthorizedClient;
+import org.springframework.security.oauth2.client.OAuth2AuthorizedClientManager;
+import org.springframework.security.oauth2.core.OAuth2AccessToken;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import static org.springframework.http.HttpStatus.UNAUTHORIZED;
+
+@RestController
+public class AccessTokenController {
+
+    private final OAuth2AuthorizedClientManager authorizedClientManager;
+
+    public AccessTokenController(OAuth2AuthorizedClientManager authorizedClientManager) {
+        this.authorizedClientManager = authorizedClientManager;
+    }
+
+    @GetMapping("/token/access")
+    ResponseEntity<Map<String, Object>> accessToken(Authentication authentication) {
+        OAuth2AuthorizeRequest request = OAuth2AuthorizeRequest
+            .withClientRegistrationId("keycloak")
+            .principal(authentication)
+            .build();
+        OAuth2AuthorizedClient client = authorizedClientManager.authorize(request);
+        if (client == null || client.getAccessToken() == null) {
+            throw new ResponseStatusException(
+                UNAUTHORIZED,
+                "No authorized Keycloak client is available"
+            );
+        }
+
+        OAuth2AccessToken token = client.getAccessToken();
+        Map<String, Object> response = new LinkedHashMap<>();
+        response.put("access_token", token.getTokenValue());
+        response.put("token_type", token.getTokenType().getValue());
+        response.put(
+            "expires_at",
+            token.getExpiresAt() == null ? null : token.getExpiresAt().toString()
+        );
+
+        return ResponseEntity.ok()
+            .cacheControl(CacheControl.noStore())
+            .header("Pragma", "no-cache")
+            .body(response);
+    }
+}

token-mediator/src/main/java/com/example/keycloakpattern/mediator/SecurityConfig.java

@@ -1,4 +1,4 @@
-package com.example.keycloakpattern.bff;
+package com.example.keycloakpattern.mediator;
 
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -9,29 +9,14 @@ import org.springframework.security.oauth2.client.OAuth2AuthorizedClientProvider
 import org.springframework.security.oauth2.client.OAuth2AuthorizedClientProviderBuilder;
 import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
 import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
-import org.springframework.security.oauth2.client.web.DefaultOAuth2AuthorizationRequestResolver;
-import org.springframework.security.oauth2.client.web.OAuth2AuthorizationRequestCustomizers;
 import org.springframework.security.web.SecurityFilterChain;
 
 @Configuration
 public class SecurityConfig {
 
     @Bean
-    SecurityFilterChain bffSecurity(
-        HttpSecurity http,
-        ClientRegistrationRepository clientRegistrationRepository
-    ) throws Exception {
-        DefaultOAuth2AuthorizationRequestResolver authorizationRequestResolver =
-            new DefaultOAuth2AuthorizationRequestResolver(
-                clientRegistrationRepository,
-                "/oauth2/authorization"
-            );
-        authorizationRequestResolver.setAuthorizationRequestCustomizer(
-            OAuth2AuthorizationRequestCustomizers.withPkce()
-        );
-
+    SecurityFilterChain mediatorSecurity(HttpSecurity http) throws Exception {
         return http
-            .csrf(csrf -> csrf.disable())
             .authorizeHttpRequests(authorize -> authorize
                 .requestMatchers(
                     "/",
@@ -44,10 +29,7 @@ public class SecurityConfig {
                 .permitAll()
                 .anyRequest()
                 .authenticated())
-            .oauth2Login(oauth2 -> oauth2
-                .authorizationEndpoint(endpoint -> endpoint
-                    .authorizationRequestResolver(authorizationRequestResolver))
-                .defaultSuccessUrl("/", true))
+            .oauth2Login(oauth2 -> oauth2.defaultSuccessUrl("/", true))
             .build();
     }
 

token-mediator/src/main/java/com/example/keycloakpattern/mediator/TokenBoundaryController.java

@@ -0,0 +1,44 @@
+package com.example.keycloakpattern.mediator;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import org.springframework.http.CacheControl;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.oauth2.client.OAuth2AuthorizedClient;
+import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class TokenBoundaryController {
+
+    private final OAuth2AuthorizedClientService authorizedClientService;
+
+    public TokenBoundaryController(
+        OAuth2AuthorizedClientService authorizedClientService
+    ) {
+        this.authorizedClientService = authorizedClientService;
+    }
+
+    @GetMapping("/token/boundary")
+    ResponseEntity<Map<String, Object>> tokenBoundary(Authentication authentication) {
+        OAuth2AuthorizedClient client = authorizedClientService.loadAuthorizedClient(
+            "keycloak",
+            authentication.getName()
+        );
+
+        Map<String, Object> response = new LinkedHashMap<>();
+        response.put("pattern", "AP2-token-mediating-backend");
+        response.put("principal", authentication.getName());
+        response.put("accessTokenStored", client != null && client.getAccessToken() != null);
+        response.put("refreshTokenStored", client != null && client.getRefreshToken() != null);
+        response.put("browserReceivesRefreshToken", false);
+
+        return ResponseEntity.ok()
+            .cacheControl(CacheControl.noStore())
+            .header("Pragma", "no-cache")
+            .body(response);
+    }
+}

token-mediator/src/main/java/com/example/keycloakpattern/mediator/TokenMediatorApplication.java

@@ -1,12 +1,12 @@
-package com.example.keycloakpattern.bff;
+package com.example.keycloakpattern.mediator;
 
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
 @SpringBootApplication
-public class BffApplication {
+public class TokenMediatorApplication {
 
     public static void main(String[] args) {
-        SpringApplication.run(BffApplication.class, args);
+        SpringApplication.run(TokenMediatorApplication.class, args);
     }
 }

token-mediator/src/main/resources/application.yml

@@ -1,21 +1,22 @@
 server:
-  port: ${SERVER_PORT:8083}
+  port: ${SERVER_PORT:8082}
   servlet:
     session:
       cookie:
-        name: AP3_SESSION
+        name: AP2_SESSION
         http-only: true
+        same-site: lax
 
 spring:
   application:
-    name: keycloak-bff
+    name: keycloak-token-mediator
   security:
     oauth2:
       client:
         registration:
           keycloak:
             provider: keycloak
-            client-id: bff-confidential
+            client-id: token-mediating-confidential
             client-secret: ${KEYCLOAK_CLIENT_SECRET}
             client-authentication-method: client_secret_basic
             authorization-grant-type: authorization_code
@@ -32,9 +33,6 @@ spring:
             user-info-uri: http://keycloak:8080/realms/keycloak-patterns/protocol/openid-connect/userinfo
             user-name-attribute: preferred_username
 
-resource-api:
-  base-url: ${RESOURCE_API_BASE_URL:http://localhost:8081}
-
 management:
   endpoint:
     health:

token-mediator/src/main/resources/static/app.js

@@ -0,0 +1,50 @@
+const result = document.querySelector("#result");
+
+function render(value) {
+  result.textContent = JSON.stringify(value, null, 2);
+}
+
+document.querySelector("#login").addEventListener("click", () => {
+  window.location.assign("/oauth2/authorization/keycloak");
+});
+
+document.querySelector("#inspect").addEventListener("click", async () => {
+  const response = await fetch("/token/boundary", {
+    headers: { Accept: "application/json" },
+  });
+  if (response.redirected || response.status === 401) {
+    window.location.assign("/oauth2/authorization/keycloak");
+    return;
+  }
+  render(await response.json());
+});
+
+document.querySelector("#call-api").addEventListener("click", async () => {
+  const tokenResponse = await fetch("/token/access", {
+    headers: { Accept: "application/json" },
+  });
+  if (tokenResponse.redirected || tokenResponse.status === 401) {
+    window.location.assign("/oauth2/authorization/keycloak");
+    return;
+  }
+  if (!tokenResponse.ok) {
+    render({ tokenEndpointStatus: tokenResponse.status });
+    return;
+  }
+
+  const { access_token: accessToken, expires_at: expiresAt } =
+    await tokenResponse.json();
+  const apiResponse = await fetch("http://localhost:8081/api/me", {
+    headers: {
+      Accept: "application/json",
+      Authorization: `Bearer ${accessToken}`,
+    },
+  });
+  render({
+    accessTokenHeldInMemoryOnly: true,
+    refreshTokenReceived: false,
+    accessTokenExpiresAt: expiresAt,
+    resourceApiStatus: apiResponse.status,
+    resource: await apiResponse.json(),
+  });
+});

token-mediator/src/main/resources/static/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>AP2 · Token-Mediating Backend</title>
+  <style>
+    :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+    body { max-width: 52rem; margin: 6vh auto; padding: 0 1.5rem; line-height: 1.6; }
+    button { margin-right: 0.5rem; padding: 0.6rem 0.9rem; cursor: pointer; }
+    pre { min-height: 8rem; padding: 1rem; border-radius: 0.4rem;
+      background: color-mix(in srgb, CanvasText 9%, Canvas); white-space: pre-wrap; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>AP2 · Token-Mediating Backend</h1>
+    <p>
+      confidential backend가 authorization code를 token으로 교환합니다.
+      refresh token은 서버의 <code>OAuth2AuthorizedClientService</code>에만
+      보관됩니다.
+    </p>
+    <button id="login" type="button">Keycloak 로그인</button>
+    <button id="inspect" type="button">서버 token 경계 확인</button>
+    <button id="call-api" type="button">access token으로 API 직접 호출</button>
+    <pre id="result" aria-live="polite"></pre>
+  </main>
+  <script type="module" src="/app.js"></script>
+</body>
+</html>

token-mediator/src/test/java/com/example/keycloakpattern/mediator/TokenBoundaryControllerTest.java

@@ -1,18 +1,21 @@
-package com.example.keycloakpattern.bff;
+package com.example.keycloakpattern.mediator;
 
+import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.oidcLogin;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
+import java.time.Instant;
+
 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.security.oauth2.client.OAuth2AuthorizeRequest;
 import org.springframework.security.oauth2.client.OAuth2AuthorizedClient;
 import org.springframework.security.oauth2.client.OAuth2AuthorizedClientManager;
 import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
@@ -21,12 +24,9 @@ import org.springframework.security.oauth2.core.OAuth2RefreshToken;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
 import org.springframework.test.web.servlet.MockMvc;
 
-@SpringBootTest(properties = {
-    "KEYCLOAK_CLIENT_SECRET=test-only-secret",
-    "resource-api.base-url=http://127.0.0.1:9"
-})
+@SpringBootTest(properties = "KEYCLOAK_CLIENT_SECRET=test-only-secret")
 @AutoConfigureMockMvc
-class BffControllerTest {
+class TokenBoundaryControllerTest {
 
     @Autowired
     private MockMvc mockMvc;
@@ -38,32 +38,47 @@ class BffControllerTest {
     private OAuth2AuthorizedClientManager authorizedClientManager;
 
     @Test
-    void reportsServerTokenCustodyWithoutReturningTokens() throws Exception {
+    void reportsServerSideTokensWithoutReturningTheirValues() throws Exception {
         OAuth2AuthorizedClient client = mock(OAuth2AuthorizedClient.class);
         when(client.getAccessToken()).thenReturn(mock(OAuth2AccessToken.class));
         when(client.getRefreshToken()).thenReturn(mock(OAuth2RefreshToken.class));
         when(authorizedClientService.loadAuthorizedClient("keycloak", "test-subject"))
             .thenReturn(client);
 
-        mockMvc.perform(get("/bff/token-boundary").with(oidcLogin()
+        mockMvc.perform(get("/token/boundary").with(oidcLogin()
                 .idToken(token -> token.subject("test-subject"))))
             .andExpect(status().isOk())
             .andExpect(header().string("Cache-Control", "no-store"))
-            .andExpect(jsonPath("$.accessTokenStoredOnServer").value(true))
-            .andExpect(jsonPath("$.refreshTokenStoredOnServer").value(true))
-            .andExpect(jsonPath("$.browserTokenCount").value(0))
-            .andExpect(jsonPath("$.csrfProtectionEnabled").value(false))
+            .andExpect(jsonPath("$.accessTokenStored").value(true))
+            .andExpect(jsonPath("$.refreshTokenStored").value(true))
+            .andExpect(jsonPath("$.browserReceivesRefreshToken").value(false))
             .andExpect(jsonPath("$.access_token").doesNotExist())
             .andExpect(jsonPath("$.refresh_token").doesNotExist());
     }
 
     @Test
-    void demonstratesStateChangeWithoutCsrfProtection() throws Exception {
-        mockMvc.perform(post("/bff/api/preferences")
-                .param("theme", "attacker")
-                .with(oidcLogin().idToken(token -> token.subject("test-subject"))))
+    void handsOffAccessTokenOnlyAndMarksResponseNoStore() throws Exception {
+        Instant issuedAt = Instant.parse("2026-07-25T00:00:00Z");
+        OAuth2AccessToken accessToken = new OAuth2AccessToken(
+            OAuth2AccessToken.TokenType.BEARER,
+            "test-access-token",
+            issuedAt,
+            issuedAt.plusSeconds(300)
+        );
+        OAuth2AuthorizedClient client = mock(OAuth2AuthorizedClient.class);
+        when(client.getAccessToken()).thenReturn(accessToken);
+        when(authorizedClientManager.authorize(any(OAuth2AuthorizeRequest.class)))
+            .thenReturn(client);
+
+        mockMvc.perform(get("/token/access").with(oidcLogin()
+                .idToken(token -> token.subject("test-subject"))))
             .andExpect(status().isOk())
-            .andExpect(jsonPath("$.updated").value(true))
-            .andExpect(jsonPath("$.theme").value("attacker"));
+            .andExpect(header().string("Cache-Control", "no-store"))
+            .andExpect(header().string("Pragma", "no-cache"))
+            .andExpect(jsonPath("$.length()").value(3))
+            .andExpect(jsonPath("$.access_token").value("test-access-token"))
+            .andExpect(jsonPath("$.token_type").value("Bearer"))
+            .andExpect(jsonPath("$.expires_at").value("2026-07-25T00:05:00Z"))
+            .andExpect(jsonPath("$.refresh_token").doesNotExist());
     }
 }