Authentication
Sign in with Google
Let users sign in using their existing Google account. No new password to remember; faster signup.
When to use this
When you want to lower signup friction. Especially good for B2B (Google Workspace users) and consumer apps.
What I assumed
I made these guesses to fill gaps. Let me know if any are wrong.
Flow diagram
Step-by-step recipe
Copy this and paste into Cursor, Claude Code, or v0.
PATTERN: Sign in with Google
INPUT: (none from user — Google handles credentials)
OUTPUT: session_token | error_message
STEPS:
1. User clicks "Sign in with Google" button
2. Redirect user to Google OAuth consent screen
3. User approves access in Google's UI
4. Google redirects back to our callback URL with an authorization code
5. Server exchanges code for an access token (server-to-server)
6. Fetch user profile (email, name, profile picture) from Google
7. IF email already exists in our DB → link this Google account to that user
8. IF new email → create new user record
9. Create session token, store as HttpOnly cookie
10. Redirect to the page the user was trying to reach (or home)
ERROR_HANDLING:
- User cancels at Google consent → redirect back with friendly "No problem, try another way" message
- Google returns error → log it, show "We couldn't sign you in with Google right now"
- Email already used by email-login user → ask "Link this Google account to your existing account?"
- Network failure between us and Google → retry once, fall back to error message
EXTENSION_POINTS:
- Account linking with email-login (composable_with: ["email-login", "account-linking"])
- Profile setup wizard for new users (composable_with: ["profile-setup"])
- Other providers (Apple, GitHub, Microsoft) — same flow, different provider
States — how things change
| State | Description | Transitions |
|---|---|---|
| Awaiting consent at Google | User is on Google's OAuth consent page |
|
| Exchanging code | Server trading auth code for access token |
|
| Linking or creating user | Determining if email matches an existing account |
|
| Signed in | Session active, user can access protected pages | terminal |
| Cancelled | User declined at Google | terminal |
Easy-to-miss situations
The kinds of edge cases that break demos.
What if the user has multiple Google accounts?
mediumThey might pick the wrong one and create a duplicate account in our system.
Suggested handling: After login show "You signed in as [email] — switch?" link prominently. Provide easy account-linking on profile page.
What if Google's OAuth service is down?
highUsers can't log in at all if Google login is the only option.
Suggested handling: Always offer at least one alternative (email-login or magic-link). Show clear "Google sign-in is temporarily unavailable" message with the alternatives.
What if the email already exists from email-login?
highTwo accounts for same person — confusing and risky (data split).
Suggested handling: Detect this and ask "An account with this email already exists. Link your Google account to it?" Require password confirmation to link.
What if Google returns no email (rare edge case)?
lowSome Google accounts (especially restricted Workspace) might not share email.
Suggested handling: Show "We need access to your email to create your account" and ask to re-authorize with email scope. Don't proceed without email.
What if a user revokes our access in Google settings later?
lowTheir next login will fail unexpectedly.
Suggested handling: Catch the specific error, show "Your Google access was revoked. Please re-authorize or use email login." Offer easy recovery.
Composes well with
Combine these patterns when you need a richer flow.