OAuth / Social Login

Builds on Auth Fundamentals@markdowners/auth-fundamentals — the session and authorization rules there still apply once the user is signed in; this module covers the OAuth handshake itself.

Use the standard flow, not a custom one

• Use Authorization Code flow with PKCE for any user-facing OAuth login (web or mobile) — never Implicit flow, which exposes tokens in the URL fragment and has no way to bind the token exchange to the original requester.
• Always validate that the state parameter round-trips unchanged through the OAuth redirect — this is what prevents CSRF against the login flow itself (an attacker tricking a victim into completing an OAuth flow that links the attacker's identity to the victim's session).

Token handling

• Exchange the authorization code for tokens server-side, using a confidential client secret that never reaches the browser — never perform the code-for-token exchange in client-side JavaScript.
• Store the resulting access/refresh tokens server-side (encrypted at rest if they grant access to sensitive third-party data); never pass third-party OAuth tokens to the client unless the client genuinely needs to call that provider's API directly.

Account linking

• When a user signs in via OAuth with an email that already has an existing account (e.g. a password-based account with the same email), never auto-merge the two accounts silently — that lets anyone who controls an OAuth-verified email at a given address take over an existing account. Require an explicit, authenticated linking step instead.
• Store provider + provider-user-id as the actual link key, not email alone — emails can be reused or reassigned by the provider or the mail host over time, and provider-user-id is the stable identifier.

Scope minimization

• Request only the OAuth scopes you actually use (basic email, profile — not broad access to the provider's other APIs) — broader scopes increase both the blast radius of a token leak and the friction of the consent screen the user sees.

Provider trust

• Fetch the user's profile (email, verified-email status) from the provider's userinfo endpoint using the access token you just received server-side — never trust profile data passed through client-side redirect parameters, which can be manipulated before reaching your callback.
• Only treat the OAuth-provided email as verified if the provider's response explicitly marks it verified — some providers allow unverified emails through the same flow.

Callback endpoint hygiene

• Register and validate exact redirect URIs with the provider (no wildcard domains) — an overly permissive registered redirect URI is a common real-world OAuth vulnerability, since it lets tokens be redirected to an attacker-controlled endpoint.
• Make the callback route resilient to a user cancelling consent or the provider returning an error parameter instead of a code — handle it as a normal "login cancelled" state, not an unhandled exception.