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