/google-cloud-auth

name: google-cloud-auth
description: "[RU: oauth google, авторизация гугл, service account, sa key, refresh token, invalid_grant, adc, google cloud auth] Google auth for all Google APIs — OAuth 2.0, Service Account JWT, ADC. Use when: auth setup, invalid_grant, SA key, refresh token, PKCE, gcloud ADC. SKIP: GA4 (→google-analytics); GSC (→google-search-console); GTM (→google-tag-manager)."
stacks:
  - google-cloud-auth
  - oauth2
  - python
  - nodejs
tags:
  - google
  - oauth
  - auth
  - service-account
  - adc
  - refresh-token
source: vechkasov-global-skills
risk: high-stakes

<!-- versions:start -->

🎯 Version Requirements (June 2026)

**Primary pins:**

• google-auth-library (Node): `9.x`
• google-auth (Python): `2.x`
• Node.js: `24.x (Active LTS)`
• Python: `3.14.x`

> Source of truth: [STACK_VERSIONS.md](../../STACK_VERSIONS.md) — verified 2026-06-11

<!-- versions:end -->

Usage

Loaded automatically when its description matches the active task. This is the single source of truth for all Google API authentication patterns. Read the section you need, then follow the link to the relevant reference file.

Use this skill when

• Setting up OAuth 2.0 Authorization Code flow (installed app or web app) for any Google API — GSC, GA4, GTM, YouTube, Drive
• Configuring a Service Account for server-to-server (backend) access: creating SA, downloading key.json, granting access
• Understanding Application Default Credentials (ADC) and `GOOGLE_APPLICATION_CREDENTIALS` env var discovery chain
• Diagnosing `invalid_grant`, `token_has_been_expired_or_revoked`, or `401 Unauthorized` on a previously working token
• Choosing between OAuth user flow and Service Account for a given use case
• Implementing offline access (`access_type=offline`) and `prompt=consent` to force a new refresh token
• Configuring PKCE for installed apps or web apps that cannot store a client secret securely
• Setting up domain-wide delegation (DWD) — impersonating G Suite users via a Service Account
• Reviewing minimum scopes needed for a specific Google API (GSC readonly, GA4 readonly, GTM publish, YouTube, etc.)
• Auditing OAuth consent screen configuration (redirect URIs, app verification, testing vs production mode)

Do not use this skill when

• You need to make GA4 Data API calls — auth is covered in context; load `google-analytics` for request shape, quotas, and FilterExpression DSL
• You need to query Google Search Console data — load `google-search-console` for dimensions, filters, and URL Inspection
• You need GTM container / tag management — load `google-tag-manager` for resource hierarchy and CRUD operations
• You need Yandex OAuth (Yandex Metrika, Direct, Webmaster) — different provider; load `yandex-metrica`, `yandex-direct`, or `yandex-webmaster`
• You need general HTTP transport patterns (retries, backoff, connection pooling) — load `httpx` (Python) or `nodejs`

Purpose

Google Cloud Authentication provides the credential foundation for every Google API call. Three patterns cover all use cases: OAuth 2.0 Authorization Code flow for end-user consent (installed apps, web apps), Service Account JWT bearer for backend scripts with no user interaction, and Application Default Credentials (ADC) for environments where credentials are pre-injected (Cloud Run, GKE, Compute Engine, gcloud CLI).

This skill is **high-stakes** because a wrong auth choice or misconfiguration fails silently — the API returns 401 or 403 with a reason that can be mistaken for a permission issue when it is actually a stale token, missing scope, or a refresh token rotation that was not handled. Every downstream Google skill (GA4, GSC, GTM, YouTube) depends on this skill for its credential bootstrap; errors here block all of them.

Capabilities

OAuth 2.0 Authorization Code flow

OAuth 2.0 is the right choice whenever a real Google user must grant consent — for example, when you need to access a Search Console property that the user owns, or read GA4 data on behalf of a paying customer. The flow has two sub-variants: **web application** (client secret stored server-side, redirect URI is an `https://` URL) and **installed application** (client secret is embedded in the app binary and treated as non-confidential; redirect URI is `urn:ietf:wg:oauth:2.0:oob` or `http://localhost:PORT`). Both variants produce the same token pair — `access_token` (1-hour TTL) and `refresh_token` (long-lived). PKCE (`code_challenge` + `code_verifier`) is mandatory for public clients (installed apps, SPAs) and recommended for web apps. Redirect URIs must be registered in the Cloud Console OAuth client; unregistered URIs return `redirect_uri_mismatch` immediately.

> Full reference: [references/oauth2-user-flow.md](references/oauth2-user-flow.md)

Service Account JWT bearer

A Service Account (SA) is a Google-managed identity that authenticates with a key file rather than a user password. The auth library creates a signed JWT assertion, exchanges it for an access token at `https://oauth2.googleapis.com/token`, and re-exchanges automatically on expiry. This pattern requires: (1) the SA created in Cloud Console + key.json downloaded, (2) the relevant API enabled in the Cloud project, and (3) the SA email granted access on the target resource — for GA4 via Property Access Management, for GSC via the Search Console UI, for GTM via the GTM account/container settings. Domain-wide delegation (DWD) extends this by allowing the SA to impersonate any user in a G Suite domain; it requires a Super Admin to authorize the SA's client ID in the Admin Console.

> Full reference: [references/service-account.md](references/service-account.md)

Application Default Credentials (ADC)

ADC is the zero-config credential discovery chain used by all Google client libraries (`google-auth`, `googleapis`, `google-auth-library`). When code calls `google.auth.default()` or `new GoogleAuth()`, the library walks a discovery chain: (1) `GOOGLE_APPLICATION_CREDENTI