google-signin

Google Sign-In (GIS) — production web login

Condensed operating instructions. Full narrative guide with diagrams, token anatomy, troubleshooting table, and a copy-paste FastAPI + JS skeleton: references/full-guide.md — read it when implementing from scratch; its FastAPI + JS skeleton is the reference implementation this skill ships.

Pick the right flow first

• Only need "who is this user?" → GIS ID-token flow (this skill): load https://accounts.google.com/gsi/client, receive one Google-signed JWT, verify server-side. No redirect URI, no client secret, no Google-token storage.
• Need to call Google APIs (Gmail/Drive/Calendar) on the user's behalf → OAuth 2.0 authorization-code flow instead (redirect URI + client secret + refresh tokens). Never use the code flow just for login.

Core flow (ID-token)

1. Frontend: google.accounts.id.initialize({ client_id, callback, nonce })
   • renderButton(). Generate a fresh random nonce per render (crypto.randomUUID()). The GSI script loads async — retry rendering (e.g. 20 × 150 ms) instead of silently dropping the button.
2. Callback receives { credential } — a Google-signed ID token (JWT). POST it with the nonce to your backend. Never treat it as a session.
3. Backend: verify with the official lib — Python google.oauth2.id_token.verify_oauth2_token(credential, transport, CLIENT_ID), Node google-auth-library verifyIdToken({ idToken, audience }). That checks signature (Google JWKS), aud, iss, exp. Never hand-decode and trust the payload.
4. Additionally require email_verified == true and token nonce claim == submitted nonce.
5. Find-or-create the user, then issue YOUR OWN session (app JWT) as an HttpOnly + Secure + SameSite=Strict cookie. Google's token is verified once, never stored, never logged.

Identity & account linking (three-way branch)

Key the user on sub (stable Google user ID; store as google_id) — never on email (emails change, sub doesn't). On each Google login: