feat(ap3): add oauth2Login session BFF

.env.example

@@ -0,0 +1,17 @@
+# Copy this file to .env and replace every change-me value.
+KC_BOOTSTRAP_ADMIN_USERNAME=admin
+KC_BOOTSTRAP_ADMIN_PASSWORD=change-me-admin-password
+
+POSTGRES_DB=keycloak
+POSTGRES_USER=keycloak
+POSTGRES_PASSWORD=change-me-postgres-password
+
+# Keycloak resolves these placeholders while importing the realm.
+TOKEN_MEDIATING_CLIENT_SECRET=change-me-token-mediating-client-secret
+BFF_CLIENT_SECRET=change-me-bff-client-secret
+EDGE_PROXY_CLIENT_SECRET=change-me-edge-proxy-client-secret
+ADMIN_USER_PASSWORD=change-me-admin-user-password
+REGULAR_USER_PASSWORD=change-me-regular-user-password
+
+# Port 80 is the single-EC2 target. 8088 avoids common local port conflicts.
+NGINX_PORT=8088

.gitignore

@@ -0,0 +1,10 @@
+.env
+.idea/
+.vscode/
+*.iml
+
+backend/target/
+bff/target/
+**/node_modules/
+frontend/dist/
+build/

README.md

@@ -1,2 +1,112 @@
-# keycloak-pattern
+# Keycloak Authentication Patterns
 
+Keycloak을 중심으로 네 가지 브라우저 인증 통합 패턴을 같은 로컬
+인프라에서 비교하는 학습 프로젝트입니다.
+
+- AP1: Browser-based OAuth Client (SPA direct + Resource Server)
+- AP2: Token-Mediating Backend
+- AP3: Backend-for-Frontend (BFF)
+- AP4: Edge forward-auth
+
+현재 `develop`의 공통 baseline은 Keycloak, PostgreSQL, Spring Boot API,
+nginx를 Docker Compose로 실행하는 토대입니다. 패턴별 구현은 이 baseline
+위에서 별도 브랜치로 진행합니다.
+
+## 요구 사항
+
+- Docker Engine
+- Docker Compose
+- `curl`
+
+로컬 Java나 Maven은 필요하지 않습니다. Spring Boot 빌드와 테스트는 Maven
+컨테이너에서 수행합니다.
+
+## 시작
+
+```bash
+cp .env.example .env
+docker compose up --build -d
+./scripts/verify-stack.sh
+```
+
+기본 주소는 다음과 같습니다.
+
+| 구성 요소 | 주소 |
+|---|---|
+| Keycloak | <http://localhost:8080> |
+| Spring Boot API | <http://localhost:8081> |
+| nginx | <http://localhost:8088> |
+
+host의 80번 포트를 쓸 수 있는 single-EC2 환경에서는 `.env`의
+`NGINX_PORT=80`으로 변경할 수 있습니다.
+
+## 상태 확인
+
+```bash
+docker compose ps
+docker compose logs -f keycloak
+curl http://localhost:8088/api/public
+curl -i http://localhost:8088/api/me
+```
+
+`/api/public`은 `200`, 인증 정보가 없는 `/api/me`는 `401`이 정상입니다.
+
+## 환경 초기화
+
+PostgreSQL과 Keycloak data volume을 제거하고 realm import부터 다시
+검증하려면 다음 한 줄을 사용합니다.
+
+```bash
+docker compose down -v && docker compose up --build -d
+```
+
+`start-dev`와 로컬 HTTP 설정은 학습 전용입니다. 운영 환경에서는
+optimized Keycloak image, HTTPS, 엄격한 hostname 및 외부 secret store를
+사용해야 합니다.
+
+## Realm baseline
+
+`keycloak/import/keycloak-patterns-realm.json`은 시작 시 자동 import됩니다.
+하나의 `keycloak-patterns` realm 안에서 패턴마다 client를 분리합니다.
+
+| Client | 유형 | 패턴 |
+|---|---|---|
+| `spa-public` | public + PKCE S256 | AP1 |
+| `token-mediating-confidential` | confidential | AP2 |
+| `bff-confidential` | confidential | AP3 |
+| `edge-proxy` | confidential | AP4 |
+
+confidential client secret과 테스트 사용자 password는 JSON에 평문으로
+저장하지 않습니다. JSON에는 `${ENVIRONMENT_VARIABLE}` placeholder만
+커밋하고, Keycloak 26.7.0이 import 시 `.env` 값을 주입합니다.
+
+```bash
+python3 scripts/validate-realm.py
+docker compose down -v
+docker compose up -d --wait
+./scripts/verify-realm.sh
+```
+
+실행 중인 DB에서 CLI realm export를 재현하려면 다음 명령을 사용합니다.
+Keycloak을 잠시 중지하고 export한 뒤 자동으로 다시 올립니다.
+
+```bash
+./scripts/export-realm.sh
+```
+
+runtime export에는 실제 client secret과 credential hash가 포함될 수 있어
+gitignored `build/keycloak-export/`에 권한 `0600`으로만 저장됩니다.
+
+## AP3: Backend-for-Frontend
+
+`develop-keycloak-pattern3`의 Spring BFF는 `http://localhost:8083`에서
+실행됩니다. 브라우저에는 HttpOnly session cookie만 두고 access/refresh
+token은 BFF가 서버에 보관합니다. `/bff/api/me`는 BFF가 보유 access
+token을 붙여 Resource Server로 proxy합니다.
+
+```bash
+./scripts/verify-pattern3.sh
+```
+
+자세한 경계와 session 저장소 trade-off는
+[`docs/ap3-bff-boundary.md`](docs/ap3-bff-boundary.md)를 참고하세요.

backend/.dockerignore

@@ -0,0 +1 @@
+target/

backend/Dockerfile

@@ -0,0 +1,19 @@
+FROM maven:3.9.11-eclipse-temurin-21-alpine AS build
+
+WORKDIR /workspace
+COPY pom.xml .
+RUN mvn --batch-mode dependency:go-offline
+
+COPY src src
+RUN mvn --batch-mode verify
+
+FROM eclipse-temurin:21-jre-alpine
+
+RUN addgroup -S spring && adduser -S spring -G spring
+USER spring:spring
+
+WORKDIR /app
+COPY --from=build /workspace/target/keycloak-pattern-api.jar app.jar
+
+EXPOSE 8081
+ENTRYPOINT ["java", "-jar", "/app/app.jar"]

backend/pom.xml

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.5.16</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>com.example</groupId>
+    <artifactId>keycloak-pattern-api</artifactId>
+    <version>0.0.1-SNAPSHOT</version>
+    <name>keycloak-pattern-api</name>
+    <description>Shared resource API for the Keycloak authentication patterns</description>
+
+    <properties>
+        <java.version>21</java.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.security</groupId>
+            <artifactId>spring-security-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <finalName>keycloak-pattern-api</finalName>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>

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

@@ -0,0 +1,30 @@
+package com.example.keycloakpattern;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.security.oauth2.jwt.Jwt;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api")
+public class ApiController {
+
+    @GetMapping("/public")
+    public Map<String, String> publicEndpoint() {
+        return Map.of("status", "ok", "service", "keycloak-pattern-api");
+    }
+
+    @GetMapping("/me")
+    public Map<String, Object> currentUser(@AuthenticationPrincipal Jwt jwt) {
+        Map<String, Object> response = new LinkedHashMap<>();
+        response.put("subject", jwt.getSubject());
+        response.put("username", jwt.getClaimAsString("preferred_username"));
+        response.put("issuer", jwt.getIssuer());
+        response.put("audience", jwt.getAudience());
+        return response;
+    }
+}

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

@@ -0,0 +1,29 @@
+package com.example.keycloakpattern;
+
+import org.springframework.security.oauth2.core.OAuth2Error;
+import org.springframework.security.oauth2.core.OAuth2TokenValidator;
+import org.springframework.security.oauth2.core.OAuth2TokenValidatorResult;
+import org.springframework.security.oauth2.jwt.Jwt;
+
+final class AudienceValidator implements OAuth2TokenValidator<Jwt> {
+
+    private static final OAuth2Error MISSING_AUDIENCE = new OAuth2Error(
+        "invalid_token",
+        "The required resource audience is missing",
+        null
+    );
+
+    private final String expectedAudience;
+
+    AudienceValidator(String expectedAudience) {
+        this.expectedAudience = expectedAudience;
+    }
+
+    @Override
+    public OAuth2TokenValidatorResult validate(Jwt jwt) {
+        if (jwt.getAudience().contains(expectedAudience)) {
+            return OAuth2TokenValidatorResult.success();
+        }
+        return OAuth2TokenValidatorResult.failure(MISSING_AUDIENCE);
+    }
+}

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

@@ -0,0 +1,31 @@
+package com.example.keycloakpattern;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.oauth2.core.DelegatingOAuth2TokenValidator;
+import org.springframework.security.oauth2.core.OAuth2TokenValidator;
+import org.springframework.security.oauth2.jwt.Jwt;
+import org.springframework.security.oauth2.jwt.JwtDecoder;
+import org.springframework.security.oauth2.jwt.JwtValidators;
+import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
+
+@Configuration
+public class JwtDecoderConfig {
+
+    @Bean
+    JwtDecoder jwtDecoder(
+        @Value("${spring.security.oauth2.resourceserver.jwt.issuer-uri}") String issuer,
+        @Value("${spring.security.oauth2.resourceserver.jwt.jwk-set-uri}") String jwkSetUri,
+        @Value("${security.expected-audience}") String expectedAudience
+    ) {
+        NimbusJwtDecoder decoder = NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
+        OAuth2TokenValidator<Jwt> issuerAndTimestamp =
+            JwtValidators.createDefaultWithIssuer(issuer);
+        OAuth2TokenValidator<Jwt> audience = new AudienceValidator(expectedAudience);
+        decoder.setJwtValidator(
+            new DelegatingOAuth2TokenValidator<>(issuerAndTimestamp, audience)
+        );
+        return decoder;
+    }
+}

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

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

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

@@ -0,0 +1,27 @@
+package com.example.keycloakpattern;
+
+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;
+
+@Configuration
+public class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain apiSecurity(HttpSecurity http) throws Exception {
+        return http
+            .csrf(csrf -> csrf.disable())
+            .sessionManagement(session ->
+                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(authorize -> authorize
+                .requestMatchers("/actuator/health", "/actuator/health/**", "/api/public")
+                .permitAll()
+                .anyRequest()
+                .authenticated())
+            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
+            .build();
+    }
+}

backend/src/main/resources/application.yml

@@ -0,0 +1,25 @@
+server:
+  port: ${SERVER_PORT:8081}
+
+spring:
+  application:
+    name: keycloak-pattern-api
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: ${SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI:http://localhost:8080/realms/keycloak-patterns}
+          jwk-set-uri: ${SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI:http://localhost:8080/realms/keycloak-patterns/protocol/openid-connect/certs}
+
+security:
+  expected-audience: ${SECURITY_EXPECTED_AUDIENCE:keycloak-pattern-api}
+
+management:
+  endpoint:
+    health:
+      probes:
+        enabled: true
+  endpoints:
+    web:
+      exposure:
+        include: health,info

backend/src/test/java/com/example/keycloakpattern/ApiSecurityTest.java

@@ -0,0 +1,43 @@
+package com.example.keycloakpattern;
+
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.jwt;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+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.test.web.servlet.MockMvc;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+class ApiSecurityTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Test
+    void publicEndpointDoesNotRequireAuthentication() throws Exception {
+        mockMvc.perform(get("/api/public"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.status").value("ok"));
+    }
+
+    @Test
+    void protectedEndpointRejectsAnonymousRequests() throws Exception {
+        mockMvc.perform(get("/api/me"))
+            .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    void protectedEndpointAcceptsJwtAuthentication() throws Exception {
+        mockMvc.perform(get("/api/me").with(jwt().jwt(token -> token
+                .subject("test-subject")
+                .claim("preferred_username", "regular-user"))))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.subject").value("test-subject"))
+            .andExpect(jsonPath("$.username").value("regular-user"));
+    }
+}

backend/src/test/java/com/example/keycloakpattern/AudienceValidatorTest.java

@@ -0,0 +1,49 @@
+package com.example.keycloakpattern;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.security.oauth2.core.OAuth2TokenValidatorResult;
+import org.springframework.security.oauth2.jwt.Jwt;
+
+class AudienceValidatorTest {
+
+    private final AudienceValidator validator =
+        new AudienceValidator("keycloak-pattern-api");
+
+    @Test
+    void acceptsRequiredAudience() {
+        OAuth2TokenValidatorResult result = validator.validate(jwtWithAudience(
+            List.of("account", "keycloak-pattern-api")
+        ));
+
+        assertThat(result.hasErrors()).isFalse();
+    }
+
+    @Test
+    void rejectsForeignAudience() {
+        OAuth2TokenValidatorResult result = validator.validate(jwtWithAudience(
+            List.of("another-resource")
+        ));
+
+        assertThat(result.hasErrors()).isTrue();
+        assertThat(result.getErrors())
+            .extracting(error -> error.getErrorCode())
+            .containsExactly("invalid_token");
+    }
+
+    private Jwt jwtWithAudience(List<String> audience) {
+        Instant now = Instant.now();
+        return new Jwt(
+            "test-token",
+            now,
+            now.plusSeconds(300),
+            Map.of("alg", "none"),
+            Map.of("sub", "test-subject", "aud", audience)
+        );
+    }
+}

bff/.dockerignore

@@ -0,0 +1 @@
+target/

bff/Dockerfile

@@ -0,0 +1,14 @@
+FROM maven:3.9.11-eclipse-temurin-21-alpine AS build
+WORKDIR /workspace
+COPY pom.xml .
+RUN mvn --batch-mode dependency:go-offline
+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
+USER spring:spring
+EXPOSE 8083
+ENTRYPOINT ["java", "-jar", "/app/app.jar"]

bff/pom.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.5.16</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>com.example</groupId>
+    <artifactId>keycloak-bff</artifactId>
+    <version>0.0.1-SNAPSHOT</version>
+    <name>keycloak-bff</name>
+
+    <properties>
+        <java.version>21</java.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-oauth2-client</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.security</groupId>
+            <artifactId>spring-security-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <finalName>keycloak-bff</finalName>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>

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

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

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

@@ -0,0 +1,112 @@
+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/java/com/example/keycloakpattern/bff/SecurityConfig.java

@@ -0,0 +1,73 @@
+package com.example.keycloakpattern.bff;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.oauth2.client.AuthorizedClientServiceOAuth2AuthorizedClientManager;
+import org.springframework.security.oauth2.client.OAuth2AuthorizedClientManager;
+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()
+        );
+
+        return http
+            .csrf(csrf -> csrf.disable())
+            .authorizeHttpRequests(authorize -> authorize
+                .requestMatchers(
+                    "/",
+                    "/index.html",
+                    "/app.js",
+                    "/favicon.ico",
+                    "/actuator/health",
+                    "/actuator/health/**"
+                )
+                .permitAll()
+                .anyRequest()
+                .authenticated())
+            .oauth2Login(oauth2 -> oauth2
+                .authorizationEndpoint(endpoint -> endpoint
+                    .authorizationRequestResolver(authorizationRequestResolver))
+                .defaultSuccessUrl("/", true))
+            .build();
+    }
+
+    @Bean
+    OAuth2AuthorizedClientManager authorizedClientManager(
+        ClientRegistrationRepository clientRegistrationRepository,
+        OAuth2AuthorizedClientService authorizedClientService
+    ) {
+        OAuth2AuthorizedClientProvider authorizedClientProvider =
+            OAuth2AuthorizedClientProviderBuilder.builder()
+                .authorizationCode()
+                .refreshToken()
+                .build();
+
+        AuthorizedClientServiceOAuth2AuthorizedClientManager manager =
+            new AuthorizedClientServiceOAuth2AuthorizedClientManager(
+                clientRegistrationRepository,
+                authorizedClientService
+            );
+        manager.setAuthorizedClientProvider(authorizedClientProvider);
+        return manager;
+    }
+}

bff/src/main/resources/application.yml

@@ -0,0 +1,46 @@
+server:
+  port: ${SERVER_PORT:8083}
+  servlet:
+    session:
+      cookie:
+        name: AP3_SESSION
+        http-only: true
+
+spring:
+  application:
+    name: keycloak-bff
+  security:
+    oauth2:
+      client:
+        registration:
+          keycloak:
+            provider: keycloak
+            client-id: bff-confidential
+            client-secret: ${KEYCLOAK_CLIENT_SECRET}
+            client-authentication-method: client_secret_basic
+            authorization-grant-type: authorization_code
+            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
+            scope:
+              - openid
+              - profile
+              - email
+        provider:
+          keycloak:
+            authorization-uri: http://localhost:8080/realms/keycloak-patterns/protocol/openid-connect/auth
+            token-uri: http://keycloak:8080/realms/keycloak-patterns/protocol/openid-connect/token
+            jwk-set-uri: http://keycloak:8080/realms/keycloak-patterns/protocol/openid-connect/certs
+            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:
+      probes:
+        enabled: true
+  endpoints:
+    web:
+      exposure:
+        include: health,info

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

@@ -0,0 +1,39 @@
+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

@@ -0,0 +1,31 @@
+<!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>

bff/src/test/java/com/example/keycloakpattern/bff/BffControllerTest.java

@@ -0,0 +1,69 @@
+package com.example.keycloakpattern.bff;
+
+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 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.OAuth2AuthorizedClient;
+import org.springframework.security.oauth2.client.OAuth2AuthorizedClientManager;
+import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
+import org.springframework.security.oauth2.core.OAuth2AccessToken;
+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"
+})
+@AutoConfigureMockMvc
+class BffControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockitoBean
+    private OAuth2AuthorizedClientService authorizedClientService;
+
+    @MockitoBean
+    private OAuth2AuthorizedClientManager authorizedClientManager;
+
+    @Test
+    void reportsServerTokenCustodyWithoutReturningTokens() 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()
+                .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("$.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"))))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.updated").value(true))
+            .andExpect(jsonPath("$.theme").value("attacker"));
+    }
+}

docker-compose.yml

@@ -0,0 +1,140 @@
+name: keycloak-patterns
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-keycloak}
+      POSTGRES_USER: ${POSTGRES_USER:-keycloak}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?copy .env.example to .env and set POSTGRES_PASSWORD}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - pg_isready -U "$${POSTGRES_USER}" -d "$${POSTGRES_DB}"
+      interval: 5s
+      timeout: 5s
+      retries: 12
+    networks:
+      - keycloak-net
+    restart: unless-stopped
+
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.7.0
+    command:
+      - start-dev
+      - --import-realm
+    environment:
+      KC_DB: postgres
+      KC_DB_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB:-keycloak}
+      KC_DB_USERNAME: ${POSTGRES_USER:-keycloak}
+      KC_DB_PASSWORD: ${POSTGRES_PASSWORD:?copy .env.example to .env and set POSTGRES_PASSWORD}
+      KC_HOSTNAME: http://localhost:8080
+      KC_HTTP_ENABLED: "true"
+      KC_HEALTH_ENABLED: "true"
+      KC_BOOTSTRAP_ADMIN_USERNAME: ${KC_BOOTSTRAP_ADMIN_USERNAME:?set KC_BOOTSTRAP_ADMIN_USERNAME in .env}
+      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_BOOTSTRAP_ADMIN_PASSWORD:?set KC_BOOTSTRAP_ADMIN_PASSWORD in .env}
+      TOKEN_MEDIATING_CLIENT_SECRET: ${TOKEN_MEDIATING_CLIENT_SECRET:?set TOKEN_MEDIATING_CLIENT_SECRET in .env}
+      BFF_CLIENT_SECRET: ${BFF_CLIENT_SECRET:?set BFF_CLIENT_SECRET in .env}
+      EDGE_PROXY_CLIENT_SECRET: ${EDGE_PROXY_CLIENT_SECRET:?set EDGE_PROXY_CLIENT_SECRET in .env}
+      ADMIN_USER_PASSWORD: ${ADMIN_USER_PASSWORD:?set ADMIN_USER_PASSWORD in .env}
+      REGULAR_USER_PASSWORD: ${REGULAR_USER_PASSWORD:?set REGULAR_USER_PASSWORD in .env}
+    ports:
+      - "127.0.0.1:8080:8080"
+    volumes:
+      - keycloak_data:/opt/keycloak/data
+      - ./keycloak/import:/opt/keycloak/data/import:ro
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test:
+        - CMD
+        - bash
+        - -c
+        - "{ printf 'HEAD /health/ready HTTP/1.0\r\n\r\n' >&0; grep 'HTTP/1.0 200'; } 0<>/dev/tcp/localhost/9000"
+      interval: 10s
+      timeout: 5s
+      retries: 18
+      start_period: 60s
+    networks:
+      - keycloak-net
+    restart: unless-stopped
+
+  app:
+    build:
+      context: ./backend
+    environment:
+      SERVER_PORT: "8081"
+      SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI: http://localhost:8080/realms/keycloak-patterns
+      SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI: http://keycloak:8080/realms/keycloak-patterns/protocol/openid-connect/certs
+    ports:
+      - "127.0.0.1:8081:8081"
+    depends_on:
+      keycloak:
+        condition: service_healthy
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - wget -q -O - http://127.0.0.1:8081/actuator/health | grep -q '"status":"UP"'
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+    networks:
+      - keycloak-net
+    restart: unless-stopped
+
+  bff:
+    build:
+      context: ./bff
+    environment:
+      SERVER_PORT: "8083"
+      KEYCLOAK_CLIENT_SECRET: ${BFF_CLIENT_SECRET:?set BFF_CLIENT_SECRET in .env}
+      RESOURCE_API_BASE_URL: http://app:8081
+    ports:
+      - "127.0.0.1:8083:8083"
+    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"'
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+    networks:
+      - keycloak-net
+    restart: unless-stopped
+
+  nginx:
+    build:
+      context: ./frontend
+    ports:
+      - "127.0.0.1:${NGINX_PORT:-8088}:80"
+    depends_on:
+      app:
+        condition: service_healthy
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - wget -q -O - http://127.0.0.1/health | grep -q '^ok$'
+      interval: 10s
+      timeout: 5s
+      retries: 12
+    networks:
+      - keycloak-net
+    restart: unless-stopped
+
+volumes:
+  keycloak_data:
+  postgres_data:
+
+networks:
+  keycloak-net:
+    driver: bridge

docs/ap3-bff-boundary.md

@@ -0,0 +1,28 @@
+# 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-lock.json

@@ -0,0 +1,28 @@
+{
+  "name": "keycloak-pattern-e2e",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "keycloak-pattern-e2e",
+      "version": "1.0.0",
+      "devDependencies": {
+        "playwright-core": "1.62.0"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.62.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.62.0.tgz",
+      "integrity": "sha512-nsNRyq0r2zsG8AcRHWknc9QRA5XCueC7gWMrs+Gx2tlZn9hcl8zudfh00lhJPY1DE7NmZ6bDsT9g2yey8mXljA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    }
+  }
+}

e2e/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "keycloak-pattern-e2e",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "test:pattern3": "node pattern3.mjs"
+  },
+  "devDependencies": {
+    "playwright-core": "1.62.0"
+  }
+}

e2e/pattern3.mjs

@@ -0,0 +1,140 @@
+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();
+}

frontend/Dockerfile

@@ -0,0 +1,4 @@
+FROM nginx:1.29-alpine
+
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY index.html /usr/share/nginx/html/index.html

frontend/index.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Keycloak Authentication Patterns</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      font-family: system-ui, sans-serif;
+    }
+    body {
+      max-width: 48rem;
+      margin: 8vh auto;
+      padding: 0 1.5rem;
+      line-height: 1.6;
+    }
+    code {
+      padding: 0.15rem 0.35rem;
+      border-radius: 0.25rem;
+      background: color-mix(in srgb, CanvasText 10%, Canvas);
+    }
+  </style>
+</head>
+<body>
+  <h1>Keycloak Authentication Patterns</h1>
+  <p>공통 Docker Compose baseline이 실행 중입니다.</p>
+  <p>
+    공개 API는 <code>/api/public</code>, 보호 API는
+    <code>/api/me</code>에서 확인할 수 있습니다.
+  </p>
+</body>
+</html>

frontend/nginx.conf

@@ -0,0 +1,26 @@
+server {
+    listen 80;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location = /health {
+        access_log off;
+        default_type text/plain;
+        return 200 "ok\n";
+    }
+
+    location /api/ {
+        proxy_pass http://app:8081;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

keycloak/import/.gitkeep

@@ -0,0 +1 @@
+

keycloak/import/keycloak-patterns-realm.json

@@ -0,0 +1,181 @@
+{
+  "realm": "keycloak-patterns",
+  "displayName": "Keycloak Authentication Patterns",
+  "enabled": true,
+  "sslRequired": "external",
+  "registrationAllowed": false,
+  "resetPasswordAllowed": false,
+  "editUsernameAllowed": false,
+  "loginWithEmailAllowed": true,
+  "duplicateEmailsAllowed": false,
+  "bruteForceProtected": true,
+  "accessTokenLifespan": 300,
+  "ssoSessionIdleTimeout": 1800,
+  "ssoSessionMaxLifespan": 36000,
+  "offlineSessionIdleTimeout": 2592000,
+  "revokeRefreshToken": true,
+  "refreshTokenMaxReuse": 0,
+  "roles": {
+    "realm": [
+      {
+        "name": "admin-role",
+        "description": "Administrative role used by authorization examples"
+      },
+      {
+        "name": "user-role",
+        "description": "Regular authenticated user role"
+      }
+    ]
+  },
+  "clients": [
+    {
+      "clientId": "spa-public",
+      "name": "AP1 SPA Public Client",
+      "description": "Browser-based OAuth client using Authorization Code and PKCE",
+      "enabled": true,
+      "protocol": "openid-connect",
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "implicitFlowEnabled": false,
+      "directAccessGrantsEnabled": false,
+      "serviceAccountsEnabled": false,
+      "frontchannelLogout": true,
+      "redirectUris": [
+        "http://localhost:8088/*",
+        "http://127.0.0.1:8088/*"
+      ],
+      "webOrigins": [
+        "http://localhost:8088",
+        "http://127.0.0.1:8088"
+      ],
+      "attributes": {
+        "pkce.code.challenge.method": "S256",
+        "post.logout.redirect.uris": "http://localhost:8088/*##http://127.0.0.1:8088/*"
+      }
+    },
+    {
+      "clientId": "token-mediating-confidential",
+      "name": "AP2 Token-Mediating Backend",
+      "description": "Confidential backend that keeps refresh tokens server-side",
+      "enabled": true,
+      "protocol": "openid-connect",
+      "publicClient": false,
+      "clientAuthenticatorType": "client-secret",
+      "secret": "${TOKEN_MEDIATING_CLIENT_SECRET}",
+      "standardFlowEnabled": true,
+      "implicitFlowEnabled": false,
+      "directAccessGrantsEnabled": false,
+      "serviceAccountsEnabled": false,
+      "frontchannelLogout": true,
+      "redirectUris": [
+        "http://localhost:8082/login/oauth2/code/keycloak"
+      ],
+      "webOrigins": [
+        "http://localhost:8082"
+      ],
+      "attributes": {
+        "post.logout.redirect.uris": "http://localhost:8082/*"
+      }
+    },
+    {
+      "clientId": "bff-confidential",
+      "name": "AP3 Backend-for-Frontend",
+      "description": "Confidential BFF that keeps all OAuth tokens server-side",
+      "enabled": true,
+      "protocol": "openid-connect",
+      "publicClient": false,
+      "clientAuthenticatorType": "client-secret",
+      "secret": "${BFF_CLIENT_SECRET}",
+      "standardFlowEnabled": true,
+      "implicitFlowEnabled": false,
+      "directAccessGrantsEnabled": false,
+      "serviceAccountsEnabled": false,
+      "frontchannelLogout": true,
+      "redirectUris": [
+        "http://localhost:8083/login/oauth2/code/keycloak"
+      ],
+      "webOrigins": [
+        "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",
+      "name": "AP4 Edge Forward Auth",
+      "description": "Confidential oauth2-proxy OIDC client",
+      "enabled": true,
+      "protocol": "openid-connect",
+      "publicClient": false,
+      "clientAuthenticatorType": "client-secret",
+      "secret": "${EDGE_PROXY_CLIENT_SECRET}",
+      "standardFlowEnabled": true,
+      "implicitFlowEnabled": false,
+      "directAccessGrantsEnabled": false,
+      "serviceAccountsEnabled": false,
+      "frontchannelLogout": true,
+      "redirectUris": [
+        "http://localhost:4180/oauth2/callback"
+      ],
+      "webOrigins": [],
+      "attributes": {
+        "post.logout.redirect.uris": "http://localhost:8088/*"
+      }
+    }
+  ],
+  "users": [
+    {
+      "username": "admin-user",
+      "enabled": true,
+      "email": "admin-user@example.test",
+      "emailVerified": true,
+      "firstName": "Admin",
+      "lastName": "User",
+      "realmRoles": [
+        "admin-role"
+      ],
+      "credentials": [
+        {
+          "type": "password",
+          "value": "${ADMIN_USER_PASSWORD}",
+          "temporary": false
+        }
+      ]
+    },
+    {
+      "username": "regular-user",
+      "enabled": true,
+      "email": "regular-user@example.test",
+      "emailVerified": true,
+      "firstName": "Regular",
+      "lastName": "User",
+      "realmRoles": [
+        "user-role"
+      ],
+      "credentials": [
+        {
+          "type": "password",
+          "value": "${REGULAR_USER_PASSWORD}",
+          "temporary": false
+        }
+      ]
+    }
+  ]
+}

scripts/export-realm.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env sh
+set -eu
+
+compose_file=${COMPOSE_FILE:-docker-compose.yml}
+output_dir=${REALM_EXPORT_DIR:-"$(pwd)/build/keycloak-export"}
+output_file="$output_dir/keycloak-patterns-realm.json"
+
+mkdir -p "$output_dir"
+
+restart_keycloak() {
+  trap - EXIT INT TERM
+  docker compose -f "$compose_file" up -d --wait >/dev/null
+}
+trap restart_keycloak EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+docker compose -f "$compose_file" stop keycloak >/dev/null
+docker compose -f "$compose_file" run --rm --no-deps \
+  --volume "$output_dir:/opt/keycloak/data/export" \
+  keycloak \
+    export \
+    --realm keycloak-patterns \
+    --file /opt/keycloak/data/export/keycloak-patterns-realm.json \
+    --users same_file
+
+chmod 600 "$output_file"
+python3 scripts/validate-realm.py --runtime "$output_file"
+
+echo "runtime realm export written to $output_file"

scripts/validate-realm.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Validate the committed realm template or a runtime Keycloak CLI export."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+REALM_NAME = "keycloak-patterns"
+PUBLIC_CLIENT = "spa-public"
+CONFIDENTIAL_CLIENTS = {
+    "token-mediating-confidential": "${TOKEN_MEDIATING_CLIENT_SECRET}",
+    "bff-confidential": "${BFF_CLIENT_SECRET}",
+    "edge-proxy": "${EDGE_PROXY_CLIENT_SECRET}",
+}
+EXPECTED_ROLES = {"admin-role", "user-role"}
+EXPECTED_USERS = {"admin-user", "regular-user"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "realm_file",
+        nargs="?",
+        type=Path,
+        default=Path("keycloak/import/keycloak-patterns-realm.json"),
+    )
+    parser.add_argument(
+        "--runtime",
+        action="store_true",
+        help="validate an expanded CLI export instead of the committed template",
+    )
+    return parser.parse_args()
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise SystemExit(f"realm validation failed: {message}")
+
+
+def indexed(items: list[dict[str, Any]], key: str) -> dict[str, dict[str, Any]]:
+    return {str(item[key]): item for item in items}
+
+
+def validate(path: Path, runtime: bool) -> None:
+    document = json.loads(path.read_text(encoding="utf-8"))
+    require(document.get("realm") == REALM_NAME, f"realm must be {REALM_NAME}")
+    require(document.get("enabled") is True, "realm must be enabled")
+    require(document.get("accessTokenLifespan") == 300, "access token TTL must be 300s")
+    require(document.get("revokeRefreshToken") is True, "refresh token rotation must be enabled")
+    require(document.get("refreshTokenMaxReuse") == 0, "refresh token max reuse must be 0")
+
+    clients = indexed(document.get("clients", []), "clientId")
+    expected_client_ids = {PUBLIC_CLIENT, *CONFIDENTIAL_CLIENTS}
+    require(expected_client_ids <= clients.keys(), "all four pattern clients must exist")
+    if not runtime:
+        require(clients.keys() == expected_client_ids, "template must declare exactly four clients")
+
+    spa = clients[PUBLIC_CLIENT]
+    require(spa.get("publicClient") is True, "spa-public must be a public client")
+    require("secret" not in spa, "spa-public must not have a client secret")
+    require(spa.get("standardFlowEnabled") is True, "spa-public standard flow must be enabled")
+    require(
+        spa.get("directAccessGrantsEnabled") is False,
+        "spa-public direct access grants must be disabled",
+    )
+    require(
+        spa.get("attributes", {}).get("pkce.code.challenge.method") == "S256",
+        "spa-public must enforce PKCE S256",
+    )
+
+    for client_id, placeholder in CONFIDENTIAL_CLIENTS.items():
+        client = clients[client_id]
+        require(client.get("publicClient") is False, f"{client_id} must be confidential")
+        require(
+            client.get("clientAuthenticatorType") == "client-secret",
+            f"{client_id} must use client-secret authentication",
+        )
+        secret = client.get("secret")
+        if runtime:
+            require(isinstance(secret, str) and len(secret) >= 16, f"{client_id} secret missing")
+            require(not secret.startswith("${"), f"{client_id} placeholder was not resolved")
+        else:
+            require(secret == placeholder, f"{client_id} must use an env placeholder")
+
+    roles = {
+        role["name"]
+        for role in document.get("roles", {}).get("realm", [])
+        if "name" in role
+    }
+    require(EXPECTED_ROLES <= roles, "admin-role and user-role must exist")
+
+    users = indexed(document.get("users", []), "username")
+    require(EXPECTED_USERS <= users.keys(), "both baseline users must exist")
+    if not runtime:
+        expected_passwords = {
+            "admin-user": "${ADMIN_USER_PASSWORD}",
+            "regular-user": "${REGULAR_USER_PASSWORD}",
+        }
+        for username, placeholder in expected_passwords.items():
+            credentials = users[username].get("credentials", [])
+            require(len(credentials) == 1, f"{username} must have one initial credential")
+            require(
+                credentials[0].get("value") == placeholder,
+                f"{username} password must use an env placeholder",
+            )
+
+    print(
+        f"realm validated: {REALM_NAME}, four pattern clients, "
+        f"{len(EXPECTED_ROLES)} roles, {len(EXPECTED_USERS)} users"
+    )
+
+
+if __name__ == "__main__":
+    arguments = parse_args()
+    validate(arguments.realm_file, arguments.runtime)

scripts/verify-pattern3.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ ! -f .env ]; then
+  echo "missing .env; copy .env.example and set development values" >&2
+  exit 1
+fi
+
+set -a
+. ./.env
+set +a
+
+docker compose down --volumes --remove-orphans
+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
+
+echo "AP3 BFF session and CSRF behavior verified"

scripts/verify-realm.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env sh
+set -eu
+
+compose_file=${COMPOSE_FILE:-docker-compose.yml}
+
+python3 scripts/validate-realm.py
+./scripts/verify-stack.sh
+
+curl --fail --silent --show-error --output /dev/null \
+  "http://localhost:8080/realms/keycloak-patterns/.well-known/openid-configuration"
+
+docker compose -f "$compose_file" exec -T keycloak sh -ec '
+  kcadm=/opt/keycloak/bin/kcadm.sh
+  "$kcadm" config credentials \
+    --server http://localhost:8080 \
+    --realm master \
+    --user "$KC_BOOTSTRAP_ADMIN_USERNAME" \
+    --password "$KC_BOOTSTRAP_ADMIN_PASSWORD" >/dev/null
+
+  clients=$("$kcadm" get clients -r keycloak-patterns --fields clientId)
+  for client in \
+    spa-public \
+    token-mediating-confidential \
+    bff-confidential \
+    edge-proxy
+  do
+    printf "%s" "$clients" | grep -q "\"$client\""
+  done
+
+  users=$("$kcadm" get users -r keycloak-patterns --fields username)
+  printf "%s" "$users" | grep -q "\"admin-user\""
+  printf "%s" "$users" | grep -q "\"regular-user\""
+
+  roles=$("$kcadm" get roles -r keycloak-patterns --fields name)
+  printf "%s" "$roles" | grep -q "\"admin-role\""
+  printf "%s" "$roles" | grep -q "\"user-role\""
+'
+
+echo "realm verified: import, discovery, four clients, two roles, two users"

scripts/verify-stack.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env sh
+set -eu
+
+compose_file=${COMPOSE_FILE:-docker-compose.yml}
+nginx_port=${NGINX_PORT:-8088}
+
+wait_for_url() {
+  name=$1
+  url=$2
+  attempts=30
+
+  while [ "$attempts" -gt 0 ]; do
+    if curl --fail --silent --show-error --output /dev/null "$url"; then
+      return 0
+    fi
+    attempts=$((attempts - 1))
+    sleep 2
+  done
+
+  echo "$name did not become ready: $url" >&2
+  return 1
+}
+
+assert_healthy() {
+  service=$1
+  attempts=30
+
+  while [ "$attempts" -gt 0 ]; do
+    container_id=$(docker compose -f "$compose_file" ps --quiet "$service")
+
+    if [ -n "$container_id" ]; then
+      health=$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$container_id")
+      if [ "$health" = "healthy" ]; then
+        return 0
+      fi
+    else
+      health="not-running"
+    fi
+
+    attempts=$((attempts - 1))
+    sleep 2
+  done
+
+  echo "$service is not healthy: $health" >&2
+  return 1
+}
+
+for service in postgres keycloak app nginx; do
+  assert_healthy "$service"
+done
+
+wait_for_url "Keycloak discovery" \
+  "http://localhost:8080/realms/master/.well-known/openid-configuration"
+wait_for_url "Spring Boot health" "http://localhost:8081/actuator/health"
+wait_for_url "nginx health" "http://localhost:${nginx_port}/health"
+wait_for_url "public API" "http://localhost:${nginx_port}/api/public"
+
+protected_status=$(curl --silent --output /dev/null --write-out '%{http_code}' \
+  "http://localhost:${nginx_port}/api/me")
+if [ "$protected_status" != "401" ]; then
+  echo "expected unauthenticated /api/me to return 401, got $protected_status" >&2
+  exit 1
+fi
+
+echo "baseline stack verified: 4 healthy services, public 200, protected 401"