feat: map broker claims to realm roles

.gitignore

@@ -6,5 +6,6 @@
 backend/target/
 build/
 e2e/node_modules/
+google-e2e/node_modules/
 frontend/node_modules/
 frontend/dist/

docs/first-broker-login-security.md

@@ -0,0 +1,27 @@
+# First Broker Login security
+
+Keycloak 26.7.0's built-in `first broker login` flow does **not** silently
+auto-link by email. It contains:
+
+- `Create User If Unique`
+- `Handle Existing Account`
+- `Confirm link existing account`
+- email verification or re-authentication ownership proof
+
+`Automatically set existing user` is an explicit, dangerous opt-in. The local
+acceptance harness copies the built-in flow, enables AutoLink, disables the
+ownership-proof branch, and signs in through a controllable OIDC account whose
+email collides with `regular-user`. It verifies that the external identity is
+attached without proof. The harness then assigns the original built-in flow,
+repeats the login, observes the existing-account confirmation page, and verifies
+that no federated identity was attached.
+
+Run after the stack is healthy:
+
+```bash
+./scripts/verify-first-broker-login.sh
+```
+
+The vulnerable flow remains only as a disabled learning artifact. The
+`mock-google` provider is always returned to the secure built-in flow at the end
+of the verification.

docs/google-claim-mapping.md

@@ -0,0 +1,23 @@
+# Google claim and identity mapping
+
+The broker uses the upstream OIDC `sub` as the stable federated identity key.
+Email is a mutable profile attribute and is never the external identity key.
+
+The default mapping policy is:
+
+| Upstream claim | Keycloak target |
+|---|---|
+| `sub` | stable username `${ALIAS}.${CLAIM.sub}` and federated identity ID |
+| `email` | email |
+| `given_name` | first name |
+| `family_name` | last name |
+| `picture` | custom `picture` attribute |
+| `hd` | custom `hd` attribute |
+
+The Identity Provider uses `syncMode=IMPORT`: profile values are imported on
+first login and later local edits are not overwritten on every login. `FORCE`
+is an explicit alternative when upstream freshness is more important.
+
+`./scripts/verify-google-claim-mapping.sh` signs in through the controllable
+OIDC realm and verifies the resulting Keycloak user, custom attributes, stable
+subject-derived username, and federated identity record.

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`를 차례로 확인한다.

google-e2e/claim-mapping.mjs

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import { chromium } from "playwright-core";
+
+const keycloakUrl = 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(
+    `${keycloakUrl}/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 usersByEmail(token) {
+  const response = await fetch(
+    `${keycloakUrl}/admin/realms/keycloak-patterns/users?email=${encodeURIComponent(
+      "broker-new-user@example.test",
+    )}&exact=true`,
+    { headers: { Authorization: `Bearer ${token}` } },
+  );
+  assert.equal(response.status, 200);
+  return response.json();
+}
+
+async function userById(token, userId) {
+  const response = await fetch(
+    `${keycloakUrl}/admin/realms/keycloak-patterns/users/${userId}`,
+    { headers: { Authorization: `Bearer ${token}` } },
+  );
+  assert.equal(response.status, 200);
+  return response.json();
+}
+
+async function removePreviousUser(token) {
+  for (const user of await usersByEmail(token)) {
+    const response = await fetch(
+      `${keycloakUrl}/admin/realms/keycloak-patterns/users/${user.id}`,
+      {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${token}` },
+      },
+    );
+    assert.equal(response.status, 204);
+  }
+}
+
+async function brokerLogin(page) {
+  const url = new URL(
+    `${keycloakUrl}/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);
+}
+
+const token = await adminToken();
+await removePreviousUser(token);
+
+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();
+  await brokerLogin(page);
+
+  const users = await usersByEmail(token);
+  assert.equal(users.length, 1);
+  const user = await userById(token, users[0].id);
+  assert.match(user.username, /^mock-google\.[0-9a-f-]+$/u);
+  assert.equal(user.firstName, "Broker");
+  assert.equal(user.lastName, "New");
+  assert.deepEqual(user.attributes.picture, [
+    "https://images.example.test/mock-user.png",
+  ]);
+  assert.deepEqual(user.attributes.hd, ["example.test"]);
+
+  const identitiesResponse = await fetch(
+    `${keycloakUrl}/admin/realms/keycloak-patterns/users/${user.id}/federated-identity`,
+    { headers: { Authorization: `Bearer ${token}` } },
+  );
+  assert.equal(identitiesResponse.status, 200);
+  const identities = await identitiesResponse.json();
+  assert.equal(identities.length, 1);
+  assert.equal(identities[0].identityProvider, "mock-google");
+  assert.ok(identities[0].userId);
+
+  console.log(
+    "Google claim mapping verified: stable sub username, profile attributes, federated identity",
+  );
+} finally {
+  await browser.close();
+}

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/first-broker-login.mjs

@@ -0,0 +1,124 @@
+import assert from "node:assert/strict";
+import { chromium } from "playwright-core";
+
+const expectation = process.env.FIRST_BROKER_EXPECTATION;
+assert.ok(
+  expectation === "vulnerable" || expectation === "secure",
+  "FIRST_BROKER_EXPECTATION must be vulnerable or secure",
+);
+
+const keycloakUrl = 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 body = new URLSearchParams({
+    client_id: "admin-cli",
+    grant_type: "password",
+    username: adminUsername,
+    password: adminPassword,
+  });
+  const response = await fetch(
+    `${keycloakUrl}/realms/master/protocol/openid-connect/token`,
+    { method: "POST", body },
+  );
+  assert.equal(response.status, 200);
+  return (await response.json()).access_token;
+}
+
+async function regularUser(token) {
+  const response = await fetch(
+    `${keycloakUrl}/admin/realms/keycloak-patterns/users?username=regular-user&exact=true`,
+    { headers: { Authorization: `Bearer ${token}` } },
+  );
+  assert.equal(response.status, 200);
+  const users = await response.json();
+  assert.equal(users.length, 1);
+  return users[0];
+}
+
+async function federatedIdentities(token, userId) {
+  const response = await fetch(
+    `${keycloakUrl}/admin/realms/keycloak-patterns/users/${userId}/federated-identity`,
+    { headers: { Authorization: `Bearer ${token}` } },
+  );
+  assert.equal(response.status, 200);
+  return response.json();
+}
+
+async function removeMockLink(token, userId) {
+  const identities = await federatedIdentities(token, userId);
+  if (identities.some(({ identityProvider }) => identityProvider === "mock-google")) {
+    const response = await fetch(
+      `${keycloakUrl}/admin/realms/keycloak-patterns/users/${userId}/federated-identity/mock-google`,
+      {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${token}` },
+      },
+    );
+    assert.equal(response.status, 204);
+  }
+}
+
+const token = await adminToken();
+const user = await regularUser(token);
+await removeMockLink(token, user.id);
+
+const browser = await chromium.launch({
+  executablePath: process.env.CHROME_BIN ?? "/usr/bin/google-chrome",
+  headless: true,
+  args: ["--no-sandbox"],
+});
+
+try {
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  const authorizationUrl = new URL(
+    `${keycloakUrl}/realms/keycloak-patterns/protocol/openid-connect/auth`,
+  );
+  authorizationUrl.search = new URLSearchParams({
+    client_id: "spa-public",
+    redirect_uri: "http://localhost:8088/",
+    response_type: "code",
+    scope: "openid profile email",
+    state: `first-broker-${expectation}`,
+    nonce: `nonce-${expectation}`,
+    code_challenge: "K2qUEfBl-nQvF2gB4dNxC2zYVwZc1CVnZb5CsX2L7fI",
+    code_challenge_method: "S256",
+    kc_idp_hint: "mock-google",
+  });
+
+  await page.goto(authorizationUrl.toString());
+  await page.waitForURL(/\/realms\/mock-google\//u);
+  await page.locator("#username").fill("mock-collision-user");
+  await page.locator("#password").fill(mockPassword);
+  await page.locator("#kc-login").click();
+  await page.waitForLoadState("domcontentloaded");
+
+  if (expectation === "vulnerable") {
+    await page.waitForURL(/localhost:8088\/\?.*code=/u);
+    const identities = await federatedIdentities(token, user.id);
+    assert.equal(
+      identities.some(({ identityProvider }) => identityProvider === "mock-google"),
+      true,
+      "unsafe AutoLink should attach the attacker-controlled identity",
+    );
+    await removeMockLink(token, user.id);
+  } else {
+    assert.match(page.url(), /\/realms\/keycloak-patterns\//u);
+    const body = (await page.locator("body").innerText()).toLowerCase();
+    assert.match(body, /account already exists|link existing account|existing account/u);
+    const identities = await federatedIdentities(token, user.id);
+    assert.equal(
+      identities.some(({ identityProvider }) => identityProvider === "mock-google"),
+      false,
+      "Confirm Link must not attach the identity without ownership proof",
+    );
+  }
+
+  console.log(`first broker login ${expectation} case verified`);
+} finally {
+  await browser.close();
+}

google-e2e/package-lock.json

@@ -0,0 +1,27 @@
+{
+  "name": "keycloak-google-broker-e2e",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "keycloak-google-broker-e2e",
+      "version": "1.0.0",
+      "dependencies": {
+        "playwright-core": "1.55.1"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.55.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.55.1.tgz",
+      "integrity": "sha512-Z6Mh9mkwX+zxSlHqdr5AOcJnfp+xUWLCt9uKV18fhzA8eyxUd8NUWzAjxUh55RZKSYwDGX0cfaySdhZJGMoJ+w==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}

google-e2e/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "keycloak-google-broker-e2e",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test:first-broker": "node first-broker-login.mjs",
+    "test:claim-mapping": "node claim-mapping.mjs",
+    "test:claim-to-role": "node claim-to-role.mjs"
+  },
+  "dependencies": {
+    "playwright-core": "1.55.1"
+  }
+}

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"
       }
     ]
   },
@@ -154,6 +158,78 @@
       }
     }
   ],
+  "identityProviderMappers": [
+    {
+      "name": "mock-google-stable-username",
+      "identityProviderAlias": "mock-google",
+      "identityProviderMapper": "oidc-username-idp-mapper",
+      "config": {
+        "template": "${ALIAS}.${CLAIM.sub}",
+        "target": "LOCAL"
+      }
+    },
+    {
+      "name": "mock-google-email",
+      "identityProviderAlias": "mock-google",
+      "identityProviderMapper": "oidc-user-attribute-idp-mapper",
+      "config": {
+        "syncMode": "INHERIT",
+        "claim": "email",
+        "user.attribute": "email"
+      }
+    },
+    {
+      "name": "mock-google-given-name",
+      "identityProviderAlias": "mock-google",
+      "identityProviderMapper": "oidc-user-attribute-idp-mapper",
+      "config": {
+        "syncMode": "INHERIT",
+        "claim": "given_name",
+        "user.attribute": "firstName"
+      }
+    },
+    {
+      "name": "mock-google-family-name",
+      "identityProviderAlias": "mock-google",
+      "identityProviderMapper": "oidc-user-attribute-idp-mapper",
+      "config": {
+        "syncMode": "INHERIT",
+        "claim": "family_name",
+        "user.attribute": "lastName"
+      }
+    },
+    {
+      "name": "mock-google-picture",
+      "identityProviderAlias": "mock-google",
+      "identityProviderMapper": "oidc-user-attribute-idp-mapper",
+      "config": {
+        "syncMode": "INHERIT",
+        "claim": "picture",
+        "user.attribute": "picture"
+      }
+    },
+    {
+      "name": "mock-google-hosted-domain",
+      "identityProviderAlias": "mock-google",
+      "identityProviderMapper": "oidc-user-attribute-idp-mapper",
+      "config": {
+        "syncMode": "INHERIT",
+        "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": [
     {
       "username": "admin-user",

keycloak/import/mock-google-realm.json

@@ -25,7 +25,37 @@
       "redirectUris": [
         "http://localhost:8080/realms/keycloak-patterns/broker/mock-google/endpoint"
       ],
-      "webOrigins": []
+      "webOrigins": [],
+      "protocolMappers": [
+        {
+          "name": "hosted-domain",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-hardcoded-claim-mapper",
+          "consentRequired": false,
+          "config": {
+            "claim.name": "hd",
+            "claim.value": "example.test",
+            "jsonType.label": "String",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        },
+        {
+          "name": "picture",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-hardcoded-claim-mapper",
+          "consentRequired": false,
+          "config": {
+            "claim.name": "picture",
+            "claim.value": "https://images.example.test/mock-user.png",
+            "jsonType.label": "String",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ]
     }
   ],
   "users": [
@@ -51,14 +81,6 @@
       "emailVerified": false,
       "firstName": "Broker",
       "lastName": "Collision",
-      "attributes": {
-        "hd": [
-          "example.test"
-        ],
-        "picture": [
-          "https://images.example.test/mock-collision-user.png"
-        ]
-      },
       "credentials": [
         {
           "type": "password",

scripts/configure-broker-user-profile.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ ! -f .env ]; then
+  echo "missing .env" >&2
+  exit 1
+fi
+
+set -a
+. ./.env
+set +a
+
+keycloak_url="${KEYCLOAK_URL:-http://localhost:8080}"
+realm="${KEYCLOAK_REALM:-keycloak-patterns}"
+profile_url="$keycloak_url/admin/realms/$realm/users/profile"
+
+admin_token="$(
+  curl -fsS \
+    -d client_id=admin-cli \
+    -d grant_type=password \
+    -d "username=$KC_BOOTSTRAP_ADMIN_USERNAME" \
+    -d "password=$KC_BOOTSTRAP_ADMIN_PASSWORD" \
+    "$keycloak_url/realms/master/protocol/openid-connect/token" |
+    jq -er .access_token
+)"
+
+profile="$(curl -fsS -H "Authorization: Bearer $admin_token" "$profile_url")"
+updated_profile="$(
+  printf '%s' "$profile" |
+    jq '
+      def broker_attribute($name; $label): {
+        name: $name,
+        displayName: $label,
+        validations: {length: {max: 2048}},
+        permissions: {
+          view: ["admin", "user"],
+          edit: ["admin"]
+        },
+        multivalued: false,
+        group: "user-metadata"
+      };
+      if any(.attributes[]; .name == "picture") then .
+      else .attributes += [broker_attribute("picture"; "Profile picture URL")]
+      end |
+      if any(.attributes[]; .name == "hd") then .
+      else .attributes += [broker_attribute("hd"; "Hosted domain")]
+      end
+    '
+)"
+
+printf '%s' "$updated_profile" |
+  curl -fsS -X PUT \
+    -H "Authorization: Bearer $admin_token" \
+    -H "Content-Type: application/json" \
+    --data @- \
+    "$profile_url"
+
+echo "Broker user-profile attributes configured for realm '$realm'"

scripts/configure-google-idp.sh

@@ -15,6 +15,8 @@ set +a
 : "${GOOGLE_CLIENT_ID:?set GOOGLE_CLIENT_ID in .env}"
 : "${GOOGLE_CLIENT_SECRET:?set GOOGLE_CLIENT_SECRET in .env}"
 
+./scripts/configure-broker-user-profile.sh
+
 keycloak_url="${KEYCLOAK_URL:-http://localhost:8080}"
 realm="${KEYCLOAK_REALM:-keycloak-patterns}"
 
@@ -76,6 +78,77 @@ else
   action="created"
 fi
 
+mapper_endpoint="$endpoint/google/mappers"
+upsert_mapper() {
+  mapper_name="$1"
+  mapper_type="$2"
+  mapper_config="$3"
+  mapper_id="$(
+    curl -fsS \
+      -H "Authorization: Bearer $admin_token" \
+      "$mapper_endpoint" |
+      jq -r --arg name "$mapper_name" '
+        .[] | select(.name == $name) | .id
+      ' |
+      head -1
+  )"
+  mapper_payload="$(
+    jq -n \
+      --arg name "$mapper_name" \
+      --arg alias "google" \
+      --arg mapper "$mapper_type" \
+      --argjson config "$mapper_config" \
+      '{
+        name: $name,
+        identityProviderAlias: $alias,
+        identityProviderMapper: $mapper,
+        config: $config
+      }'
+  )"
+  if [ -n "$mapper_id" ]; then
+    curl -fsS -X PUT \
+      -H "Authorization: Bearer $admin_token" \
+      -H "Content-Type: application/json" \
+      --data "$mapper_payload" \
+      "$mapper_endpoint/$mapper_id"
+  else
+    curl -fsS -X POST \
+      -H "Authorization: Bearer $admin_token" \
+      -H "Content-Type: application/json" \
+      --data "$mapper_payload" \
+      "$mapper_endpoint"
+  fi
+}
+
+upsert_mapper \
+  "google-stable-username" \
+  "oidc-username-idp-mapper" \
+  '{"template":"${ALIAS}.${CLAIM.sub}","target":"LOCAL"}'
+upsert_mapper \
+  "google-email" \
+  "oidc-user-attribute-idp-mapper" \
+  '{"syncMode":"INHERIT","claim":"email","user.attribute":"email"}'
+upsert_mapper \
+  "google-given-name" \
+  "oidc-user-attribute-idp-mapper" \
+  '{"syncMode":"INHERIT","claim":"given_name","user.attribute":"firstName"}'
+upsert_mapper \
+  "google-family-name" \
+  "oidc-user-attribute-idp-mapper" \
+  '{"syncMode":"INHERIT","claim":"family_name","user.attribute":"lastName"}'
+upsert_mapper \
+  "google-picture" \
+  "oidc-user-attribute-idp-mapper" \
+  '{"syncMode":"INHERIT","claim":"picture","user.attribute":"picture"}'
+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:"
 echo "$keycloak_url/realms/$realm/broker/google/endpoint"

scripts/set-first-broker-login-mode.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env sh
+set -eu
+
+mode="${1:-}"
+case "$mode" in
+  vulnerable|secure) ;;
+  *)
+    echo "usage: $0 vulnerable|secure" >&2
+    exit 1
+    ;;
+esac
+
+if [ ! -f .env ]; then
+  echo "missing .env" >&2
+  exit 1
+fi
+
+set -a
+. ./.env
+set +a
+
+keycloak_url="${KEYCLOAK_URL:-http://localhost:8080}"
+realm="${KEYCLOAK_REALM:-keycloak-patterns}"
+admin_base="$keycloak_url/admin/realms/$realm"
+vulnerable_flow="vulnerable first broker login"
+idp_url="$admin_base/identity-provider/instances/mock-google"
+
+admin_token="$(
+  curl -fsS \
+    -d client_id=admin-cli \
+    -d grant_type=password \
+    -d "username=$KC_BOOTSTRAP_ADMIN_USERNAME" \
+    -d "password=$KC_BOOTSTRAP_ADMIN_PASSWORD" \
+    "$keycloak_url/realms/master/protocol/openid-connect/token" |
+    jq -er .access_token
+)"
+
+auth_header="Authorization: Bearer $admin_token"
+encode() {
+  jq -rn --arg value "$1" '$value | @uri'
+}
+
+flows="$(curl -fsS -H "$auth_header" "$admin_base/authentication/flows")"
+flow_id="$(
+  printf '%s' "$flows" |
+    jq -r --arg alias "$vulnerable_flow" '
+      .[] | select(.alias == $alias) | .id
+    ' |
+    head -1
+)"
+
+if [ -n "$flow_id" ]; then
+  existing_executions="$(
+    curl -fsS -H "$auth_header" \
+      "$admin_base/authentication/flows/$(encode "$vulnerable_flow")/executions"
+  )"
+  if printf '%s' "$existing_executions" | jq -e '
+    any(.[]; .authenticationFlow == true)
+  ' >/dev/null; then
+    idp_before_delete="$(curl -fsS -H "$auth_header" "$idp_url")"
+    printf '%s' "$idp_before_delete" |
+      jq '.firstBrokerLoginFlowAlias = "first broker login"' |
+      curl -fsS -X PUT \
+        -H "$auth_header" \
+        -H "Content-Type: application/json" \
+        --data @- \
+        "$idp_url"
+    curl -fsS -X DELETE \
+      -H "$auth_header" \
+      "$admin_base/authentication/flows/$flow_id"
+    flow_id=""
+  fi
+fi
+
+if [ -z "$flow_id" ]; then
+  curl -fsS -X POST \
+    -H "$auth_header" \
+    -H "Content-Type: application/json" \
+    --data "$(
+      jq -n --arg alias "$vulnerable_flow" '{
+        alias: $alias,
+        description: "INSECURE LEARNING FLOW - automatic email linking",
+        providerId: "basic-flow",
+        topLevel: true,
+        builtIn: false
+      }'
+    )" \
+    "$admin_base/authentication/flows"
+fi
+
+executions_url="$admin_base/authentication/flows/$(encode "$vulnerable_flow")/executions"
+executions="$(curl -fsS -H "$auth_header" "$executions_url")"
+create_user_id="$(
+  printf '%s' "$executions" |
+    jq -r '.[] | select(.providerId == "idp-create-user-if-unique") | .id' |
+    head -1
+)"
+if [ -z "$create_user_id" ]; then
+  curl -fsS -X POST \
+    -H "$auth_header" \
+    -H "Content-Type: application/json" \
+    --data '{"provider":"idp-create-user-if-unique"}' \
+    "$admin_base/authentication/flows/$(encode "$vulnerable_flow")/executions/execution"
+  executions="$(curl -fsS -H "$auth_header" "$executions_url")"
+  create_user_id="$(
+    printf '%s' "$executions" |
+      jq -r '.[] | select(.providerId == "idp-create-user-if-unique") | .id' |
+      head -1
+  )"
+fi
+
+auto_link_id="$(
+  printf '%s' "$executions" |
+    jq -r '.[] | select(.providerId == "idp-auto-link") | .id' |
+    head -1
+)"
+
+if [ -z "$auto_link_id" ]; then
+  curl -fsS -X POST \
+    -H "$auth_header" \
+    -H "Content-Type: application/json" \
+    --data '{"provider":"idp-auto-link"}' \
+    "$admin_base/authentication/flows/$(encode "$vulnerable_flow")/executions/execution"
+  executions="$(curl -fsS -H "$auth_header" "$executions_url")"
+  auto_link_id="$(
+    printf '%s' "$executions" |
+      jq -r '.[] | select(.providerId == "idp-auto-link") | .id' |
+      head -1
+  )"
+fi
+
+if [ "$mode" = "vulnerable" ]; then
+  curl -fsS -X PUT \
+    -H "$auth_header" \
+    -H "Content-Type: application/json" \
+    --data "$(jq -n --arg id "$create_user_id" '{id: $id, requirement: "ALTERNATIVE"}')" \
+    "$executions_url"
+  curl -fsS -X PUT \
+    -H "$auth_header" \
+    -H "Content-Type: application/json" \
+    --data "$(jq -n --arg id "$auto_link_id" '{id: $id, requirement: "ALTERNATIVE"}')" \
+    "$executions_url"
+  selected_flow="$vulnerable_flow"
+else
+  selected_flow="first broker login"
+fi
+
+idp="$(curl -fsS -H "$auth_header" "$idp_url")"
+printf '%s' "$idp" |
+  jq --arg flow "$selected_flow" '.firstBrokerLoginFlowAlias = $flow' |
+  curl -fsS -X PUT \
+    -H "$auth_header" \
+    -H "Content-Type: application/json" \
+    --data @- \
+    "$idp_url"
+
+assigned="$(
+  curl -fsS -H "$auth_header" "$idp_url" |
+    jq -r .firstBrokerLoginFlowAlias
+)"
+test "$assigned" = "$selected_flow"
+
+if [ "$mode" = "secure" ]; then
+  secure_executions="$(
+    curl -fsS -H "$auth_header" \
+      "$admin_base/authentication/flows/$(encode "first broker login")/executions"
+  )"
+  printf '%s' "$secure_executions" | jq -e '
+    any(.[];
+      .providerId == "idp-confirm-link" and .requirement == "REQUIRED"
+    ) and
+    (any(.[];
+      .providerId == "idp-auto-link" and .requirement != "DISABLED"
+    ) | not)
+  ' >/dev/null
+fi
+
+echo "mock-google First Broker Login mode: $mode ($selected_flow)"

scripts/verify-first-broker-login.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ ! -f .env ]; then
+  echo "missing .env" >&2
+  exit 1
+fi
+
+set -a
+. ./.env
+set +a
+
+restore_secure_flow() {
+  ./scripts/set-first-broker-login-mode.sh secure >/dev/null 2>&1 || true
+}
+trap restore_secure_flow 0 1 2 15
+
+npm --prefix google-e2e ci
+
+./scripts/set-first-broker-login-mode.sh vulnerable
+FIRST_BROKER_EXPECTATION=vulnerable \
+  npm --prefix google-e2e run test:first-broker
+
+./scripts/set-first-broker-login-mode.sh secure
+FIRST_BROKER_EXPECTATION=secure \
+  npm --prefix google-e2e run test:first-broker
+
+trap - 0 1 2 15
+echo "First Broker Login verified: unsafe AutoLink reproduced, Confirm Link restored"

scripts/verify-google-claim-mapping.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ ! -f .env ]; then
+  echo "missing .env" >&2
+  exit 1
+fi
+
+set -a
+. ./.env
+set +a
+
+./scripts/configure-broker-user-profile.sh
+./scripts/set-first-broker-login-mode.sh secure
+npm --prefix google-e2e ci
+npm --prefix google-e2e run test:claim-mapping

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