keycloak-pattern/docs/google-claim-mapping.md

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.