merge: BFF versus SPA-direct comparison

.gitignore

@@ -4,6 +4,9 @@
 *.iml
 
 backend/target/
+bff/target/
+**/node_modules/
+frontend/dist/
 build/
 e2e/node_modules/
 google-e2e/node_modules/

README.md

@@ -103,3 +103,19 @@ Keycloak을 잠시 중지하고 export한 뒤 자동으로 다시 올립니다.
 
 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)를 참고하세요.
+최종 AP3 branch는 `AP3_SESSION; HttpOnly; SameSite=Lax`와 Spring CSRF
+token을 함께 사용하며, token 없는 상태 변경 요청은 403으로 거부합니다.

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/resources/application.yml

@@ -11,6 +11,9 @@ spring:
           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:

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", true);
+
+        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/CsrfController.java

@@ -0,0 +1,25 @@
+package com.example.keycloakpattern.bff;
+
+import java.util.Map;
+
+import org.springframework.http.CacheControl;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.web.csrf.CsrfToken;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class CsrfController {
+
+    @GetMapping("/bff/csrf")
+    ResponseEntity<Map<String, String>> csrf(CsrfToken csrfToken) {
+        return ResponseEntity.ok()
+            .cacheControl(CacheControl.noStore())
+            .header("Pragma", "no-cache")
+            .body(Map.of(
+                "headerName", csrfToken.getHeaderName(),
+                "parameterName", csrfToken.getParameterName(),
+                "token", csrfToken.getToken()
+            ));
+    }
+}

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

@@ -0,0 +1,80 @@
+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;
+import org.springframework.security.web.csrf.CookieCsrfTokenRepository;
+
+@Configuration
+public class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain bffSecurity(
+        HttpSecurity http,
+        ClientRegistrationRepository clientRegistrationRepository
+    ) throws Exception {
+        DefaultOAuth2AuthorizationRequestResolver authorizationRequestResolver =
+            new DefaultOAuth2AuthorizationRequestResolver(
+                clientRegistrationRepository,
+                "/oauth2/authorization"
+            );
+        authorizationRequestResolver.setAuthorizationRequestCustomizer(
+            OAuth2AuthorizationRequestCustomizers.withPkce()
+        );
+
+        CookieCsrfTokenRepository csrfTokenRepository =
+            CookieCsrfTokenRepository.withHttpOnlyFalse();
+        csrfTokenRepository.setCookiePath("/");
+
+        return http
+            .csrf(csrf -> csrf
+                .csrfTokenRepository(csrfTokenRepository)
+                .csrfTokenRequestHandler(new SpaCsrfTokenRequestHandler()))
+            .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/java/com/example/keycloakpattern/bff/SpaCsrfTokenRequestHandler.java

@@ -0,0 +1,40 @@
+package com.example.keycloakpattern.bff;
+
+import java.util.function.Supplier;
+
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+
+import org.springframework.security.web.csrf.CsrfToken;
+import org.springframework.security.web.csrf.CsrfTokenRequestAttributeHandler;
+import org.springframework.security.web.csrf.CsrfTokenRequestHandler;
+import org.springframework.security.web.csrf.XorCsrfTokenRequestAttributeHandler;
+import org.springframework.util.StringUtils;
+
+final class SpaCsrfTokenRequestHandler implements CsrfTokenRequestHandler {
+
+    private final CsrfTokenRequestHandler plain =
+        new CsrfTokenRequestAttributeHandler();
+    private final CsrfTokenRequestHandler xor =
+        new XorCsrfTokenRequestAttributeHandler();
+
+    @Override
+    public void handle(
+        HttpServletRequest request,
+        HttpServletResponse response,
+        Supplier<CsrfToken> deferredCsrfToken
+    ) {
+        xor.handle(request, response, deferredCsrfToken);
+    }
+
+    @Override
+    public String resolveCsrfTokenValue(
+        HttpServletRequest request,
+        CsrfToken csrfToken
+    ) {
+        if (StringUtils.hasText(request.getHeader(csrfToken.getHeaderName()))) {
+            return plain.resolveCsrfTokenValue(request, csrfToken);
+        }
+        return xor.resolveCsrfTokenValue(request, csrfToken);
+    }
+}

bff/src/main/resources/application.yml

@@ -0,0 +1,47 @@
+server:
+  port: ${SERVER_PORT:8083}
+  servlet:
+    session:
+      cookie:
+        name: AP3_SESSION
+        http-only: true
+        same-site: lax
+
+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,59 @@
+const result = document.querySelector("#result");
+
+function render(value) {
+  result.textContent = JSON.stringify(value, null, 2);
+}
+
+function readCookie(name) {
+  const prefix = `${encodeURIComponent(name)}=`;
+  const value = document.cookie
+    .split("; ")
+    .find((cookie) => cookie.startsWith(prefix));
+  return value ? decodeURIComponent(value.slice(prefix.length)) : null;
+}
+
+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-with-csrf").addEventListener("click", async () => {
+  const csrfResponse = await fetch("/bff/csrf", {
+    headers: { Accept: "application/json" },
+  });
+  const csrf = await csrfResponse.json();
+  const csrfToken = readCookie("XSRF-TOKEN");
+  if (!csrfToken) {
+    render({ status: 500, error: "XSRF-TOKEN cookie was not created" });
+    return;
+  }
+  await request("/bff/api/preferences", {
+    method: "POST",
+    body: new URLSearchParams({ theme: "dark" }),
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      [csrf.headerName]: csrfToken,
+    },
+  });
+});

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-with-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,90 @@
+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.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf;
+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(true))
+            .andExpect(jsonPath("$.access_token").doesNotExist())
+            .andExpect(jsonPath("$.refresh_token").doesNotExist());
+    }
+
+    @Test
+    void rejectsStateChangeWithoutCsrfToken() throws Exception {
+        mockMvc.perform(post("/bff/api/preferences")
+                .param("theme", "attacker")
+                .with(oidcLogin().idToken(token -> token.subject("test-subject"))))
+            .andExpect(status().isForbidden());
+    }
+
+    @Test
+    void acceptsStateChangeWithCsrfToken() throws Exception {
+        mockMvc.perform(post("/bff/api/preferences")
+                .param("theme", "dark")
+                .with(oidcLogin().idToken(token -> token.subject("test-subject")))
+                .with(csrf()))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.updated").value(true))
+            .andExpect(jsonPath("$.theme").value("dark"));
+    }
+
+    @Test
+    void exposesSpaCsrfTokenWithoutCaching() throws Exception {
+        mockMvc.perform(get("/bff/csrf").with(oidcLogin()
+                .idToken(token -> token.subject("test-subject"))))
+            .andExpect(status().isOk())
+            .andExpect(header().string("Cache-Control", "no-store"))
+            .andExpect(header().exists("Set-Cookie"))
+            .andExpect(jsonPath("$.headerName").value("X-XSRF-TOKEN"))
+            .andExpect(jsonPath("$.token").isNotEmpty());
+    }
+}

deploy/reverse-proxy/keycloak.env.example

@@ -0,0 +1,6 @@
+# Keycloak receives HTTP only from the trusted reverse proxy.
+KC_HTTP_ENABLED=true
+KC_PROXY_HEADERS=xforwarded
+KC_HOSTNAME=https://auth.example.test
+KC_HOSTNAME_STRICT=true
+

deploy/reverse-proxy/nginx-keycloak.conf

@@ -0,0 +1,14 @@
+server {
+    listen 8080;
+    server_name auth.example.test;
+
+    location / {
+        proxy_pass http://keycloak:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Forwarded-Port 443;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}

deploy/tls/Caddyfile

@@ -0,0 +1,10 @@
+auth.example.test {
+	tls /etc/tls/tls.crt /etc/tls/tls.key
+
+	reverse_proxy keycloak:8080 {
+		header_up Host {host}
+		header_up X-Forwarded-Host {host}
+		header_up X-Forwarded-Port 443
+		header_up X-Forwarded-Proto https
+	}
+}

deploy/tls/nginx.conf

@@ -0,0 +1,21 @@
+events {}
+
+http {
+    server {
+        listen 443 ssl;
+        server_name auth.example.test;
+
+        ssl_certificate /etc/tls/tls.crt;
+        ssl_certificate_key /etc/tls/tls.key;
+        ssl_protocols TLSv1.2 TLSv1.3;
+
+        location / {
+            proxy_pass http://keycloak:8080;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Port 443;
+            proxy_set_header X-Forwarded-Proto https;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        }
+    }
+}

deploy/tunnel/cloudflared-config.yml

@@ -0,0 +1,7 @@
+tunnel: 00000000-0000-0000-0000-000000000000
+credentials-file: /etc/cloudflared/00000000-0000-0000-0000-000000000000.json
+
+ingress:
+  - hostname: auth.example.test
+    service: http://reverse-proxy:8080
+  - service: http_status:404

docker-compose.yml

@@ -88,6 +88,32 @@ services:
       - 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

docs/account-linking-sub-vs-email.md

@@ -0,0 +1,18 @@
+# Federated account key: `sub`, not email
+
+외부 IdP의 email은 표시·연락 속성이지 계정 식별자나 자동 연결 증명이 아니다.
+Keycloak의 federated identity는 provider alias와 provider user ID(`sub`)를
+로컬 사용자에 연결한다.
+
+정책:
+
+- 신규 identity의 email이 기존 로컬 계정과 충돌하면 기존 계정의 인증을 다시
+  요구하는 기본 First Broker Login flow를 사용한다.
+- `Automatically Set Existing User`를 production flow에 넣지 않는다.
+- upstream email 변경은 같은 `sub`의 계정 귀속을 바꾸지 않는다.
+- 마지막 로그인 수단을 unlink하는 UI에서는 먼저 다른 인증 수단을 등록하도록
+  안내한다.
+
+`verify-account-linking-sub-vs-email.sh`는 mock IdP 사용자의 email을 실제로
+변경하고 다시 로그인한다. 로컬 사용자 ID가 유지되고 federated `userId`가
+upstream `sub`와 같은지 확인한 후 원래 email을 복구한다.

docs/ap3-bff-boundary.md

@@ -0,0 +1,36 @@
+# 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와 SameSite 방어
+
+`feature/keycloak-bff-oauth2login-session`에서는 방어 전 비교를 위해
+CSRF를 끄고, 다른 origin의 자동 제출 form이 `/bff/api/preferences`
+상태를 바꾸는 것을 재현합니다.
+
+`feature/keycloak-bff-csrf-samesite-defense`에서는 다음 방어를 함께
+적용합니다.
+
+- Spring synchronizer CSRF token과 `CookieCsrfTokenRepository`
+- JS가 읽는 `XSRF-TOKEN`과 요청의 `X-XSRF-TOKEN` header
+- HttpOnly `AP3_SESSION` cookie의 명시적 `SameSite=Lax`
+
+E2E는 token 없는 동일 위조 POST가 403이 되는 것, CSRF header가 있는
+정상 POST는 200인 것, cross-site POST에는 AP3 session cookie가 제외되는
+것을 각각 확인합니다. SameSite는 CSRF token을 대체하지 않는
+defense-in-depth입니다.

docs/bff-vs-spa-direct.md

@@ -0,0 +1,22 @@
+# BFF vs SPA direct
+
+| 항목 | SPA direct (AP1) | BFF (AP3) |
+|---|---|---|
+| OAuth client | public + PKCE | confidential + server secret |
+| token holder | browser JavaScript memory | BFF server |
+| browser credential | access/refresh token | HttpOnly session cookie |
+| XSS 영향 | 실행 중 token/API 권한 탈취 가능 | cookie 읽기는 막지만 same-origin 요청 악용 가능 |
+| CSRF | bearer header 중심이라 상대적으로 작음 | session cookie이므로 명시적 방어 필요 |
+| backend 상태 | stateless 가능 | session store 필요 |
+| logout/revocation | browser와 Keycloak 조정 | BFF session과 Keycloak logout 조정 |
+| scale-out | JWT 검증 위주 | sticky session 또는 shared store |
+
+이 repository의 AP3는 Spring `oauth2Login`, confidential `bff-confidential`
+client, server-side authorized-client/token 보관, HttpOnly/SameSite session,
+CSRF token을 실제 구현한다. AP1은 token을 메모리에만 두지만 XSS가 실행되면
+현재 token을 사용할 수 있다는 경계를 E2E로 보여 준다.
+
+선택은 “BFF가 항상 더 안전하다”가 아니라 threat model과 운영비의 교환이다.
+브라우저에 OAuth token을 노출하지 않는 것이 우선이고 stateful 운영을 감당할
+수 있으면 BFF, protocol과 stateless Resource Server를 직접 학습하려면 AP1이
+더 투명하다.

docs/four-pattern-tradeoff-matrix.md

@@ -0,0 +1,37 @@
+# Four Keycloak integration patterns
+
+| 축 | AP1 SPA direct | AP2 token mediator | AP3 BFF | AP4 edge auth |
+|---|---|---|---|---|
+| OAuth client | public | confidential | confidential | confidential proxy |
+| browser 보유물 | access/refresh token | 짧은 handoff code 또는 app token | HttpOnly session cookie | proxy session cookie |
+| OAuth code 교환 | browser + PKCE | mediator backend | BFF | oauth2-proxy |
+| API bearer 검증 | Spring resource server | mediator/downstream API | BFF 내부 또는 downstream | edge가 인증 후 trusted header |
+| server session | 없음 | handoff 상태만 짧게 | 필수 | proxy cookie/session |
+| XSS token 탈취면 | 가장 큼 | 축소 | browser token 제거 | browser token 제거 |
+| CSRF 주의 | token endpoint/refresh 설계 | app cookie 사용 시 | 필수 방어 | proxy cookie 사용 시 |
+| 수평 확장 상태 | 단순 | handoff store 공유 가능 | session store 필요 | proxy 설정에 따름 |
+| 주 학습 포인트 | PKCE/JWT/RS | token 경계·one-time handoff | oauth2Login/session/CSRF | auth_request/header trust |
+
+## 선택 기준
+
+- 브라우저에서 OAuth와 token 수명주기를 직접 학습하려면 AP1.
+- 브라우저에 upstream token을 주지 않되 API 호출은 bearer 중심으로 유지하려면
+  AP2.
+- token을 browser에서 완전히 제거하고 애플리케이션 단위 인가·세션을
+  중앙화하려면 AP3.
+- 기존 upstream을 수정하기 어렵고 경계에서 일괄 인증하려면 AP4.
+
+Google federation은 다섯 번째 인증 패턴이 아니다. 네 패턴 모두 최종적으로
+Keycloak token/session을 소비하며, Google은 Keycloak 앞의 upstream IdP
+hop으로 추가된다.
+
+## 이 repository의 실행 증거
+
+- AP1: PKCE SPA, issuer/audience, token storage, refresh/logout 검증
+- AP2: confidential client와 one-time access handoff 검증
+- AP3: `oauth2Login` session과 CSRF/SameSite 검증
+- AP4: oauth2-proxy, nginx `auth_request`, spoofed header 제거 검증
+- 공통: local mock Google brokering, First Broker Login, claim/role mapping 검증
+
+각 근거 브랜치와 병합 여부는 `keycloak-branch-manifest.tsv` 및
+`audit-keycloak-branches.sh`로 추적한다.

docs/google-redirect-uri-policy.md

@@ -0,0 +1,24 @@
+# Google redirect URI policy
+
+Google에 등록하는 redirect URI는 애플리케이션 SPA callback이 아니라 Keycloak
+broker endpoint다.
+
+```text
+https://auth.example.test/realms/keycloak-patterns/broker/google/endpoint
+```
+
+규칙:
+
+- production URI는 HTTPS와 고정된 public Keycloak origin을 사용한다.
+- wildcard, path prefix, 임시 tunnel hostname을 production OAuth client에
+  등록하지 않는다.
+- 개발·스테이징·운영은 Google OAuth client를 분리한다.
+- reverse proxy가 있더라도 Google이 보는 URI와 Keycloak이 생성하는 URI가
+  byte-for-byte 같아야 한다.
+- `configure-google-idp.sh`가 출력하는 URI를 Google Console의 Authorized
+  redirect URI와 대조한다.
+
+```sh
+PUBLIC_KEYCLOAK_URL=https://auth.example.test \
+  ./scripts/verify-google-redirect-uri-policy.sh
+```

docs/https-termination.md

@@ -0,0 +1,20 @@
+# HTTPS termination: nginx or Caddy
+
+두 예제 모두 public `443`에서 TLS를 종료하고 private Docker network의
+`keycloak:8080`으로 전달한다. Keycloak 쪽 설정은
+`deploy/reverse-proxy/keycloak.env.example`의 hostname/proxy contract를
+같이 사용한다.
+
+- nginx: 인증서 배포·갱신을 운영자가 담당할 때 적합하다.
+- Caddy: ACME를 통한 인증서 수명주기를 proxy가 담당하게 할 때 간단하다.
+- 둘을 동시에 production entry point로 띄우지 않는다.
+- 인증서와 private key는 repository 또는 image에 포함하지 않는다.
+- HTTP challenge/redirect 및 방화벽의 80/443 허용은 배포 환경에서 별도로
+  결정한다.
+
+검증 스크립트는 임시 자체 서명 인증서를 만들고 두 vendor image에서 설정을
+각각 validate한 뒤 임시 파일을 제거한다.
+
+```sh
+./scripts/verify-https-termination-config.sh
+```

docs/public-domain-tunneling.md

@@ -0,0 +1,21 @@
+# Public HTTPS domain for broker callbacks
+
+Google brokering을 반복 테스트할 때는 Cloudflare **named tunnel + 관리
+도메인**을 기본 profile로 사용한다. `trycloudflare.com` quick tunnel과
+임의 ngrok URL은 일회성 데모용이며 고정 callback으로 간주하지 않는다.
+
+설정 순서:
+
+1. `cloudflared tunnel login`
+2. `cloudflared tunnel create keycloak-patterns`
+3. 예제 config의 tunnel UUID와 credentials path를 실제 값으로 교체
+4. `cloudflared tunnel route dns keycloak-patterns auth.example.test`
+5. `cloudflared tunnel run keycloak-patterns`
+6. Keycloak `KC_HOSTNAME`과 Google redirect URI를 같은 public host로 설정
+
+컨테이너 안의 `127.0.0.1`은 cloudflared 컨테이너 자신이므로 origin에는
+`reverse-proxy:8080` 같은 Compose service DNS를 사용한다. 마지막 catch-all
+ingress는 알 수 없는 hostname을 404로 끝낸다.
+
+실 tunnel 생성과 DNS 변경에는 사용자 소유 계정·도메인이 필요하므로 자동
+검증은 ingress 파일의 구조까지만 수행한다.

docs/reverse-proxy-headers.md

@@ -0,0 +1,15 @@
+# Reverse proxy headers
+
+TLS를 reverse proxy에서 종료하면 Keycloak은 브라우저가 사용한 외부 origin을
+정확히 알아야 한다. 배포 예제는 다음 계약을 함께 적용한다.
+
+- nginx는 `Host`, `X-Forwarded-Host`, `X-Forwarded-Port`,
+  `X-Forwarded-Proto`, `X-Forwarded-For`를 덮어쓴다.
+- Keycloak은 `KC_PROXY_HEADERS=xforwarded`로 그 헤더 형식을 명시한다.
+- `KC_HOSTNAME`은 외부 HTTPS URL로 고정하고 strict hostname 검증을 켠다.
+- Keycloak의 8080 포트는 public으로 publish하지 않고 proxy network에서만
+  접근시킨다. 신뢰되지 않은 클라이언트가 forwarded header를 직접 넣을 수
+  있으면 안 된다.
+
+`scripts/verify-reverse-proxy-headers.sh`는 양쪽 설정의 짝과 nginx 구문을
+검증한다.

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,198 @@
+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({ method: request.method(), url: 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");
+  assert.equal(callbackRequest.method, "GET");
+
+  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, true);
+  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);
+  assert.equal(sessionCookie.sameSite, "Lax");
+
+  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);
+
+  const missingCsrfResponse = await page.evaluate(async () => {
+    const response = await fetch("/bff/api/preferences", {
+      method: "POST",
+      body: new URLSearchParams({ theme: "missing-csrf" }),
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    });
+    return response.status;
+  });
+  assert.equal(missingCsrfResponse, 403);
+
+  const csrfResponsePromise = page.waitForResponse((response) =>
+    response.url().endsWith("/bff/csrf"),
+  );
+  const validChangeResponsePromise = page.waitForResponse(
+    (response) =>
+      response.url().endsWith("/bff/api/preferences") &&
+      response.request().method() === "POST" &&
+      response.status() === 200,
+  );
+  await page.locator("#change-with-csrf").click();
+  const csrfResponse = await csrfResponsePromise;
+  const validChangeResponse = await validChangeResponsePromise;
+  assert.equal(csrfResponse.status(), 200);
+  assert.equal(validChangeResponse.status(), 200);
+  const validChange = await validChangeResponse.json();
+  assert.equal(validChange.theme, "dark");
+
+  const csrfCookies = await context.cookies("http://localhost:8083/");
+  const csrfCookie = csrfCookies.find((cookie) => cookie.name === "XSRF-TOKEN");
+  assert.ok(csrfCookie);
+  assert.equal(csrfCookie.httpOnly, false);
+
+  await page.goto("http://localhost:8088");
+  const [forgedResponse] = await Promise.all([
+    page.waitForNavigation(),
+    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();
+    }),
+  ]);
+  assert.ok(forgedResponse);
+  assert.equal(forgedResponse.status(), 403);
+
+  await page.goto("http://127.0.0.1:8088");
+  const crossSiteRequestPromise = page.waitForRequest(
+    (request) =>
+      request.url() === "http://localhost:8083/bff/api/preferences" &&
+      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 = "cross-site-attacker";
+    form.append(input);
+    document.body.append(form);
+    form.submit();
+  });
+  const crossSiteRequest = await crossSiteRequestPromise;
+  const crossSiteHeaders = await crossSiteRequest.allHeaders();
+  assert.equal(
+    (crossSiteHeaders.cookie ?? "").includes("AP3_SESSION="),
+    false,
+    "SameSite=Lax must omit the session cookie on a cross-site POST",
+  );
+
+  console.log(
+    "pattern3 BFF verified: tokenless POST 403, CSRF header 200, SameSite=Lax session",
+  );
+} finally {
+  await browser.close();
+}

google-e2e/package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "test:first-broker": "node first-broker-login.mjs",
     "test:claim-mapping": "node claim-mapping.mjs",
-    "test:claim-to-role": "node claim-to-role.mjs"
+    "test:claim-to-role": "node claim-to-role.mjs",
+    "test:sub-vs-email": "node sub-vs-email.mjs"
   },
   "dependencies": {
     "playwright-core": "1.55.1"

google-e2e/sub-vs-email.mjs

@@ -0,0 +1,132 @@
+import assert from "node:assert/strict";
+import { chromium } from "playwright-core";
+
+const baseUrl = process.env.KEYCLOAK_URL ?? "http://localhost:8080";
+const adminUsername = process.env.KC_BOOTSTRAP_ADMIN_USERNAME;
+const adminPassword = process.env.KC_BOOTSTRAP_ADMIN_PASSWORD;
+const mockPassword = process.env.MOCK_GOOGLE_USER_PASSWORD;
+assert.ok(adminUsername && adminPassword && mockPassword);
+
+async function adminToken() {
+  const response = await fetch(
+    `${baseUrl}/realms/master/protocol/openid-connect/token`,
+    {
+      method: "POST",
+      body: new URLSearchParams({
+        client_id: "admin-cli",
+        grant_type: "password",
+        username: adminUsername,
+        password: adminPassword,
+      }),
+    },
+  );
+  assert.equal(response.status, 200);
+  return (await response.json()).access_token;
+}
+
+async function adminJson(token, path, init = {}) {
+  const response = await fetch(`${baseUrl}/admin/realms/${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(init.body ? { "Content-Type": "application/json" } : {}),
+    },
+  });
+  assert.ok(response.ok, `${init.method ?? "GET"} ${path}: ${response.status}`);
+  return response.status === 204 ? undefined : response.json();
+}
+
+async function users(token, realm, query) {
+  return adminJson(token, `${realm}/users?${new URLSearchParams(query)}`);
+}
+
+async function brokerLogin(browser) {
+  const page = await browser.newPage();
+  const url = new URL(
+    `${baseUrl}/realms/keycloak-patterns/protocol/openid-connect/auth`,
+  );
+  url.search = new URLSearchParams({
+    client_id: "spa-public",
+    redirect_uri: "http://localhost:8088/",
+    response_type: "code",
+    scope: "openid profile email",
+    state: crypto.randomUUID(),
+    nonce: crypto.randomUUID(),
+    code_challenge: "K2qUEfBl-nQvF2gB4dNxC2zYVwZc1CVnZb5CsX2L7fI",
+    code_challenge_method: "S256",
+    kc_idp_hint: "mock-google",
+    prompt: "login",
+  });
+  await page.goto(url.toString());
+  await page.waitForURL(/\/realms\/mock-google\//u);
+  await page.locator("#username").fill("mock-new-user");
+  await page.locator("#password").fill(mockPassword);
+  await page.locator("#kc-login").click();
+  await page.waitForURL(/localhost:8088\/\?.*code=/u);
+  await page.close();
+}
+
+const token = await adminToken();
+const mockUsers = await users(token, "mock-google", {
+  username: "mock-new-user",
+  exact: "true",
+});
+assert.equal(mockUsers.length, 1);
+const mockUser = await adminJson(
+  token,
+  `mock-google/users/${mockUsers[0].id}`,
+);
+const originalEmail = mockUser.email;
+const changedEmail = "broker-renamed-user@example.test";
+
+for (const existing of await users(token, "keycloak-patterns", {
+  username: `mock-google.${mockUser.id}`,
+  exact: "true",
+})) {
+  await adminJson(token, `keycloak-patterns/users/${existing.id}`, {
+    method: "DELETE",
+  });
+}
+
+const browser = await chromium.launch({
+  executablePath: process.env.CHROME_BIN ?? "/usr/bin/google-chrome",
+  headless: true,
+  args: ["--no-sandbox"],
+});
+
+try {
+  await brokerLogin(browser);
+  const before = await users(token, "keycloak-patterns", {
+    username: `mock-google.${mockUser.id}`,
+    exact: "true",
+  });
+  assert.equal(before.length, 1);
+  const localUserId = before[0].id;
+  const identities = await adminJson(
+    token,
+    `keycloak-patterns/users/${localUserId}/federated-identity`,
+  );
+  assert.equal(identities[0].userId, mockUser.id);
+
+  await adminJson(token, `mock-google/users/${mockUser.id}`, {
+    method: "PUT",
+    body: JSON.stringify({ ...mockUser, email: changedEmail }),
+  });
+  await brokerLogin(browser);
+
+  const after = await users(token, "keycloak-patterns", {
+    username: `mock-google.${mockUser.id}`,
+    exact: "true",
+  });
+  assert.equal(after.length, 1);
+  assert.equal(after[0].id, localUserId);
+  console.log(
+    "Federated identity verified: provider sub stayed linked while upstream email changed",
+  );
+} finally {
+  await adminJson(token, `mock-google/users/${mockUser.id}`, {
+    method: "PUT",
+    body: JSON.stringify({ ...mockUser, email: originalEmail }),
+  });
+  await browser.close();
+}

keycloak/import/keycloak-patterns-realm.json

@@ -102,8 +102,24 @@
         "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-account-linking-sub-vs-email.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env sh
+set -eu
+
+set -a
+. ./.env
+set +a
+
+./scripts/set-first-broker-login-mode.sh secure
+cd google-e2e
+npm install --ignore-scripts
+npm run test:sub-vs-email

scripts/verify-google-redirect-uri-policy.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+set -eu
+
+realm="${KEYCLOAK_REALM:-keycloak-patterns}"
+public_keycloak_url="${PUBLIC_KEYCLOAK_URL:-https://auth.example.test}"
+expected="$public_keycloak_url/realms/$realm/broker/google/endpoint"
+
+case "$public_keycloak_url" in
+  https://*) ;;
+  *)
+    echo "PUBLIC_KEYCLOAK_URL must use https outside the local mock environment" >&2
+    exit 1
+    ;;
+esac
+
+case "$public_keycloak_url" in
+  *\** | */)
+    echo "PUBLIC_KEYCLOAK_URL must be an exact origin without wildcard/trailing slash" >&2
+    exit 1
+    ;;
+esac
+
+test "$expected" = "https://auth.example.test/realms/keycloak-patterns/broker/google/endpoint"
+echo "Google redirect URI policy verified: $expected"

scripts/verify-https-termination-config.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env sh
+set -eu
+
+test_dir="$(mktemp -d)"
+cleanup() {
+  rm -rf "$test_dir"
+}
+trap cleanup EXIT
+
+openssl req -x509 -newkey rsa:2048 -nodes -days 1 \
+  -subj "/CN=auth.example.test" \
+  -keyout "$test_dir/tls.key" \
+  -out "$test_dir/tls.crt" >/dev/null 2>&1
+
+docker run --rm \
+  --add-host keycloak:127.0.0.1 \
+  -v "$PWD/deploy/tls/nginx.conf:/etc/nginx/nginx.conf:ro" \
+  -v "$test_dir:/etc/tls:ro" \
+  nginx:1.29-alpine nginx -t
+
+docker run --rm \
+  --add-host keycloak:127.0.0.1 \
+  -v "$PWD/deploy/tls/Caddyfile:/etc/caddy/Caddyfile:ro" \
+  -v "$test_dir:/etc/tls:ro" \
+  caddy:2.10.2-alpine caddy validate --config /etc/caddy/Caddyfile
+
+echo "nginx and Caddy HTTPS termination configurations verified"

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-public-tunnel-config.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env sh
+set -eu
+
+config=deploy/tunnel/cloudflared-config.yml
+grep -q '^tunnel: [0-9a-f-]*$' "$config"
+grep -q '^  - hostname: auth.example.test$' "$config"
+grep -q '^    service: http://reverse-proxy:8080$' "$config"
+grep -q '^  - service: http_status:404$' "$config"
+
+docker run --rm \
+  -v "$PWD/$config:/etc/cloudflared/config.yml:ro" \
+  cloudflare/cloudflared:2025.6.1 \
+  tunnel --config /etc/cloudflared/config.yml ingress validate
+
+echo "Cloudflare named-tunnel ingress configuration verified"

scripts/verify-reverse-proxy-headers.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+set -eu
+
+config=deploy/reverse-proxy/nginx-keycloak.conf
+env_file=deploy/reverse-proxy/keycloak.env.example
+
+grep -q 'proxy_set_header X-Forwarded-Host' "$config"
+grep -q 'proxy_set_header X-Forwarded-Port 443' "$config"
+grep -q 'proxy_set_header X-Forwarded-Proto https' "$config"
+grep -q '^KC_PROXY_HEADERS=xforwarded$' "$env_file"
+grep -q '^KC_HOSTNAME=https://' "$env_file"
+
+docker run --rm \
+  --add-host keycloak:127.0.0.1 \
+  -v "$PWD/$config:/etc/nginx/conf.d/default.conf:ro" \
+  nginx:1.29-alpine nginx -t
+
+echo "Reverse-proxy header and Keycloak hostname contracts verified"