docs: define single-EC2 Google federation deployment

.gitignore

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

README.md

@@ -103,3 +103,39 @@ Keycloak을 잠시 중지하고 export한 뒤 자동으로 다시 올립니다.
 
 runtime export에는 실제 client secret과 credential hash가 포함될 수 있어
 gitignored `build/keycloak-export/`에 권한 `0600`으로만 저장됩니다.
+
+## AP1: SPA Direct + Resource Server
+
+`develop-keycloak-pattern1`은 vanilla JavaScript SPA가 `spa-public` client로
+Authorization Code + PKCE S256 로그인을 수행하는 패턴입니다. access/refresh
+token은 명시적인 in-memory store에만 보관되므로 새로고침하면 사라집니다.
+
+```bash
+./scripts/verify-pattern1.sh
+```
+
+브라우저에서 `http://localhost:8088`을 열어 로그인한 뒤 보호 API를 호출할 수
+있습니다. SPA는 `http://localhost:8081/api/me`를 직접 호출하며 Spring
+Resource Server가 Bearer JWT를 검증합니다.
+
+Keycloak의 dedicated audience mapper는 `spa-public` access token에
+`keycloak-pattern-api`를 추가합니다. Spring은 signature, `iss`, `exp`뿐
+아니라 이 `aud`도 검사합니다. `verify-pattern1.sh`는 같은 정상 토큰을
+`deliberately-wrong-audience`를 기대하는 진단 인스턴스에도 제출해 `401`을
+확인합니다.
+
+Keycloak은 `KC_HOSTNAME=http://localhost:8080`을 기준으로 token의 `iss`를
+발급합니다. 정상 Resource Server는 이 외부 issuer 문자열을 검증하되 JWKS는
+Docker 내부의 `http://keycloak:8080`에서 가져옵니다. 진단 인스턴스는 일부러
+`http://wrong-issuer.invalid`를 기대하도록 구성되어, 서명과 audience가
+정상이더라도 issuer mismatch로 `401`을 반환합니다.
+
+token 저장 위치와 XSS 범위는
+[`docs/ap1-token-storage.md`](docs/ap1-token-storage.md)에 정리했습니다.
+E2E는 Web Storage token이 0개임과 동시에 실행 중 fetch hook이 Bearer
+header를 관찰할 수 있음을 재현합니다.
+
+refresh rotation, 소비된 refresh token 재사용, RP-Initiated Logout,
+revocation과 stateless JWT의 차이는
+[`docs/ap1-refresh-logout.md`](docs/ap1-refresh-logout.md)에 정리했으며 같은
+E2E에서 실제 Keycloak 26.7.0 동작을 검증합니다.

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

@@ -27,4 +27,9 @@ public class ApiController {
         response.put("audience", jwt.getAudience());
         return response;
     }
+
+    @GetMapping("/admin")
+    public Map<String, String> adminEndpoint() {
+        return Map.of("status", "ok", "authorization", "admin-role");
+    }
 }

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/KeycloakRealmRoleConverter.java

@@ -0,0 +1,28 @@
+package com.example.keycloakpattern;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+
+import org.springframework.core.convert.converter.Converter;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.oauth2.jwt.Jwt;
+
+final class KeycloakRealmRoleConverter
+    implements Converter<Jwt, Collection<GrantedAuthority>> {
+
+    @Override
+    public Collection<GrantedAuthority> convert(Jwt jwt) {
+        Map<String, Object> realmAccess = jwt.getClaimAsMap("realm_access");
+        if (realmAccess == null || !(realmAccess.get("roles") instanceof Collection<?> roles)) {
+            return List.of();
+        }
+        return roles.stream()
+            .filter(String.class::isInstance)
+            .map(String.class::cast)
+            .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
+            .map(GrantedAuthority.class::cast)
+            .toList();
+    }
+}

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

@@ -1,11 +1,17 @@
 package com.example.keycloakpattern;
 
+import java.util.List;
+
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.http.SessionCreationPolicy;
+import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
 import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.web.cors.CorsConfiguration;
+import org.springframework.web.cors.CorsConfigurationSource;
+import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
 
 @Configuration
 public class SecurityConfig {
@@ -13,15 +19,40 @@ public class SecurityConfig {
     @Bean
     SecurityFilterChain apiSecurity(HttpSecurity http) throws Exception {
         return http
+            .cors(Customizer.withDefaults())
             .csrf(csrf -> csrf.disable())
             .sessionManagement(session ->
                 session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
             .authorizeHttpRequests(authorize -> authorize
                 .requestMatchers("/actuator/health", "/actuator/health/**", "/api/public")
                 .permitAll()
+                .requestMatchers("/api/admin")
+                .hasRole("admin-role")
                 .anyRequest()
                 .authenticated())
-            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
+            .oauth2ResourceServer(oauth2 -> oauth2.jwt(jwt ->
+                jwt.jwtAuthenticationConverter(jwtAuthenticationConverter())))
             .build();
     }
+
+    private JwtAuthenticationConverter jwtAuthenticationConverter() {
+        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
+        converter.setJwtGrantedAuthoritiesConverter(new KeycloakRealmRoleConverter());
+        return converter;
+    }
+
+    @Bean
+    CorsConfigurationSource corsConfigurationSource() {
+        CorsConfiguration configuration = new CorsConfiguration();
+        configuration.setAllowedOrigins(List.of(
+            "http://localhost:8088",
+            "http://127.0.0.1:8088"
+        ));
+        configuration.setAllowedMethods(List.of("GET", "OPTIONS"));
+        configuration.setAllowedHeaders(List.of("Authorization", "Content-Type"));
+
+        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+        source.registerCorsConfiguration("/api/**", configuration);
+        return source;
+    }
 }

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/ApiSecurityTest.java

@@ -10,6 +10,7 @@ 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;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
 
 @SpringBootTest
 @AutoConfigureMockMvc
@@ -40,4 +41,19 @@ class ApiSecurityTest {
             .andExpect(jsonPath("$.subject").value("test-subject"))
             .andExpect(jsonPath("$.username").value("regular-user"));
     }
+
+    @Test
+    void regularUserCannotCallAdminEndpoint() throws Exception {
+        mockMvc.perform(get("/api/admin").with(jwt()
+                .authorities(new SimpleGrantedAuthority("ROLE_user-role"))))
+            .andExpect(status().isForbidden());
+    }
+
+    @Test
+    void adminRoleCanCallAdminEndpoint() throws Exception {
+        mockMvc.perform(get("/api/admin").with(jwt()
+                .authorities(new SimpleGrantedAuthority("ROLE_admin-role"))))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.authorization").value("admin-role"));
+    }
 }

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)
+        );
+    }
+}

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

@@ -0,0 +1,46 @@
+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.jwt.Jwt;
+
+class KeycloakRealmRoleConverterTest {
+
+    private final KeycloakRealmRoleConverter converter =
+        new KeycloakRealmRoleConverter();
+
+    @Test
+    void mapsRealmRolesWithExactlyOneRolePrefix() {
+        Jwt jwt = new Jwt(
+            "token",
+            Instant.now(),
+            Instant.now().plusSeconds(60),
+            Map.of("alg", "none"),
+            Map.of("sub", "subject", "realm_access", Map.of(
+                "roles", List.of("admin-role", "user-role")
+            ))
+        );
+
+        assertThat(converter.convert(jwt))
+            .extracting("authority")
+            .containsExactly("ROLE_admin-role", "ROLE_user-role");
+    }
+
+    @Test
+    void missingRealmAccessProducesNoAuthorities() {
+        Jwt jwt = new Jwt(
+            "token",
+            Instant.now(),
+            Instant.now().plusSeconds(60),
+            Map.of("alg", "none"),
+            Map.of("sub", "subject")
+        );
+
+        assertThat(converter.convert(jwt)).isEmpty();
+    }
+}

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,58 @@ services:
       - keycloak-net
     restart: unless-stopped
 
+  app-wrong-audience:
+    profiles:
+      - diagnostics
+    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
+      SECURITY_EXPECTED_AUDIENCE: deliberately-wrong-audience
+    ports:
+      - "127.0.0.1:18081: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
+
+  app-wrong-issuer:
+    profiles:
+      - diagnostics
+    build:
+      context: ./backend
+    environment:
+      SERVER_PORT: "8081"
+      SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI: http://wrong-issuer.invalid/realms/keycloak-patterns
+      SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI: http://keycloak:8080/realms/keycloak-patterns/protocol/openid-connect/certs
+      SECURITY_EXPECTED_AUDIENCE: keycloak-pattern-api
+    ports:
+      - "127.0.0.1:18082: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
+
   nginx:
     build:
       context: ./frontend

docs/account-linking-spa-ux.md

@@ -0,0 +1,18 @@
+# Account linking UX for the SPA
+
+두 흐름을 구분한다.
+
+- 로그인 도중 email collision: Keycloak의 안전한 First Broker Login flow가
+  기존 계정 인증을 요구한다.
+- 로그인한 사용자가 설정 화면에서 “Google 연결”: Client-Initiated Account
+  Linking URL을 만들어 Keycloak로 redirect한다.
+
+`createAccountLinkUrl`은 현재 token의 `session_state`, `azp`(issued-for),
+provider와 nonce를 SHA-256 서명 재료로 사용한다. SPA는 연결 성공 후
+Account Console 또는 별도 backend read model을 통해 연결 상태를 새로
+조회해야 하며 email만 보고 “연결됨”을 표시하면 안 된다.
+
+Unlink는 사용자가 다른 로그인 수단을 갖고 있는지 먼저 안내하고, Keycloak이
+마지막 federated identity 제거를 거부하면 해당 오류를 그대로 성공처럼
+처리하지 않는다. production First Broker Login에는 자동 기존-user linking을
+넣지 않는다.

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/ap1-refresh-logout.md

@@ -0,0 +1,30 @@
+# AP1 refresh rotation and logout
+
+Realm 실행 profile:
+
+- Access Token Lifespan: 300초
+- Revoke Refresh Token: 활성화
+- Refresh Token Max Reuse: 0
+
+`e2e/pattern1.mjs`는 token 원문을 출력하지 않고 다음 순서를 실행한다.
+
+1. browser Authorization Code + PKCE 로그인으로 AT₁/RT₁/ID Token을 받는다.
+2. `signoutRedirect()`가 `id_token_hint`를 포함한 Keycloak logout endpoint를
+   호출하는지 확인한다.
+3. logout 이후 새 authorization 요청에서 로그인 화면이 다시 필요한지
+   확인한다.
+4. 새 RT₁으로 refresh하여 AT₂/RT₂를 받고 RT₂가 RT₁과 다른지 확인한다.
+5. 이미 소비된 RT₁을 재사용해 성공하지 않는지 확인한다.
+6. RT₁ 재사용 뒤 RT₂와 realm session 상태가 어떤 결과를 내는지 status로
+   기록한다. 이 결과를 사전에 family invalidation이라고 단정하지 않는다.
+7. refresh token을 revoke한 뒤 같은 refresh token의 재사용은 실패하지만,
+   이미 발급된 self-contained access JWT는 `exp` 전까지 Resource Server에서
+   계속 `200`인 stateless 함정을 확인한다.
+
+logout은 브라우저 SSO session을 종료하는 흐름이고 token revocation은 특정
+token grant를 폐기하는 흐름이다. 둘은 목적과 endpoint가 다르다.
+
+즉시 access 차단이 필요한 시스템이라면 짧은 access token TTL 외에
+introspection, reference token 또는 별도 deny-list 같은 stateful 검증을
+검토해야 한다. 이 AP1 구현은 JWT의 stateless 검증 특성을 의도적으로
+유지한다.

docs/ap1-token-storage.md

@@ -0,0 +1,29 @@
+# AP1 token storage trade-off
+
+AP1에서는 `access_token`, `refresh_token`, `id_token`을
+`oidc-client-ts`의 명시적인 `InMemoryWebStorage`에만 보관한다.
+`localStorage`와 `sessionStorage`에는 OAuth token을 저장하지 않는다.
+
+full-page authorization redirect를 생존해야 하는 일회성 transaction
+state와 PKCE verifier만 `sessionStorage`를 사용한다. callback 성공 후
+라이브러리가 해당 transaction state를 제거한다.
+
+| 저장 위치 | reload 생존 | JavaScript 접근 | AP1 선택 |
+|---|---:|---:|---:|
+| 메모리 | 아니요 | 실행 중 가능 | 사용 |
+| `sessionStorage` | 같은 탭에서 가능 | 가능 | token 저장 금지 |
+| `localStorage` | 예 | 가능 | token 저장 금지 |
+| HttpOnly cookie | 가능 | raw token 접근 불가 | AP2/AP3의 서버 소유 경계 |
+
+메모리 저장은 XSS를 제거하지 않는다. 악성 스크립트가 실행 중 `fetch`를
+후킹하면 SPA가 붙이는 `Authorization: Bearer ...` 헤더를 관찰할 수 있다.
+다만 persistent storage를 사용하지 않으므로 reload 이후 탈취 가능한 token
+복사본이 남지 않는다.
+
+`e2e/pattern1.mjs`는 다음 두 조건을 동시에 검증한다.
+
+1. access token이 Web Storage 어디에도 존재하지 않는다.
+2. 실행 중 fetch hook은 Bearer token을 관찰할 수 있다.
+
+따라서 결론은 “메모리면 XSS에 안전”이 아니라 “영속 탈취 범위를 줄이지만
+실행 중 XSS에는 여전히 노출”이다.

docs/federation-spa-zero-change.md

@@ -0,0 +1,16 @@
+# Google federation without an AP1 application fork
+
+SPA는 Google SDK나 Google token endpoint를 알지 않는다. 기존 `spa-public`
+client로 Keycloak authorization endpoint를 호출하고, Keycloak 로그인
+화면에서 mock Google을 선택해도 callback, PKCE 교환, access token audience,
+Spring API 호출은 로컬 사용자 로그인과 동일하다.
+
+달라지는 곳은 Keycloak 앞단뿐이다.
+
+```text
+SPA -> Keycloak -> Google/mock OIDC
+SPA <- Keycloak access token <- Keycloak
+```
+
+`verify-federation-spa-zero-change.sh`는 기존 SPA 로그인 버튼에서 broker를
+선택하고, 변경 없는 callback과 `/api/me`가 200인지 실제 브라우저로 검증한다.

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-claim-to-role.md

@@ -0,0 +1,18 @@
+# Google claim-to-role mapping
+
+`hd=example.test`인 upstream OIDC identity에는 Keycloak realm role
+`employee-role`을 부여한다. 매핑 키는 email이 아니라 Google subject이며,
+role 조건에 쓰는 `hd` claim은 mock provider와 실제 Google provider에서 같은
+계약을 사용한다.
+
+Realm import는 `oidc-role-idp-mapper`를 선언한다. 실제 Google 설정 스크립트도
+같은 mapper를 upsert한다. 따라서 재실행해도 mapper가 중복되지 않는다.
+
+검증:
+
+```sh
+./scripts/verify-google-claim-to-role.sh
+```
+
+검증기는 mock Google 로그인, Authorization Code + PKCE 교환, 최종 Keycloak
+access token의 `realm_access.roles`를 차례로 확인한다.

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/internal-spa-direct-google-federation.md

@@ -0,0 +1,18 @@
+# AP1 internal SPA direct: Google-federated profile
+
+```text
+SPA -> Keycloak -> Google
+SPA <- Keycloak code/token <- Keycloak
+SPA -> Spring API with Keycloak access token
+```
+
+Google은 upstream authentication만 담당한다. SPA와 Resource Server의 trust
+anchor는 계속 Keycloak issuer/JWKS/audience다. 따라서 Spring이 Google
+ID token을 직접 받거나 Google JWKS를 검증하지 않는다.
+
+추가 운영 항목은 Google client secret, exact broker redirect URI, safe First
+Broker Login, `sub` account key, claim mapper다. 로컬에서는 두 번째 Keycloak
+realm이 Google 역할을 하므로 외부 credential 없이 같은 hop을 재현한다.
+
+`verify-internal-spa-google-contract.sh`는 broker 설정과 기존 AP1 SPA의
+zero-change federation E2E를 함께 실행한다.

docs/internal-spa-direct-no-google.md

@@ -0,0 +1,17 @@
+# AP1 internal SPA direct: local identity profile
+
+```text
+Browser SPA --Authorization Code + PKCE--> Keycloak
+Browser SPA --Bearer access token-------> Spring Resource Server
+```
+
+이 profile은 Keycloak 로컬 사용자만으로 동작한다. Google client ID/secret,
+public domain, broker callback이 없어도 AP1의 login, refresh, logout,
+audience/issuer 검증과 RBAC를 모두 학습할 수 있다.
+
+`mock-google` provider가 realm에 함께 존재해도 로컬 로그인은 provider
+availability에 의존하지 않는다. 실제로 federation 없는 배포를 만들 때는
+해당 IdP를 disabled로 두거나 realm overlay에서 제거한다.
+
+빠른 계약 검증은 `verify-internal-spa-no-google-contract.sh`, 실제 브라우저
+흐름은 `verify-pattern1.sh`가 담당한다.

docs/pkce-flow-stages.md

@@ -0,0 +1,15 @@
+# Authorization Code + PKCE stages
+
+1. SPA가 매 로그인마다 고엔트로피 `code_verifier`를 생성한다.
+2. SHA-256과 Base64URL로 `code_challenge`를 만든다.
+3. authorization request에는 challenge와 `S256`만 전송한다.
+4. redirect의 code와 저장해 둔 state를 대조한다.
+5. token request에 원래 verifier를 보내 code를 교환한다.
+6. verifier/state/code는 한 번 사용한 뒤 메모리에서 제거한다.
+
+Keycloak client는 public client이며 implicit와 password grant를 끄고 S256을
+강제한다. PKCE는 악성 redirect endpoint가 code만 가로챘을 때의 교환을 막지만,
+SPA 실행 컨텍스트를 장악한 XSS 자체를 막지는 않는다.
+
+`verify-pkce-flow-stages.sh`는 Web Crypto 단위 테스트, realm client 계약,
+authorization/token 요청의 필드를 함께 검사한다.

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/refresh-token-rotation.md

@@ -0,0 +1,16 @@
+# Refresh token rotation contract
+
+Realm 설정은 refresh token revoke를 활성화하고 재사용 허용 횟수를 0으로 둔다.
+SPA는 새 token set을 받은 즉시 이전 refresh token을 폐기한다.
+
+실제 AP1 E2E는 다음을 구분한다.
+
+- RT1로 refresh하면 RT2가 새로 발급된다.
+- 이미 소비한 RT1 재사용은 성공하면 안 된다.
+- 재사용 탐지 후 RT2까지 무효화할지는 Keycloak realm 정책과 동시 요청
+  상황에 따라 관찰한다.
+- refresh token revoke 이후 refresh는 실패한다.
+- 이미 발급된 stateless access JWT는 `exp`까지 유효할 수 있다.
+
+`verify-refresh-token-rotation-contract.sh`는 realm과 E2E assertions의 계약을
+빠르게 확인한다. 실제 token 수명주기 재현은 `verify-pattern1.sh`가 수행한다.

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 구문을
+검증한다.

docs/single-ec2-google-federation.md

@@ -0,0 +1,20 @@
+# Single EC2 with Google federation
+
+local-identity single-EC2 topology에 다음 네 요소가 추가된다.
+
+1. 고정 public HTTPS hostname
+2. trusted TLS/reverse proxy와 Keycloak public hostname
+3. Google OAuth client의 exact broker callback
+4. Keycloak Google IdP secret과 safe First Broker Login policy
+
+학습 profile은 Cloudflare named tunnel을 사용할 수 있어 EC2 inbound에
+Keycloak 8080을 열지 않는다. containerized cloudflared의 origin은
+`127.0.0.1`이 아니라 Compose service DNS의 reverse proxy다.
+
+실제 Google secret은 `.env`/secret store에만 두며 realm export나 Git에
+포함하지 않는다. credential이 없는 CI는 mock OIDC realm으로 broker 계약을
+검증하고, 실제 Google callback은 사용자 소유 credential/domain 환경에서
+별도 실행한다.
+
+`verify-single-ec2-google-profile.sh`는 tunnel, proxy headers, redirect URI,
+broker realm 계약을 묶어 검증한다.

docs/single-ec2-no-google.md

@@ -0,0 +1,20 @@
+# Single EC2, AP1, no Google
+
+한 VM의 Docker Compose에 PostgreSQL, Keycloak, Spring API, nginx SPA를 둔다.
+외부 진입점만 nginx/TLS proxy로 제한하고 Keycloak 8080, API 8081, PostgreSQL은
+loopback 또는 Docker private network에 둔다.
+
+```text
+Internet :443 -> TLS proxy/SPA
+                    |-> Spring API:8081
+Browser ----------->|-> Keycloak:8080 (public auth path만 proxy)
+Keycloak ----------> PostgreSQL:5432
+```
+
+이 profile은 Google credential과 tunnel이 필요 없다. EC2 보안 그룹은 22
+(관리 정책에 따른 제한), 80/443만 열고 container 내부 포트를 공개하지 않는다.
+backup 대상은 PostgreSQL 데이터와 realm/config/secret이며 Keycloak 개발
+모드 `start-dev`는 production에서 사용하지 않는다.
+
+`verify-single-ec2-no-google.sh`는 Compose rendering, loopback binding,
+AP1 local-identity 계약을 확인한다.

docs/spring-role-mapping.md

@@ -0,0 +1,16 @@
+# Keycloak realm roles to Spring authorization
+
+`realm_access.roles`의 각 문자열을 `ROLE_` prefix가 붙은 Spring authority로
+변환한다. `/api/admin`은 `hasRole("admin-role")` 계약이므로 최종 authority는
+`ROLE_admin-role`이다. `hasRole("ROLE_admin-role")`로 쓰면 prefix가 중복된다.
+
+검증은 세 층으로 구성된다.
+
+- converter 단위 테스트: role claim과 claim 부재
+- MockMvc: regular 403, admin 200
+- 실제 Authorization Code + PKCE login: Keycloak token의 realm role을
+  Spring Resource Server가 변환해 regular 403/admin 200을 반환
+
+```sh
+./scripts/verify-spring-role-mapping.sh
+```

docs/three-leg-trust-chain.md

@@ -0,0 +1,15 @@
+# Three-leg trust chain
+
+| Hop | 발급자/행위자 | 검증자 | 핵심 검증 |
+|---|---|---|---|
+| 1 | Google/mock IdP | Keycloak broker | signature, upstream issuer, client audience, expiry, nonce |
+| 2 | Keycloak | SPA | state, PKCE code binding, Keycloak issuer, token response |
+| 3 | Keycloak access token | Spring Resource Server | Keycloak signature/JWKS, issuer, expiry, API audience, roles |
+
+Keycloak은 upstream ID token을 그대로 SPA에 전달하지 않는다. upstream
+identity를 검증·연결한 뒤 자신의 realm key로 새 token을 발급한다. 그 결과
+backend의 trust store와 issuer 설정은 Google 로그인 여부와 무관하게 하나다.
+
+`verify-three-leg-trust-chain.sh`는 두 realm의 discovery issuer가 서로 다르고,
+Spring 코드가 main Keycloak issuer만 신뢰하는지 확인한다. 실제 hop 전체는
+`verify-federation-spa-zero-change.sh`로 검증한다.

e2e/federation-zero-change.mjs

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { chromium } from "playwright-core";
+
+const password = process.env.MOCK_GOOGLE_USER_PASSWORD;
+assert.ok(password);
+
+const browser = await chromium.launch({
+  executablePath: process.env.CHROME_BIN ?? "/usr/bin/google-chrome",
+  headless: true,
+  args: ["--no-sandbox"],
+});
+
+try {
+  const page = await browser.newPage();
+  const tokenResponse = page.waitForResponse((response) =>
+    response.url().includes("/protocol/openid-connect/token")
+    && response.request().postData()?.includes("grant_type=authorization_code"),
+  );
+
+  await page.goto("http://localhost:8088/");
+  await page.locator("#login").click();
+  await page.locator('a[href*="/broker/mock-google/login"]').click();
+  await page.waitForURL(/\/realms\/mock-google\//u);
+  await page.locator("#username").fill("mock-new-user");
+  await page.locator("#password").fill(password);
+  await page.locator("#kc-login").click();
+
+  const response = await tokenResponse;
+  assert.equal(response.status(), 200);
+  const token = (await response.json()).access_token;
+  const payload = JSON.parse(
+    Buffer.from(token.split(".")[1], "base64url").toString(),
+  );
+  assert.match(payload.preferred_username, /^mock-google\./u);
+  assert.ok(payload.aud.includes("keycloak-pattern-api"));
+
+  await page.waitForURL("http://localhost:8088/");
+  await page.locator('[data-authenticated="true"]').waitFor();
+  await page.locator("#call-api").click();
+  await page.waitForFunction(() =>
+    document.querySelector("#result")?.textContent.includes('"httpStatus": 200'),
+  );
+  console.log("Google federation verified with the unchanged AP1 SPA/API contract");
+} finally {
+  await browser.close();
+}

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,14 @@
+{
+  "name": "keycloak-pattern-e2e",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "test:pattern1": "node pattern1.mjs",
+    "test:role-mapping": "node role-mapping.mjs",
+    "test:federation-zero-change": "node federation-zero-change.mjs"
+  },
+  "devDependencies": {
+    "playwright-core": "1.62.0"
+  }
+}

e2e/pattern1.mjs

@@ -0,0 +1,210 @@
+import assert from "node:assert/strict";
+import { chromium } from "playwright-core";
+
+const username = process.env.E2E_USERNAME ?? "regular-user";
+const password = process.env.E2E_PASSWORD;
+const frontendUrl = "http://localhost:8088/";
+const tokenEndpoint =
+  "http://localhost:8080/realms/keycloak-patterns/protocol/openid-connect/token";
+const revokeEndpoint =
+  "http://localhost:8080/realms/keycloak-patterns/protocol/openid-connect/revoke";
+
+assert.ok(password, "E2E_PASSWORD must be set");
+
+async function login(page) {
+  await page.locator("#login").click();
+  await page.waitForURL(/localhost:8080/u);
+  await page.locator("#username").waitFor();
+
+  const tokenResponsePromise = page.waitForResponse((response) =>
+    response.url() === tokenEndpoint
+    && response.request().postData()?.includes("grant_type=authorization_code"),
+  );
+
+  await page.locator("#username").fill(username);
+  await page.locator("#password").fill(password);
+  await page.locator("#kc-login").click();
+
+  const tokenResponse = await tokenResponsePromise;
+  assert.equal(tokenResponse.status(), 200);
+  const tokenSet = await tokenResponse.json();
+  assert.ok(tokenSet.access_token);
+  assert.ok(tokenSet.refresh_token);
+  assert.ok(tokenSet.id_token);
+
+  await page.waitForURL(frontendUrl);
+  await page.locator('[data-authenticated="true"]').waitFor();
+  return tokenSet;
+}
+
+async function postForm(url, values) {
+  return fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(values),
+  });
+}
+
+async function refresh(refreshToken) {
+  return postForm(tokenEndpoint, {
+    grant_type: "refresh_token",
+    client_id: "spa-public",
+    refresh_token: refreshToken,
+  });
+}
+
+async function callResource(accessToken, url = "http://localhost:8081/api/me") {
+  return fetch(url, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+}
+
+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();
+  let authorizationUrl;
+
+  page.on("request", (request) => {
+    if (request.url().includes("/protocol/openid-connect/auth")) {
+      authorizationUrl = new URL(request.url());
+    }
+  });
+
+  await page.goto(frontendUrl);
+  const firstTokenSet = await login(page);
+
+  assert.equal(authorizationUrl?.searchParams.get("response_type"), "code");
+  assert.equal(authorizationUrl?.searchParams.get("code_challenge_method"), "S256");
+  assert.ok(authorizationUrl?.searchParams.get("code_challenge"));
+
+  await page.evaluate(() => {
+    const originalFetch = window.fetch.bind(window);
+    window.__xssProbe = { authorization: null };
+    window.fetch = (input, init = {}) => {
+      const headers = new Headers(
+        init.headers ?? (input instanceof Request ? input.headers : undefined),
+      );
+      const authorization = headers.get("Authorization");
+      if (authorization) {
+        window.__xssProbe.authorization = authorization;
+      }
+      return originalFetch(input, init);
+    };
+  });
+
+  await page.locator("#call-api").click();
+  await page.waitForFunction(() => {
+    const text = document.querySelector("#result")?.textContent ?? "";
+    return text.includes('"httpStatus": 200');
+  });
+
+  const capturedAuthorization = await page.evaluate(
+    () => window.__xssProbe.authorization,
+  );
+  assert.match(capturedAuthorization, /^Bearer /u);
+  const accessToken = capturedAuthorization.slice("Bearer ".length);
+  assert.equal(accessToken, firstTokenSet.access_token);
+
+  const payload = JSON.parse(
+    Buffer.from(accessToken.split(".")[1], "base64url").toString("utf8"),
+  );
+  const audiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+  assert.ok(audiences.includes("keycloak-pattern-api"));
+
+  const storageSnapshot = await page.evaluate(() => ({
+    localStorage: Object.values(localStorage),
+    sessionStorage: Object.values(sessionStorage),
+  }));
+  assert.equal(JSON.stringify(storageSnapshot).includes(accessToken), false);
+  assert.ok(capturedAuthorization);
+
+  if (process.env.WRONG_AUDIENCE_URL) {
+    assert.equal(
+      (await callResource(accessToken, process.env.WRONG_AUDIENCE_URL)).status,
+      401,
+    );
+  }
+  if (process.env.WRONG_ISSUER_URL) {
+    assert.equal(
+      (await callResource(accessToken, process.env.WRONG_ISSUER_URL)).status,
+      401,
+    );
+  }
+
+  const logoutRequestPromise = page.waitForRequest((request) =>
+    request.url().includes("/protocol/openid-connect/logout"),
+  );
+  await page.locator("#logout").click();
+  const logoutRequest = await logoutRequestPromise;
+  assert.ok(new URL(logoutRequest.url()).searchParams.get("id_token_hint"));
+  await page.waitForURL(frontendUrl);
+  await page.locator('[data-authenticated="false"]').waitFor();
+
+  const secondTokenSet = await login(page);
+  const rotatedResponse = await refresh(secondTokenSet.refresh_token);
+  assert.equal(rotatedResponse.status, 200);
+  const rotated = await rotatedResponse.json();
+  assert.ok(rotated.refresh_token);
+  assert.notEqual(rotated.refresh_token, secondTokenSet.refresh_token);
+
+  const reusedOldResponse = await refresh(secondTokenSet.refresh_token);
+  assert.notEqual(
+    reusedOldResponse.status,
+    200,
+    "a consumed refresh token must not be accepted again",
+  );
+
+  const rotatedAfterReuseResponse = await refresh(rotated.refresh_token);
+  const rotatedAfterReuseStatus = rotatedAfterReuseResponse.status;
+  assert.ok([200, 400, 401].includes(rotatedAfterReuseStatus));
+
+  assert.equal(
+    (await callResource(rotated.access_token)).status,
+    200,
+    "a locally validated access JWT remains usable until exp",
+  );
+
+  await context.clearCookies();
+  await page.reload();
+  await page.locator('[data-authenticated="false"]').waitFor();
+  const thirdTokenSet = await login(page);
+
+  const revokeResponse = await postForm(revokeEndpoint, {
+    token: thirdTokenSet.refresh_token,
+    token_type_hint: "refresh_token",
+    client_id: "spa-public",
+  });
+  assert.equal(revokeResponse.status, 200);
+  assert.notEqual((await refresh(thirdTokenSet.refresh_token)).status, 200);
+  assert.equal(
+    (await callResource(thirdTokenSet.access_token)).status,
+    200,
+    "refresh revoke is not an immediate deny-list for a stateless access JWT",
+  );
+
+  await page.reload();
+  await page.locator('[data-authenticated="false"]').waitFor();
+  assert.equal(
+    await page.evaluate(
+      (token) => JSON.stringify({
+        localStorage: Object.values(localStorage),
+        sessionStorage: Object.values(sessionStorage),
+      }).includes(token),
+      thirdTokenSet.access_token,
+    ),
+    false,
+  );
+
+  console.log(
+    "pattern1 verified: PKCE, aud/iss negatives, memory/XSS boundary, logout, RT rotation/reuse, revoke-vs-stateless JWT"
+      + ` (RT2 after RT1 reuse: ${rotatedAfterReuseStatus})`,
+  );
+} finally {
+  await browser.close();
+}

e2e/role-mapping.mjs

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { chromium } from "playwright-core";
+
+const keycloakUrl = "http://localhost:8080";
+const frontendUrl = "http://localhost:8088/";
+
+async function accessToken(browser, username, password) {
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  await page.goto(frontendUrl);
+  const tokenResponse = page.waitForResponse((response) =>
+    response.url().includes("/protocol/openid-connect/token")
+    && response.request().postData()?.includes("grant_type=authorization_code"),
+  );
+  await page.locator("#login").click();
+  await page.locator("#username").fill(username);
+  await page.locator("#password").fill(password);
+  await page.locator("#kc-login").click();
+  const response = await tokenResponse;
+  assert.equal(response.status(), 200);
+  const token = (await response.json()).access_token;
+  await context.close();
+  return token;
+}
+
+async function adminStatus(token) {
+  return (
+    await fetch("http://localhost:8081/api/admin", {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+  ).status;
+}
+
+const regularPassword = process.env.REGULAR_USER_PASSWORD;
+const adminPassword = process.env.ADMIN_USER_PASSWORD;
+assert.ok(regularPassword && adminPassword);
+
+const browser = await chromium.launch({
+  executablePath: process.env.CHROME_BIN ?? "/usr/bin/google-chrome",
+  headless: true,
+  args: ["--no-sandbox"],
+});
+
+try {
+  const regularToken = await accessToken(
+    browser,
+    "regular-user",
+    regularPassword,
+  );
+  const regularPayload = JSON.parse(
+    Buffer.from(regularToken.split(".")[1], "base64url").toString(),
+  );
+  assert.ok(regularPayload.realm_access.roles.includes("user-role"));
+  assert.equal(await adminStatus(regularToken), 403);
+
+  const adminToken = await accessToken(browser, "admin-user", adminPassword);
+  const adminPayload = JSON.parse(
+    Buffer.from(adminToken.split(".")[1], "base64url").toString(),
+  );
+  assert.ok(adminPayload.realm_access.roles.includes("admin-role"));
+  assert.equal(await adminStatus(adminToken), 200);
+  console.log("Spring RBAC verified: realm role -> ROLE_ authority -> 403/200");
+} finally {
+  await browser.close();
+}

frontend/Dockerfile

@@ -1,4 +1,16 @@
+FROM node:24-alpine AS build
+
+WORKDIR /workspace
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY src ./src
+COPY test ./test
+RUN npm test && npm run build
+
 FROM nginx:1.29-alpine
 
 COPY nginx.conf /etc/nginx/conf.d/default.conf
 COPY index.html /usr/share/nginx/html/index.html
+COPY --from=build /workspace/dist/app.js /usr/share/nginx/html/app.js

frontend/index.html

@@ -3,31 +3,66 @@
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Keycloak Authentication Patterns</title>
+  <meta name="referrer" content="no-referrer">
+  <title>AP1 · SPA Direct + Resource Server</title>
   <style>
     :root {
       color-scheme: light dark;
       font-family: system-ui, sans-serif;
     }
     body {
-      max-width: 48rem;
+      max-width: 56rem;
-      margin: 8vh auto;
+      margin: 6vh auto;
       padding: 0 1.5rem;
-      line-height: 1.6;
+      line-height: 1.55;
+    }
+    button {
+      margin: 0 0.5rem 0.5rem 0;
+      padding: 0.6rem 0.9rem;
+      cursor: pointer;
+    }
+    code, pre {
+      border-radius: 0.35rem;
+      background: color-mix(in srgb, CanvasText 9%, Canvas);
     }
     code {
-      padding: 0.15rem 0.35rem;
+      padding: 0.1rem 0.3rem;
-      border-radius: 0.25rem;
+    }
-      background: color-mix(in srgb, CanvasText 10%, Canvas);
+    pre {
+      min-height: 8rem;
+      padding: 1rem;
+      overflow: auto;
+      white-space: pre-wrap;
+    }
+    .notice {
+      border-left: 0.3rem solid #e09f3e;
+      padding-left: 1rem;
     }
   </style>
 </head>
 <body>
-  <h1>Keycloak Authentication Patterns</h1>
+  <main>
-  <p>공통 Docker Compose baseline이 실행 중입니다.</p>
+    <h1>AP1 · SPA Direct + Resource Server</h1>
-  <p>
+    <p>
-    공개 API는 <code>/api/public</code>, 보호 API는
+      바닐라 JavaScript SPA가 <code>spa-public</code> client로 Authorization
-    <code>/api/me</code>에서 확인할 수 있습니다.
+      Code + PKCE를 수행하고, access token을 직접 Spring Resource Server에
-  </p>
+      전달합니다.
+    </p>
+    <p class="notice">
+      access/refresh token은 메모리에만 존재합니다. 새로고침하면 사라지는 것이
+      이 패턴의 의도된 보안 경계입니다.
+    </p>
+
+    <section>
+      <button id="login" type="button">Keycloak 로그인</button>
+      <button id="call-api" type="button" disabled>보호 API 호출</button>
+      <button id="pkce-demo" type="button">수동 PKCE 생성</button>
+      <button id="logout" type="button" disabled>로그아웃</button>
+    </section>
+
+    <p id="session-state" data-authenticated="false">세션 확인 중…</p>
+    <pre id="result" aria-live="polite"></pre>
+  </main>
+  <script type="module" src="/app.js"></script>
 </body>
 </html>

frontend/nginx.conf

@@ -21,6 +21,7 @@ server {
     }
 
     location / {
+        add_header Cache-Control "no-store";
         try_files $uri $uri/ /index.html;
     }
 }

frontend/package-lock.json

@@ -0,0 +1,523 @@
+{
+  "name": "keycloak-pattern1-spa",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "keycloak-pattern1-spa",
+      "version": "1.0.0",
+      "dependencies": {
+        "oidc-client-ts": "3.5.0"
+      },
+      "devDependencies": {
+        "esbuild": "0.28.1"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz",
+      "integrity": "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.1.tgz",
+      "integrity": "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.1.tgz",
+      "integrity": "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.1.tgz",
+      "integrity": "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.1.tgz",
+      "integrity": "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.1.tgz",
+      "integrity": "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.1.tgz",
+      "integrity": "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.1.tgz",
+      "integrity": "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.1.tgz",
+      "integrity": "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.1.tgz",
+      "integrity": "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.1.tgz",
+      "integrity": "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.1.tgz",
+      "integrity": "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.1.tgz",
+      "integrity": "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.1.tgz",
+      "integrity": "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.1.tgz",
+      "integrity": "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.1.tgz",
+      "integrity": "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.1.tgz",
+      "integrity": "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.1.tgz",
+      "integrity": "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.1.tgz",
+      "integrity": "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.1.tgz",
+      "integrity": "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
+      "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.1",
+        "@esbuild/android-arm": "0.28.1",
+        "@esbuild/android-arm64": "0.28.1",
+        "@esbuild/android-x64": "0.28.1",
+        "@esbuild/darwin-arm64": "0.28.1",
+        "@esbuild/darwin-x64": "0.28.1",
+        "@esbuild/freebsd-arm64": "0.28.1",
+        "@esbuild/freebsd-x64": "0.28.1",
+        "@esbuild/linux-arm": "0.28.1",
+        "@esbuild/linux-arm64": "0.28.1",
+        "@esbuild/linux-ia32": "0.28.1",
+        "@esbuild/linux-loong64": "0.28.1",
+        "@esbuild/linux-mips64el": "0.28.1",
+        "@esbuild/linux-ppc64": "0.28.1",
+        "@esbuild/linux-riscv64": "0.28.1",
+        "@esbuild/linux-s390x": "0.28.1",
+        "@esbuild/linux-x64": "0.28.1",
+        "@esbuild/netbsd-arm64": "0.28.1",
+        "@esbuild/netbsd-x64": "0.28.1",
+        "@esbuild/openbsd-arm64": "0.28.1",
+        "@esbuild/openbsd-x64": "0.28.1",
+        "@esbuild/openharmony-arm64": "0.28.1",
+        "@esbuild/sunos-x64": "0.28.1",
+        "@esbuild/win32-arm64": "0.28.1",
+        "@esbuild/win32-ia32": "0.28.1",
+        "@esbuild/win32-x64": "0.28.1"
+      }
+    },
+    "node_modules/jwt-decode": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/jwt-decode/-/jwt-decode-4.0.0.tgz",
+      "integrity": "sha512-+KJGIyHgkGuIq3IEBNftfhW/LfWhXUIY6OmyVWjliu5KH1y0fw7VQ8YndE2O4qZdMSd9SqbnC8GOcZEy0Om7sA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/oidc-client-ts": {
+      "version": "3.5.0",
+      "resolved": "https://registry.npmjs.org/oidc-client-ts/-/oidc-client-ts-3.5.0.tgz",
+      "integrity": "sha512-l2q8l9CTCTOlbX+AnK4p3M+4CEpKpyQhle6blQkdFhm0IsBqsxm15bYaSa11G7pWdsYr6epdsRZxJpCyCRbT8A==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "jwt-decode": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}

frontend/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "keycloak-pattern1-spa",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/app.js --bundle --format=esm --outfile=dist/app.js --minify --sourcemap",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "oidc-client-ts": "3.5.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.1"
+  }
+}

frontend/src/account-linking.js

@@ -0,0 +1,38 @@
+function base64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+}
+
+export async function createAccountLinkUrl({
+  keycloakBaseUrl,
+  realm,
+  provider,
+  clientId,
+  redirectUri,
+  sessionState,
+  issuedFor,
+  nonce = crypto.randomUUID(),
+  cryptoApi = crypto,
+}) {
+  const material = `${nonce}${sessionState}${issuedFor}${provider}`;
+  const digest = await cryptoApi.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(material),
+  );
+  const url = new URL(
+    `${keycloakBaseUrl}/realms/${realm}/broker/${provider}/link`,
+  );
+  url.search = new URLSearchParams({
+    nonce,
+    hash: base64Url(new Uint8Array(digest)),
+    client_id: clientId,
+    redirect_uri: redirectUri,
+  });
+  return url;
+}

frontend/src/app.js

@@ -0,0 +1,131 @@
+import {
+  InMemoryWebStorage,
+  UserManager,
+  WebStorageStateStore,
+} from "oidc-client-ts";
+
+import { createPkcePair } from "./pkce.js";
+
+const authority = "http://localhost:8080/realms/keycloak-patterns";
+const backendBaseUrl = "http://localhost:8081";
+
+const userManager = new UserManager({
+  authority,
+  client_id: "spa-public",
+  redirect_uri: "http://localhost:8088/callback.html",
+  post_logout_redirect_uri: "http://localhost:8088/",
+  response_type: "code",
+  scope: "openid profile email",
+  automaticSilentRenew: true,
+  monitorSession: false,
+  loadUserInfo: false,
+  userStore: new WebStorageStateStore({
+    store: new InMemoryWebStorage(),
+  }),
+  stateStore: new WebStorageStateStore({
+    store: window.sessionStorage,
+  }),
+});
+
+const loginButton = document.querySelector("#login");
+const logoutButton = document.querySelector("#logout");
+const apiButton = document.querySelector("#call-api");
+const pkceButton = document.querySelector("#pkce-demo");
+const sessionState = document.querySelector("#session-state");
+const result = document.querySelector("#result");
+
+let currentUser = null;
+
+function renderJson(value) {
+  result.textContent = JSON.stringify(value, null, 2);
+}
+
+function tokenMetadata(user) {
+  return {
+    subject: user.profile.sub,
+    username: user.profile.preferred_username,
+    expiresAt: new Date(user.expires_at * 1000).toISOString(),
+    accessTokenHeldBy: "browser memory",
+    refreshTokenHeldBy: user.refresh_token ? "browser memory" : "not issued",
+  };
+}
+
+function renderSession(user) {
+  currentUser = user;
+  const authenticated = Boolean(user && !user.expired);
+  sessionState.dataset.authenticated = String(authenticated);
+  sessionState.textContent = authenticated
+    ? `${user.profile.preferred_username} 로그인됨 · token은 메모리에만 보관`
+    : "로그인되지 않음 · 브라우저 저장소에 token 없음";
+  loginButton.disabled = authenticated;
+  logoutButton.disabled = !authenticated;
+  apiButton.disabled = !authenticated;
+
+  if (authenticated) {
+    renderJson(tokenMetadata(user));
+  }
+}
+
+async function finishSigninCallback() {
+  const params = new URLSearchParams(window.location.search);
+  const isCallback = window.location.pathname === "/callback.html"
+    && (params.has("code") || params.has("error"));
+
+  if (!isCallback) {
+    return null;
+  }
+
+  const user = await userManager.signinRedirectCallback();
+  window.history.replaceState({}, document.title, "/");
+  return user;
+}
+
+async function callProtectedApi() {
+  if (!currentUser || currentUser.expired) {
+    throw new Error("로그인이 필요합니다.");
+  }
+
+  const response = await fetch(`${backendBaseUrl}/api/me`, {
+    headers: {
+      Authorization: `Bearer ${currentUser.access_token}`,
+    },
+  });
+  const body = await response.json();
+  renderJson({
+    httpStatus: response.status,
+    resourceServerResponse: body,
+    tokenBoundary: tokenMetadata(currentUser),
+  });
+
+  if (!response.ok) {
+    throw new Error(`보호 API가 ${response.status}를 반환했습니다.`);
+  }
+}
+
+loginButton.addEventListener("click", () => userManager.signinRedirect());
+logoutButton.addEventListener("click", () => userManager.signoutRedirect());
+apiButton.addEventListener("click", () => {
+  callProtectedApi().catch((error) => renderJson({ error: error.message }));
+});
+pkceButton.addEventListener("click", () => {
+  createPkcePair()
+    .then(({ verifier, challenge, method }) => renderJson({
+      method,
+      verifierLength: verifier.length,
+      challengeLength: challenge.length,
+      note: "실제 로그인에서는 oidc-client-ts가 같은 S256 단계를 수행합니다.",
+    }))
+    .catch((error) => renderJson({ error: error.message }));
+});
+
+userManager.events.addUserLoaded(renderSession);
+userManager.events.addUserUnloaded(() => renderSession(null));
+userManager.events.addAccessTokenExpired(() => renderSession(null));
+
+try {
+  const callbackUser = await finishSigninCallback();
+  renderSession(callbackUser ?? await userManager.getUser());
+} catch (error) {
+  renderSession(null);
+  renderJson({ error: error.message });
+}

frontend/src/pkce.js

@@ -0,0 +1,26 @@
+function base64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/u, "");
+}
+
+export async function createPkcePair(cryptoApi = globalThis.crypto) {
+  const verifierBytes = new Uint8Array(32);
+  cryptoApi.getRandomValues(verifierBytes);
+  const verifier = base64Url(verifierBytes);
+  const digest = await cryptoApi.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(verifier),
+  );
+
+  return {
+    verifier,
+    challenge: base64Url(new Uint8Array(digest)),
+    method: "S256",
+  };
+}

frontend/test/account-linking.test.mjs

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+const { createAccountLinkUrl } = await import("../src/account-linking.js");
+
+test("creates a signed client-initiated account-link URL", async () => {
+  const url = await createAccountLinkUrl({
+    keycloakBaseUrl: "https://auth.example.test",
+    realm: "keycloak-patterns",
+    provider: "google",
+    clientId: "spa-public",
+    redirectUri: "https://app.example.test/settings/identity",
+    sessionState: "session-state",
+    issuedFor: "spa-public",
+    nonce: "fixed-nonce",
+  });
+
+  assert.equal(
+    url.pathname,
+    "/realms/keycloak-patterns/broker/google/link",
+  );
+  assert.equal(url.searchParams.get("client_id"), "spa-public");
+  assert.equal(url.searchParams.get("nonce"), "fixed-nonce");
+  assert.match(url.searchParams.get("hash"), /^[A-Za-z0-9_-]{43}$/u);
+});

frontend/test/pkce.test.mjs

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import { webcrypto } from "node:crypto";
+import test from "node:test";
+
+globalThis.btoa = (value) => Buffer.from(value, "binary").toString("base64");
+
+const { createPkcePair } = await import("../src/pkce.js");
+
+test("manual PKCE helper creates an RFC 7636 S256 pair", async () => {
+  const pair = await createPkcePair(webcrypto);
+
+  assert.equal(pair.method, "S256");
+  assert.equal(pair.verifier.length, 43);
+  assert.equal(pair.challenge.length, 43);
+  assert.match(pair.verifier, /^[A-Za-z0-9_-]+$/u);
+  assert.match(pair.challenge, /^[A-Za-z0-9_-]+$/u);
+  assert.notEqual(pair.verifier, pair.challenge);
+});

google-e2e/claim-to-role.mjs

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { createHash, randomBytes } from "node:crypto";
+import { chromium } from "playwright-core";
+
+const keycloakUrl = process.env.KEYCLOAK_URL ?? "http://localhost:8080";
+const password = process.env.MOCK_GOOGLE_USER_PASSWORD;
+assert.ok(password);
+
+const verifier = randomBytes(48).toString("base64url");
+const challenge = createHash("sha256").update(verifier).digest("base64url");
+const redirectUri = "http://localhost:8088/";
+
+const browser = await chromium.launch({
+  executablePath: process.env.CHROME_BIN ?? "/usr/bin/google-chrome",
+  headless: true,
+  args: ["--no-sandbox"],
+});
+
+try {
+  const page = await browser.newPage();
+  const authorizationUrl = new URL(
+    `${keycloakUrl}/realms/keycloak-patterns/protocol/openid-connect/auth`,
+  );
+  authorizationUrl.search = new URLSearchParams({
+    client_id: "spa-public",
+    redirect_uri: redirectUri,
+    response_type: "code",
+    scope: "openid profile email",
+    state: crypto.randomUUID(),
+    nonce: crypto.randomUUID(),
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    kc_idp_hint: "mock-google",
+    prompt: "login",
+  });
+
+  await page.goto(authorizationUrl.toString());
+  await page.waitForURL(/\/realms\/mock-google\//u);
+  await page.locator("#username").fill("mock-new-user");
+  await page.locator("#password").fill(password);
+  await page.locator("#kc-login").click();
+  await page.waitForURL(/localhost:8088\/\?.*code=/u);
+
+  const code = new URL(page.url()).searchParams.get("code");
+  assert.ok(code);
+  const response = await fetch(
+    `${keycloakUrl}/realms/keycloak-patterns/protocol/openid-connect/token`,
+    {
+      method: "POST",
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: "spa-public",
+        redirect_uri: redirectUri,
+        code,
+        code_verifier: verifier,
+      }),
+    },
+  );
+  assert.equal(response.status, 200);
+  const tokens = await response.json();
+  const payload = JSON.parse(
+    Buffer.from(tokens.access_token.split(".")[1], "base64url").toString(),
+  );
+  assert.ok(payload.realm_access.roles.includes("employee-role"));
+  console.log("Claim-to-role verified: hd=example.test -> employee-role");
+} finally {
+  await browser.close();
+}

google-e2e/package.json

@@ -5,7 +5,9 @@
   "type": "module",
   "scripts": {
     "test:first-broker": "node first-broker-login.mjs",
-    "test:claim-mapping": "node claim-mapping.mjs"
+    "test:claim-mapping": "node claim-mapping.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

@@ -24,6 +24,10 @@
       {
         "name": "user-role",
         "description": "Regular authenticated user role"
+      },
+      {
+        "name": "employee-role",
+        "description": "Assigned to brokered identities whose hosted-domain claim is example.test"
       }
     ]
   },
@@ -51,7 +55,22 @@
       "attributes": {
         "pkce.code.challenge.method": "S256",
         "post.logout.redirect.uris": "http://localhost:8088/*##http://127.0.0.1:8088/*"
-      }
+      },
+      "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": "token-mediating-confidential",
@@ -213,6 +232,17 @@
         "claim": "hd",
         "user.attribute": "hd"
       }
+    },
+    {
+      "name": "mock-google-example-domain-role",
+      "identityProviderAlias": "mock-google",
+      "identityProviderMapper": "oidc-role-idp-mapper",
+      "config": {
+        "syncMode": "INHERIT",
+        "claim": "hd",
+        "claim.value": "example.test",
+        "role": "employee-role"
+      }
     }
   ],
   "users": [

scripts/configure-google-idp.sh

@@ -144,6 +144,10 @@ upsert_mapper \
   "google-hosted-domain" \
   "oidc-user-attribute-idp-mapper" \
   '{"syncMode":"INHERIT","claim":"hd","user.attribute":"hd"}'
+upsert_mapper \
+  "google-example-domain-role" \
+  "oidc-role-idp-mapper" \
+  '{"syncMode":"INHERIT","claim":"hd","claim.value":"example.test","role":"employee-role"}'
 
 echo "Google Identity Provider $action for realm '$realm'"
 echo "Register this exact Google redirect URI:"

scripts/validate-realm.py

@@ -70,6 +70,18 @@ def validate(path: Path, runtime: bool) -> None:
         spa.get("attributes", {}).get("pkce.code.challenge.method") == "S256",
         "spa-public must enforce PKCE S256",
     )
+    audience_mappers = [
+        mapper
+        for mapper in spa.get("protocolMappers", [])
+        if mapper.get("protocolMapper") == "oidc-audience-mapper"
+    ]
+    if not runtime:
+        require(len(audience_mappers) == 1, "spa-public must declare one audience mapper")
+        require(
+            audience_mappers[0].get("config", {}).get("included.custom.audience")
+            == "keycloak-pattern-api",
+            "spa-public access token must target keycloak-pattern-api",
+        )
 
     for client_id, placeholder in CONFIDENTIAL_CLIENTS.items():
         client = clients[client_id]

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-federation-spa-zero-change.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env sh
+set -eu
+
+set -a
+. ./.env
+set +a
+
+./scripts/set-first-broker-login-mode.sh secure
+npm --prefix e2e ci
+MOCK_GOOGLE_USER_PASSWORD="$MOCK_GOOGLE_USER_PASSWORD" \
+  npm --prefix e2e run test:federation-zero-change

scripts/verify-google-claim-to-role.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+set -eu
+
+set -a
+. ./.env
+set +a
+
+./scripts/configure-broker-user-profile.sh >/dev/null
+./scripts/set-first-broker-login-mode.sh secure
+
+docker compose exec -T keycloak \
+  /opt/keycloak/bin/kcadm.sh create roles -r keycloak-patterns \
+  -s name=employee-role \
+  -s 'description=Assigned from the upstream hd claim' >/dev/null 2>&1 || true
+
+cd google-e2e
+npm install --ignore-scripts
+npm run test:claim-to-role

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-internal-spa-google-contract.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+set -eu
+
+./scripts/verify-google-broker-config.sh
+./scripts/verify-federation-spa-zero-change.sh
+echo "AP1 Google-federated profile verified"

scripts/verify-internal-spa-no-google-contract.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+set -eu
+
+jq -e '
+  (.clients[] | select(.clientId == "spa-public")
+    | .publicClient == true
+      and .attributes["pkce.code.challenge.method"] == "S256")
+  and
+  ([.users[].username] | index("regular-user") != null)
+' keycloak/import/keycloak-patterns-realm.json >/dev/null
+
+npm --prefix frontend test
+echo "AP1 local-identity profile verified without a Google dependency"

scripts/verify-pattern1.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ ! -f .env ]; then
+  echo "missing .env; copy .env.example and set local-only values" >&2
+  exit 1
+fi
+
+set -a
+. ./.env
+set +a
+
+docker compose down --volumes --remove-orphans
+docker compose up --build -d --wait
+docker compose --profile diagnostics up -d --wait \
+  app-wrong-audience \
+  app-wrong-issuer
+
+npm --prefix e2e ci
+E2E_USERNAME=regular-user \
+E2E_PASSWORD="$REGULAR_USER_PASSWORD" \
+WRONG_AUDIENCE_URL=http://localhost:18081/api/me \
+WRONG_ISSUER_URL=http://localhost:18082/api/me \
+  npm --prefix e2e run test:pattern1
+
+echo "AP1 verified end to end"

scripts/verify-pkce-flow-stages.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+set -eu
+
+npm --prefix frontend ci
+npm --prefix frontend test
+
+jq -e '
+  .clients[]
+  | select(.clientId == "spa-public")
+  | .publicClient == true
+    and .standardFlowEnabled == true
+    and .implicitFlowEnabled == false
+    and .directAccessGrantsEnabled == false
+    and .attributes["pkce.code.challenge.method"] == "S256"
+' keycloak/import/keycloak-patterns-realm.json >/dev/null
+
+rg -q 'response_type: "code"' frontend/src/app.js
+rg -q 'new InMemoryWebStorage' frontend/src/app.js
+rg -Fq 'cryptoApi.subtle.digest(' frontend/src/pkce.js
+rg -Fq '"SHA-256"' frontend/src/pkce.js
+echo "PKCE stages verified: verifier -> S256 challenge -> code -> verifier exchange"

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-refresh-token-rotation-contract.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+set -eu
+
+jq -e '
+  .revokeRefreshToken == true
+  and .refreshTokenMaxReuse == 0
+  and .accessTokenLifespan <= 300
+' keycloak/import/keycloak-patterns-realm.json >/dev/null
+
+rg -Fq 'assert.notEqual(rotated.refresh_token, secondTokenSet.refresh_token)' \
+  e2e/pattern1.mjs
+rg -Fq 'a consumed refresh token must not be accepted again' e2e/pattern1.mjs
+rg -Fq 'refresh revoke is not an immediate deny-list' e2e/pattern1.mjs
+
+echo "Refresh rotation/reuse/revocation contract verified"
+echo "Run ./scripts/verify-pattern1.sh for the destructive live-token E2E"

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"

scripts/verify-single-ec2-google-profile.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env sh
+set -eu
+
+./scripts/verify-public-tunnel-config.sh
+./scripts/verify-reverse-proxy-headers.sh
+./scripts/verify-google-redirect-uri-policy.sh
+./scripts/verify-google-broker-config.sh
+echo "Single-EC2 Google federation deployment profile verified"

scripts/verify-single-ec2-no-google.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env sh
+set -eu
+
+rendered="$(docker compose config --format json)"
+printf '%s\n' "$rendered" | jq -e '
+  (.services.keycloak.ports[] | .host_ip == "127.0.0.1" and .target == 8080)
+  and
+  (.services.app.ports[] | .host_ip == "127.0.0.1" and .target == 8081)
+  and
+  (.networks["keycloak-net"].driver == "bridge")
+' >/dev/null
+
+./scripts/verify-internal-spa-no-google-contract.sh
+echo "Single-EC2 local-identity topology verified"

scripts/verify-spring-role-mapping.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+set -eu
+
+set -a
+. ./.env
+set +a
+
+docker compose down --volumes --remove-orphans
+docker compose up --build -d --wait
+npm --prefix e2e ci
+REGULAR_USER_PASSWORD="$REGULAR_USER_PASSWORD" \
+ADMIN_USER_PASSWORD="$ADMIN_USER_PASSWORD" \
+  npm --prefix e2e run test:role-mapping

scripts/verify-three-leg-trust-chain.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+set -eu
+
+base="${KEYCLOAK_URL:-http://localhost:8080}"
+main_issuer="$base/realms/keycloak-patterns"
+mock_issuer="$base/realms/mock-google"
+
+test "$(curl -fsS "$main_issuer/.well-known/openid-configuration" | jq -r .issuer)" \
+  = "$main_issuer"
+test "$(curl -fsS "$mock_issuer/.well-known/openid-configuration" | jq -r .issuer)" \
+  = "$mock_issuer"
+
+rg -Fq 'SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI:' docker-compose.yml
+if rg -qi 'accounts\\.google\\.com|realms/mock-google' backend/src/main; then
+  echo "backend must trust only the Keycloak issuer, not the upstream IdP" >&2
+  exit 1
+fi
+
+echo "Three-leg trust anchors verified: upstream -> Keycloak -> Resource Server"