# `AshAuthentication.Strategy.OAuth2.SignInPreparation`
[🔗](https://github.com/team-alembic/ash_authentication/blob/main/lib/ash_authentication/strategies/oauth2/sign_in_preparation.ex#L5)

Prepare a query for sign in

Performs three main tasks:

  1. Ensures that there is only one matching user record returned, otherwise
     returns an authentication failed error.
  2. Generates an access token if token generation is enabled.
  3. Updates the user identity resource, if one is enabled.

## Attaching a new provider identity

The sign-in action's filter decides which account a callback matches. When the
provider's `iss`/`sub` is not yet linked to that account, this preparation
decides whether to link it:

  * If a different identity for this strategy already belongs to the account -
    refuse. One account cannot have two identities for the same provider
    auto-linked.
  * If the strategy trusts the provider's `email_verified` claim **and** the
    verified email equals the account's `email_field` - link.
  * Otherwise refuse. The person must sign in with their existing method to
    link the provider.

The email comparison is what makes the trusted claim mean something. A verified
`email_verified` claim attests ownership of one address and nothing else, so on
an action filtered by a username it says nothing about the account the filter
matched. `AshAuthentication.Strategy.OAuth2.UserResolver` states the same rule
for the register action, where the matched `upsert_identity` values carry the
evidence instead.

An account whose `email_field` is empty, or a provider that supplies no email,
therefore never links here. So does a resource with no email attribute, which
is why `trust_email_verified?` requires `email_field` to name one.

# `init`

# `supports`

# `temporal_safe?`

---

*Consult [api-reference.md](api-reference.md) for complete listing*