# `PhoenixKit.Users.OAuth`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v2.15.1/lib/phoenix_kit/users/oauth.ex#L2)

OAuth authentication context for PhoenixKit.

Handles OAuth authentication flows for external providers like Google, Apple, GitHub.

This module requires the Ueberauth library to be installed. If Ueberauth is not available,
a fallback module with basic functionality will be used instead.

# `find_or_create_user`

Resolves the local account for an OAuth callback, creating one if needed.

Resolution order matters, because the three cases carry different proof:

1. **An existing link** (`provider` + `provider_uid`) is the strongest
   signal there is — this exact external identity was attached to this
   account before, and no email address is consulted.
2. **A pre-existing local account with the same email** is the takeover
   case. Matching on the email string alone means whoever can get that
   address attached to a provider account signs in as its owner, so the
   provider must ASSERT it verified the address. Without that assertion the
   callback is refused with `{:error, :provider_email_unverified}`.
3. **No local account** registers a new one.

The assertion requirement can be lifted with the `oauth_require_verified_email`
setting (default `true`) for a deployment whose provider does not surface a
verification claim; it is a deliberate, operator-visible decision rather
than a silent default.

# `get_user_oauth_providers`

Gets all OAuth providers for a user.

# `handle_oauth_callback`

Handles OAuth callback from Ueberauth.

# `link_oauth_provider`

Links an OAuth provider to a user account.

# `unlink_oauth_provider`

Unlinks an OAuth provider from a user.

---

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