google-auth

Node.js と Python 向け Google 認証

ライブラリ

Node.js

• google-auth-library — コア認証ライブラリ（OAuth2Client、GoogleAuth、JWT、Compute、Impersonated）
• googleapis — Google API クライアント（google-auth-library をラップします）

npm install google-auth-library
npm install googleapis

以下の client.fetch() 呼び出しには google-auth-library ≥ 10.1.0 が必要です（fetch 互換 API は 10.1.0（2025-06-12）で導入されました）。9.x では同じ引数を使って client.request() を使用してください。2026-08-31 に確認した最新バージョンは 11.x で、両方のメソッドが引き続き利用できます。

Python

• google-auth — コア認証ライブラリ（google.oauth2、google.auth、credentials、transport）
• google-auth-oauthlib — OAuth 2.0 ユーザー認証情報フローのヘルパー（Flow、InstalledAppFlow）
• google-api-python-client — Google API クライアント（google-auth をラップします）

pip install google-auth
pip install google-auth-oauthlib
pip install google-api-python-client

認証方法の概要

方法	使用例	Node.js の主要クラス	Python の主要モジュール／クラス
ADC	すべてのユーザーで同じ ID を使用するサーバー間通信	GoogleAuth	google.auth.default()
OAuth 2.0	エンドユーザーに代わって操作する	OAuth2Client	google_auth_oauthlib.flow.Flow
Sign In with Google（GIS）	ウェブサイトでのユーザーのサインイン／サインアップ — google-signin スキルの対象です	GIS JS SDK + verifyIdToken()	GIS JS SDK + id_token.verify_oauth2_token()
JWT／サービスアカウント	サーバー間通信、単一の ID	JWT	service_account.Credentials
API キー	ユーザーコンテキストを必要としない公開データ	OAuth2Client({ apiKey })	googleapiclient.discovery.build(developerKey=) に渡します
Compute	サービスアカウントがアタッチされた GCP 上での使用	Compute	google.auth.compute_engine.Credentials
Workload Identity Federation	AWS／Azure／OIDC → SA キーを使わずに GCP へ	ExternalAccountClient	google.auth.identity_pool.Credentials／google.auth.aws.Credentials

クイックパターン

1. アプリケーションのデフォルト認証情報（ADC）

Node.js

const {GoogleAuth} = require('google-auth-library');

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform'
});
const client = await auth.getClient();
const res = await client.fetch('https://dns.googleapis.com/dns/v1/projects/...');

Python

import google.auth
import google.auth.transport.requests

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/cloud-platform']
)
request = google.auth.transport.requests.Request()
credentials.refresh(request)

ADC の検索順序（最初に環境変数。この行は逆になっていました）：GOOGLE_APPLICATION_CREDENTIALS 環境変数 → gcloud auth application-default login のファイル → アタッチされたサービスアカウント（メタデータ）。設定前に、解決されたプリンシパルとソース（シークレットは含めません）を出力してください。複数の認証情報が存在する場合、実際に使用されるのは解決されたソースのみです。

ADC の設定とサービスアカウントの使用方法について詳しくは、references/adc-and-service-accounts.md を参照してください。

2. OAuth 2.0 ウェブサーバーフロー

Node.js

const {OAuth2Client} = require('google-auth-library');

const client = new OAuth2Client({
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  redirectUri: REDIRECT_URI
});

const authUrl = client.generateAuthUrl({
  access_type: 'offline',
  scope: ['https://www.googleapis.com/auth/userinfo.profile'],
  state: crypto.randomBytes(32).toString('hex'),
  include_granted_scopes: true
});

// After redirect: exchange code for tokens
const {tokens} = await client.getToken(code);
client.setCredentials(tokens);

Python

from google_auth_oauthlib.flow import Flow

flow = Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/userinfo.profile'],
    redirect_uri=REDIRECT_URI
)

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true'
)

# After redirect: exchange code for tokens
flow.fetch_token(code=code)
credentials = flow.credentials

refresh_token は最初の認可時にのみ返されます。再同意を強制するには、prompt: 'consent'（Node.js）または prompt='consent'（Python）を使用してください。

OAuth 2.0 フロー（パラメーター、トークン交換、更新、取り消し、段階的認証）の全容については、references/oauth2-web-server.md を参照してください。

3. Google ID トークンの検証 — ライブラリ呼び出し

Node.js

const {OAuth2Client} = require('google-auth-library');
const client = new OAuth2Client();

const ticket = await client.verifyIdToken({
  idToken: token,
  audience: WEB_CLIENT_ID,
});
const payload = ticket.getPayload();

Python

from google.oauth2 import id_token
from google.auth.transport import requests

payload = id_token.verify_oauth2_token(token, requests.Request(), WEB_CLIENT_ID)

この呼び出しが確認するのは署名、aud、exp、iss だけです。それ以外は確認しません。これはライブラリの契約であり、ウェブサインインの契約ではありません。サインインのセキュリティチェックリスト（nonce のバインディング、email_verified、ログイン CSRF 対策、アカウントのリンク）については、google-signin スキルを使用してください。この契約を扱うのはこのスキルのみであり、このスキルでは意図的に内容を重複して記載していません。

4. JWT／サービスアカウント

Node.js

const {JWT} = require('google-auth-library');
const keys = require('./service-account-key.json');

const client = new JWT({
  email: keys.client_email,
  key: keys.private_key,
  scopes: ['https://www.googleapis.com/auth/cloud-platform'],
});
const res = await client.fetch(url);

Python

from google.oauth2 import service_account

credentials = service_account.Credentials.from_service_account_file(
    'service-account-key.json',
    scopes=['https://www.googleapis.com/auth/cloud-platform']
)

# Or from a dict already loaded into memory:
credentials = service_account.Credentials.from_service_account_info(
    info,
    scopes=['https://www.googleapis.com/auth/cloud-platform']
)

5. API キー

Node.js

const {OAuth2Client} = require('google-auth-library');
const client = new OAuth2Client({ apiKey: 'my-api-key' });

// Or via GoogleAuth:
const {GoogleAuth} = require('google-auth-library');
const auth = new GoogleAuth({
  clientOptions: { apiKey: 'my-api-key' }
});

Python

from googleapiclient.discovery import build

service = build('customsearch', 'v1', developerKey='my-api-key')

6. トークンの更新

Node.js

client.on('tokens', (tokens) => {
  if (tokens.refresh_token) {
    // Store refresh_token — only sent on first auth
  }
  // Record an event name only; token values never enter logs.
  console.info("google_auth_tokens_refreshed");
});

Python

from google.auth.transport.requests import Request

if credentials.expired and credentials.refresh_token:
    credentials.refresh(Request())
    # credentials.token is the new access token
    # credentials.expiry is the new expiration datetime

セキュリティのベストプラクティス

• クライアント側のコードで client_secret やサービスアカウントキーを決して公開しないでください
• OAuth フローで CSRF を防ぐため、必ず state パラメーターを検証してください
• Google ID トークンから一意のユーザー識別子を取得するときは、email ではなく sub を使用してください
• refresh_token は安全に保管してください。これは初回の認可時にのみ返されます
• 外部の認証情報設定は使用前に検証してください（token_url と service_account_impersonation_url が googleapis.com を指していることを確認してください）
• GCP 以外の環境では、サービスアカウントキーよりも Workload Identity Federation を優先してください
• エンドユーザー向けウェブサインインでは、google-signin スキルのチェックリスト全体を適用してください。ここで一部だけを再掲すると、2 つのスキルにすでに一度生じた不整合が再び起こります
• 本番環境でシークレットが欠けている場合は、フェイルクローズにしてください。 セッション署名用シークレットと認証情報ストアのキーは、本番環境では必須であり、開発用のフォールバックは一切ありません。ハードコードされたデフォルト値を使うと、すべてのデプロイでリポジトリ内のキーを使って Cookie に署名することになります。欠落している場合は、警告を出して続行するのではなく、起動を拒否してください（DV-07）。
• ログはサニタイズし、認証情報を決して記録しないでください。 トークン、client_secret、refresh_token、セッション値をログ行、スタックトレース、エラーメッセージに含めてはいけません。ログに記録されたトークンは、ログにアクセスできる人なら誰でも手にできます。シークレットを取り除こうとするのではなく、許可リスト方式で秘匿してください。
• HTTPS は必須であり、認証情報ストアが失敗する場合もあります。 認証 Cookie には Secure を設定し、コールバックでは平文の HTTP を拒否してください（http:// 経由の OAuth コードは通信経路上にさらされます）。また、認証情報ストアの読み取り／書き込みが失敗した場合は認証エラーとして扱い、再入力を求めるか 503 を返してください。認証情報を読み込めたものとして処理を続けてはいけません。
• Python 固有：接続プーリングのため、検証間で単一の google.auth.transport.requests.Request() インスタンスを再利用してください。頻繁に呼び出される処理で呼び出しごとに新しく作成してはいけません

リファレンスファイル

• OAuth 2.0 Web Server Flow — OAuth 2.0 フロー全体：パラメーター、同意、トークン交換、更新、取り消し、段階的な認可、エラー処理（Node.js + Python）
• ADC & Service Accounts — Application Default Credentials の設定、サービスアカウントキー、JWT、Compute 認証情報、環境設定（Node.js + Python）
• Sign In with Google — Google Identity Services（GIS）、ID トークンの検証、CSRF 保護、One Tap、FedCM（Node.js + Python）
• Workload Identity Federation — AWS、Azure、OIDC/SAML フェデレーション、ワークフォース ID、実行可能ファイルから取得する認証情報（Node.js + Python）

機能低下時

• Claude Code 以外の場合（Cursor、Codex、skills CLI、API コンテナー）：パックの PreToolUse ゲートは実行されません。ライブ認証情報を拒否するのは、あなたしかいません。
• プラグインではなくコピーしてインストールした場合：ドクトリンは適用されますが、hooks/ は適用されません。
• ブラウザーがない場合、またはコンソールにアクセスできない場合：同意画面とクライアント ID の部分は人が行う作業です。該当する画面と、作業を妨げているものを明示したうえで、コード側の作業を進め、人にしか完了できないログインを繰り返し試行しないでください。

トリガー

ここに誘導するその他の語句：「OAuth 2.0 Google」、「Application Default Credentials」、 「Workload Identity Federation」、「Google ID token」、「GOOGLE_APPLICATION_CREDENTIALS」、「Google SSO」、「サービスアカウントキー」、「ID トークンを確認」。

0.16.2 の説明から移動：「Google 認証」。