How to link accounts by email#
Make somebody signing in with a new provider land on the account they already have here, instead of getting a second one.
Three switches on the provider's Accounts tab do this, and they have to be set in order.
1. Trust the provider's verification#
Set This provider's email verification counts.
An address the provider says it verified is then recorded as verified here, exactly as a magic link from this site would record one.
Warning
Switch this on only for a provider that really checks—one that refuses to call an address verified until the account has answered mail at it.
A provider with weaker rules is an account takeover waiting to happen: somebody registers there with an address belonging to one of your users, and this site hands them the account.
google and github ship with it on. Every other driver ships with it off.
Turning it off later stops it verifying anything new. Addresses already recorded as verified stay that way, because they are identities, and removing one is an unlink rather than a configuration change.
2. Turn on matching#
Set Attach to an existing account with the same verified email.
A person signing in with this provider for the first time is then attached to an account that already exists, when the address matches a verified one.
This needs step 1 as well. The address being matched on is the one this provider just sent, so a provider whose word the site does not take cannot reach an account with it.
3. If nothing links, check how the flag arrives#
Some providers send email_verified as the string "true" rather than as a
boolean. Oracle Access Manager does, and so do some customized Keycloak realms.
Set This provider sends verification flags as text for those.
Note
The symptom is that nothing visibly goes wrong.
Sign-in works, and only the linking silently does not: every address arrives unverified, so the switch above it can never fire, and no error says so.
If verification is configured and never seems to take effect, look at what the provider actually sends before looking anywhere else.
Leave it off unless you have established that this is what your provider does. A default Keycloak sends a real boolean and does not need it.
Verify#
Sign in with the new provider, using an address that already belongs to an account here.
You land on the existing account, not a new one.
/identitiesfor that account lists both sign-in methods.The audit log has an
identity-linkedentry, and anemail-verifiedone.
If a second account was created instead, one of the three switches is off, or the address was not verified at the provider.
When it refuses#
A link that would attach an identity to a different account than the one it is
already on raises rather than merging. The audit log records link-collision.
Merging two accounts is not something this package will guess at. See About identities and user ids.
Next steps#
How to control account creation—the switch that decides what happens when no match is found
About email verification—the whole trust rule, and why an absent claim is not a
trueHow to troubleshoot sign-in—"Existing account not matched by email"