fix: add drift detection to ProtocolMapper, Role and ClientScope

[NerdySoftPaw]

Problem

Since the rollout of v0.12.1 on prod (2026-09-20), the ProtocolMapper, Role and ClientScope controllers PUT their definition to Keycloak on every sync (5m), even when nothing changed.

Operator writes per day on prod (Loki):

	up to 18.09. (0.8.1)	from 22.09. (0.12.1)
ProtocolMapper	~1,270	~11,650
Role	~1,290	~580

Every protocol mapper PUT invalidates the owning client in Keycloak's realm cache on all nodes, so the following token/userinfo requests reload from the DB. Result: 2–13s token latencies (~95 requests >2s per day, previously 0–3). This pushed the pace-id SLA v1 from ~99.98% down to 99.82% / 99.77% / 99.74% (21.–23.09.). Of the slow requests, 61% start within 5s of an operator write, versus 11% for random timestamps (small sample, n=28).

Fix

Compare the desired definition against the current Keycloak representation before updating, using the existing definitionsMatch (subset compare, string arrays unordered). This is the same pattern the client controller already uses:

• ProtocolMapper: list mappers via Get{Client,ClientScope}ProtocolMappersRaw and keep the representation matched by name (findMapperByName)
• Role: Get{Realm,Client}RoleRaw. composites is stripped beforehand as before and synced separately through the composites endpoint
• ClientScope: GetClientScopeRaw

If the fetch fails, the controller falls through to the update, so error behaviour is unchanged. Create paths are untouched.

Verification

• go test ./internal/... and go vet pass. New tests in keycloakprotocolmapper_drift_test.go, using the mapper shape returned by a live Keycloak 26:
  • an unchanged mapper does not count as drift
  • a config change is detected
  • a missing current representation forces an update
  • composites are stripped before the role compare
• Compared against live prod with read-only GETs: all 40 KeycloakProtocolMapper CRs and both client scopes compare as in sync, so zero PUTs after rollout.

Rollout / check

After deploying, protocol mapper updated successfully should drop from ~480/h to ~0. Slow token requests (>2s) should disappear from SLA v1 within a day.

Related (separate PR in keycloak-realm): man-idp uses config.hideOnLoginPage, which Keycloak 26 drops in favour of the top-level hideOnLogin. That causes a perpetual IdP diff.

🤖 Generated with Claude Code