Matching a provider sign-in to a member

Who this is for. The developer enabling providers on a site that already has members, and the reviewer deciding which providers to trust. Afterwards you can predict which account a provider sign-in lands in, and explain why some are refused.

How the account is found

At the callback, the provider reports the person's identity, including an email address. The platform takes that address as the username and looks for the account:

1. A user with that username exists: that is the account.
2. No such user, but a person with that email address exists (someone who filled in a form, say): a user is created for that person.
3. Neither: a person and a user are created, with the name the provider reported.

A user created this way is a member (type Frontend user), active, with no password, and none of the registration settings apply: no default groups and no Inactive status, whatever registration is set to. If every member must be in a group, add provider sign-ups to it with a job on the user's create event, or check for the group where it matters.

For Microsoft, the address is the account's user principal name for an organisation's own users and its mail address for guests. The Core dna provider matches by its own username, not an email address.

Members whose username is not their email address

Matching uses the username. A member who registered with a username of their own choosing is not found by their email address, and a person can have only one login, so the provider sign-in cannot create a second one for them: it fails. On a site that offers providers, have members sign in by email address, with the Users setting Use email as username on from the start (Registration settings).

Accounts that already have a way in

The first time an account is reached through a provider, the platform checks whether the account already has another way in: a password, a passkey or another provider. If it has, and the person is not signed in, the link is refused:

"A user already exists with this email address. Please login and connect your account to enable sign in with this authentication method."

The attack this guards against is account takeover by email address. Without the rule, anyone able to sign in to some provider with a member's email address, for example by opening an account there with that address, would arrive in the member's existing account, orders and personal details included, without knowing their password. With it, a provider can be added to an existing account only by someone who first proves they own it, by signing in the way the account already allows. The member does exactly that: signs in as usual, then connects the provider from their linked-accounts screen (The linked-accounts screen).

Write your errors/oauth.html to say this in the member's terms for this code, with links to sign in and to reset a forgotten password (When the handshake fails).

Accounts with no way in yet

An account with no sign-in method at all, such as a user created in the admin or by an import without a password, is claimed by the first provider sign-in with its email address. That is how staff or partners are given single sign-on only: create each user with their email address as the username and no password, and their first Microsoft sign-in completes the account. It is also why the choice of providers is a trust decision: for those accounts, the provider's word about the email address is the only check (Which providers are safe to enable).

Connecting a provider while signed in

Connecting from the linked-accounts screen runs the same handshake, and the account is found the same way: by the email address the provider reports, not by who is signed in. So connect a provider account that uses the same email address as the member's username. A provider account with a different address is not added to the signed-in member: the platform finds or creates the account for that other address and signs in as it. Tell members this next to the Connect buttons.