Compare commits

..
14 changed files with 669 additions and 10 deletions
+18
View File
@@ -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을 복구한다.
+23
View File
@@ -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.
+18
View File
@@ -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`를 차례로 확인한다.
+123
View File
@@ -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();
}
+68
View File
@@ -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();
}
+4 -1
View File
@@ -4,7 +4,10 @@
"private": true,
"type": "module",
"scripts": {
"test:first-broker": "node first-broker-login.mjs"
"test:first-broker": "node first-broker-login.mjs",
"test:claim-mapping": "node claim-mapping.mjs",
"test:claim-to-role": "node claim-to-role.mjs",
"test:sub-vs-email": "node sub-vs-email.mjs"
},
"dependencies": {
"playwright-core": "1.55.1"
+132
View File
@@ -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();
}
@@ -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",
+31 -9
View File
@@ -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",
+58
View File
@@ -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'"
+73
View File
@@ -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"
+11
View File
@@ -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
+16
View File
@@ -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
+18
View File
@@ -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