sign-in-with-google-web — Claude Code skill: setup guide

---
name: sign-in-with-google-web
metadata:
  category: Identity
  version: "1.0.0"
description: >-
  Implement, configure, and secure Sign In With Google (SiwG) using Google Identity
  Services (GIS / `https://accounts.google.com/gsi/client`) across web architectures.
  Use when creating Google sign-in buttons, implementing Google One Tap with FedCM,
  integrating GIS in React/Next.js/Angular/HTML, verifying ID tokens on backend
  runtimes (Python/Node.js/Go/Java), enforcing Google Workspace domain restrictions
  (`hd`), securing client-side ID tokens via WebCrypto nonces or encrypted IndexedDB,
  embedding in cross-origin iframes via the Intermediate Iframe API
  (`https://accounts.google.com/gsi/intermediate`), configuring Content Security
  Policy (CSP), COOP, and Permissions Policy (`identity-credentials-get`) headers,
  or handling sign-out and revocation. Don't use for legacy Google Sign-In (`gapi.auth2`),
  Google Cloud IAM service accounts, or Android/iOS native Credential Manager.
---

# Sign In With Google (SiwG) Integration & Security Architecture

This skill provides normative architectural guidelines, secure implementation
contracts, and failure-prevention protocols for integrating Sign In With Google
via the Google Identity Services (GIS) Web SDK
(`https://accounts.google.com/gsi/client`).

## 1. IETF Architecture Taxonomy & Hierarchy (RECOMMEND BFF / TMB FIRST)

All Sign In With Google implementations MUST align with the
[IETF OAuth 2.0 for Browser-Based Applications (`draft-ietf-oauth-browser-based-apps`)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps#name-application-architecture-pa)
taxonomy.

> [!IMPORTANT] **Primary Recommendation:** Always recommend backend-mediated
> patterns (**Pattern A: Backend For Frontend** or **Pattern B: Token-Mediating
> Backend / Redirect Mode**) as the most secure, robust, and industry-standard
> architectures whenever an application has a backend server. Fall back to
> client-only browser patterns (Patterns C & D) only when constrained by
> serverless static hosting or offline-first PWA requirements.

<!-- mdformat off(reason: preserve ASCII architecture diagram width) -->
```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                          IETF ARCHITECTURE HIERARCHY & SELECTION                        │
├──────────────────────────┬──────────────────────────┬───────────────────────────────────┤
│ Pattern A (RECOMMENDED): │ Pattern B (RECOMMENDED): │ Patterns C & D (Fallbacks):       │
│ Backend For Frontend     │ Token-Mediating Backend  │ Browser-Based OAuth Client        │
│ (BFF - IETF § 6.1)       │ (TMB / Redirect § 6.2)   │ (JavaScript-Only - IETF § 6.3)    │
├──────────────────────────┼──────────────────────────┼───────────────────────────────────┤
│ 🏆 GOLD STANDARD         │ 🚀 NATIVE FORM REDIRECT  │ ⚡ STATIC SPA / 💾 OFFLINE PWA    │
│ • Full-stack SPA + API   │ • Server-rendered & apps │ • Pure client-side or offline PWAs│
│ • Client JS fetch to API │ • GIS HTTP POST login_uri│ • C: Ephemeral in-memory closure  │
│ • HttpOnly session cookie│ • Direct server redirect │ • D: WebCrypto Encrypted IndexedDB│
│ • Tokens never in browser│ • Tokens never in JS     │ • Strict WebCrypto nonces / keys  │
└──────────────────────────┴──────────────────────────┴───────────────────────────────────┘
```
<!-- mdformat on -->

### 🏆 Pattern A: Backend For Frontend (BFF - IETF § 6.1) — STRONGLY RECOMMENDED

*   **Why it is the Gold Standard**: ID tokens (JWTs) and access tokens are
    never exposed to browser JavaScript across page reloads. This provides
    complete architectural immunity against XSS token harvesting.

*   **Architecture**: The browser frontend loads the GIS SDK, captures the
    credential in JavaScript callback (`callback: handleCredentialResponse`),
    and immediately forwards the ID token (JWT) via `fetch('/api/auth/google', {
    method: 'POST' })` to the backend.

*   **Backend Responsibilities**: The backend validates the JWT cryptographic
    signature against Google's public JWKs
    (`google.oauth2.id_token.verify_oauth2_token`), checks the `aud`, `hd`, and
    `nonce` claims against server session state, creates a server session, and
    issues a first-party `HttpOnly; Secure; SameSite=Lax` session cookie.

*   See full implementation in
    [references/bff_fastapi_verification.md](references/bff_fastapi_verification.md).

### 🚀 Pattern B: Token-Mediating Backend via `login_uri` Redirect (IETF § 6.2) — Server-Rendered & Form POST

*   **Why it is Highly Secure**: Bypasses client-side JavaScript credential
    handling entirely by instructing GIS to perform an HTTP POST directly to the
    backend's `login_uri`.

*   **Architecture**: Configured via `google.accounts.id.initialize({ client_id,
    login_uri: "https://example.com/api/auth/callback", ux_mode: "redirect" })`
    or HTML attributes (`data-login_uri="https://example.com/api/auth/callback"`
    and `data-ux_mode="redirect"`).

*   **Backend Responsibilities**: The backend receives the ID token as a form
    POST body (`credential` parameter), validates the double-submit
    `g_csrf_token` cookie against the `g_csrf_token` POST body field,
    cryptographically verifies the ID token server-side, establishes a session
    cookie, and returns a standard HTTP 302/303 redirect.

*   See full implementation in
    [references/tmb_login_uri_redirect.md](references/tmb_login_uri_redirect.md).

### Pattern C: Browser-Based OAuth Client — Ephemeral In-Memory (IETF § 6.3) — Fallback for Static SPAs

*   **Scope**: Use ONLY when deployment is strictly serverless/static (e.g.,
    GitHub Pages, Firebase static hosting) with no backend component.

*   **Storage Invariant**: The ID token is held strictly in private JavaScript
    memory/closures during the active tab session. **Never store raw tokens in
    `localStorage` or `sessionStorage`**.

*   **Session Renewal**: Uses GIS One Tap / FedCM auto-select (`auto_select:
    true`) to transparently re-acquire fresh ID tokens into memory on page
    reload without persistent browser storage.

*   **XSS & Replay Protection**: Generate a cryptographic `nonce` via
    `window.crypto.getRandomValues()` and pass it directly to
    `google.accounts.id.initialize({ client_id, nonce: clientNonce })`. Validate
    that `payload.nonce === clientNonce` before trusting claims in memory.

*   See full implementation in
    [references/in_memory_spa_nonce.md](references/in_memory_spa_nonce.md).

### Pattern D: Browser-Based OAuth Client — WebCrypto Encrypted IndexedDB (IETF § 6.3) — Fallback for Offline PWAs

*   **Scope**: Use ONLY for offline-first Progressive Web Apps (PWAs) where user
    authentication proof must survive tab refreshes when disconnected from the
    network.

*   **Storage Invariant**: **NEVER store raw plaintext ID tokens in
    `localStorage`**. Encrypt the ID token payload using WebCrypto `AES-GCM`
    with a non-extractable session key (`extractable: false`) before writing
    ciphertext and IV to `IndexedDB`.

*   See full implementation in
    [references/offline_pwa_encryption.md](references/offline_pwa_encryption.md).

--------------------------------------------------------------------------------

## 2. Mandatory Security Directives & Browser Policies

To avoid multi-turn repair loops and browser security exceptions, provide all
required CSP, COOP, and user activation directives in the initial deliverable:

### A. Content Security Policy (CSP) Directives

```http
Content-Security-Policy:
  script-src 'self' https://accounts.google.com/gsi/client;
  frame-src https://accounts.google.com/gsi/;
  connect-src https://accounts.google.com/gsi/;
```

If using strict nonce-based CSP, attach the nonce to the GIS script tag:
`<script src="https://accounts.google.com/gsi/client" async defer
nonce="{{NONCE}}"></script>`.

### B. Cross-Origin Opener Policy (COOP)

To allow GIS popup dialogs to communicate credentials back to the parent window
via `postMessage`:

```http
Cross-Origin-Opener-Policy: same-origin-allow-popups
```

*(Serving `same-origin` without `allow-popups` breaks GIS popups and results in
silent failures).*

### C. Automatic Selection, FedCM, & Sign-Out Lifecycle (`disableAutoSelect`)

When enabling automatic zero-click return sign-in with Google One Tap (FedCM is
enabled by default in GIS):

*   Set `auto_select: true` in `google.accounts.id.initialize({...})` (do not
    pass the deprecated `use_fedcm_for_prompt` parameter).

*   **Deprecated Library Warning**: NEVER mix deprecated `gapi.auth2`
    (`gapi.auth2.init`, `gapi.auth2.getAuthInstance().signOut()`) with Google
    Identity Services (GIS). `gapi.auth2` is completely retired; use GIS methods
    exclusively.

*   **Sign-Out Protocol**: When the user explicitly logs out of your
    application, you **MUST** call `google.accounts.id.disableAutoSelect()`:

    ```javascript
    function handleUserLogout() {
      // 1. Disable automatic One Tap / FedCM re-authentication
      google.accounts.id.disableAutoSelect();

      // 2. Clear application session state / server cookie
      fetch('/api/auth/logout', { method: 'POST' }).then(() => {
        window.location.href = '/login';
      });
    }
    ```

*   *(Failing to call `disableAutoSelect()` causes an immediate automatic
    re-login loop on the next page visit after intentional user logout).*

### D. Reliable Dynamic Script Loading & Framework Lifecycle (React, Next.js, SPAs)

When mounting Sign In With Google in Single Page Applications (React, Next.js,
Vue, Angular):

*   Modern SPAs execute component lifecycles asynchronously. Attempting to
    access `window.google.accounts.id` before `<script
    src="https://accounts.google.com/gsi/client">` has finished loading causes
    `ReferenceError: google is not defined`.

*   **NEVER use `gapi` or polling (`setInterval`)**: Use deterministic dynamic
    script loading with `onload` / `addEventListener('load')` event listeners.

*   **Dynamic Script Loader Pattern**:

    ```tsx
    import React, { useEffect, useState } from 'react';

    export function useGoogleIdentityScript() {
      const [isLoaded, setIsLoaded] = useState(false);

      useEffect(() => {
        if (window.google?.accounts?.id) {
          setIsLoaded(true);
          return;
        }

        const existingScript = document.querySelector(
          'script[src="https://accounts.google.com/gsi/client"]'
        );
        if (existingScript) {
          existingScript.addEventListener('load', () => setIsLoaded(true));
          return;
        }

        const script = document.createElement('script');
        script.src = 'https://accounts.google.com/gsi/client';
        script.async = true;
        script.defer = true;
        script.onload = () => setIsLoaded(true);
        document.head.appendChild(script);
      }, []);

      return isLoaded;
    }
    ```

*   *(Always use deterministic `onload` event listeners or framework `<Script
    strategy="afterInteractive">` rather than brittle `setInterval` polling).*

### E. Embedded Iframes & Permissions Policy (`identity-credentials-get`)

When embedding Sign In With Google or One Tap inside cross-origin `<iframe>`
elements or widget integrations, modern browser security models and FedCM
require explicit Permissions Policy delegation on the container frame:

```html
<iframe
  src="https://example.com/embed"
  allow="identity-credentials-get 'src' https://accounts.google.com">
</iframe>
```

*(Omitting `allow="identity-credentials-get"` blocks FedCM / One Tap
initialization inside embedded or cross-origin contexts).* See full integration
guide in [references/intermediate_iframe.md](references/intermediate_iframe.md).

--------------------------------------------------------------------------------

## 3. Implementation Contracts & Anti-Pattern Bans

### A. Strict Ban on Legacy GAPI (`gapi.auth2`)

*   **NEVER** import or reference `gapi.auth2`, `gapi.auth2.init`,
    `gapi.auth2.getAuthInstance()`, or `gapi.signin2`. Always warn that
    `gapi.auth2` is deprecated and decommissioned.

*   GIS (`google.accounts.id.*` and `google.accounts.oauth2.*`) is completely
    stateless. It replaces all legacy GAPI authentication libraries.

--------------------------------------------------------------------------------

## 4. Implementation Recipes (Progressive Disclosure)

Load the specific reference file matching your target architecture when
generating implementation code:

*   **Recipe 1 — Pattern A (Backend For Frontend with Python / FastAPI)
    [RECOMMENDED]**: Load
    [references/bff_fastapi_verification.md](references/bff_fastapi_verification.md)
    for custom UI button prompting, `google.oauth2.id_token.verify_oauth2_token`
    cryptographic verification, `nonce` replay checks, Google Workspace `hd`
    domain enforcement, and `HttpOnly; Secure; SameSite=Lax` session cookie
    issuance.

*   **Recipe 2 — Pattern B (Token-Mediating Backend with `login_uri` Form POST
    Redirect) [RECOMMENDED]**: Load
    [references/tmb_login_uri_redirect.md](references/tmb_login_uri_redirect.md)
    for `data-login_uri` / `ux_mode: 'redirect'` frontend setup and FastAPI
    double-submit `g_csrf_token` cookie vs. form-body validation.

*   **Recipe 3 — Pattern C (Browser-Based Ephemeral In-Memory SPA with Native
    GIS Nonce) [Fallback]**: Load
    [references/in_memory_spa_nonce.md](references/in_memory_spa_nonce.md) for
    WebCrypto `nonce` generation (`google.accounts.id.initialize({ client_id,
    nonce: clientNonce })`), UTF-8 safe Base64URL JWT decoding, and private
    closure token management.

*   **Recipe 4 — Pattern D (Browser-Based WebCrypto Encrypted IndexedDB for
    Offline PWAs) [Fallback]**: Load
    [references/offline_pwa_encryption.md](references/offline_pwa_encryption.md)
    for non-extractable (`extractable: false`) `AES-GCM` `CryptoKey` generation
    and encrypted `IndexedDB` storage.

*   **Recipe 5 — Embedded Cross-Origin Contexts (`gsi/intermediate`)**: Load
    [references/intermediate_iframe.md](references/intermediate_iframe.md) for
    `<div id="g_id_intermediate_iframe">`, `allow="identity-credentials-get"`,
    and strict `window.postMessage` origin verification.

--------------------------------------------------------------------------------

## 5. Sign-Out & Account Revocation Across All Patterns

```javascript
export function handleSignOut(userEmail) {
  // 1. Disable client-side One Tap auto-selection
  google.accounts.id.disableAutoSelect();

  // 2. Revoke OAuth grant if user disconnected account
  if (userEmail) {
    google.accounts.id.revoke(userEmail, () => {
      console.log('User grant revoked');
    });
  }

  // 3. Clear storage / session
  AuthManager.clear(); // Pattern C
  fetch('/api/auth/logout', { method: 'POST' }); // Pattern A
}
```

--------------------------------------------------------------------------------

## 6. References & Normative Standards

*   [RFC 7519: JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
    — Standard claims (`iss`, `sub`, `aud`, `exp`, `iat`, `nonce`), formatting,
    and processing rules.

*   [RFC 7515: JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515)
    — Cryptographic signature verification against Google's public JWK certs
    (`https://www.googleapis.com/oauth2/v3/certs`).

*   [RFC 4648 § 5: Base64url Encoding](https://datatracker.ietf.org/doc/html/rfc4648#section-5)
    — URL-safe Base64 encoding without padding used across JWT segments.

*   [IETF OAuth 2.0 Browser-Based Applications](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps)
    — Normative architecture standards (§ 6.1 BFF, § 6.2 TMB, § 6.3
    Client-side).

*   [Google Identity Services Web Reference](https://developers.google.com/identity/gsi/web/reference/js-reference)
    — Official GIS API reference.

*   [Intermediate Iframe API Reference](https://developers.google.com/identity/gsi/web/amp/nonamp-reference)
    — Cross-origin iframe embedding guide.

*   [Verify ID Tokens Server-Side](https://developers.google.com/identity/gsi/web/guides/verify-google-id-token)
    — Server-side token verification protocols.

*   [W3C Federated Credential Management API (FedCM)](https://www.w3.org/TR/fedcm-1/)
    — Browser identity credential mediation standard.

*   [W3C Web Cryptography API](https://www.w3.org/TR/WebCryptoAPI/) —
    Non-extractable key generation (`extractable: false`) and AES-GCM standards.