keycloak-pattern/docs/first-broker-login-security.md

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:

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