docs: define AP1 Google federation profile

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/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`가 담당한다.

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.json

@@ -5,7 +5,8 @@
   "type": "module",
   "scripts": {
     "test:pattern1": "node pattern1.mjs",
-    "test:role-mapping": "node role-mapping.mjs"
+    "test:role-mapping": "node role-mapping.mjs",
+    "test:federation-zero-change": "node federation-zero-change.mjs"
   },
   "devDependencies": {
     "playwright-core": "1.62.0"

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-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"