Google OAuth 2.0 主要エラー一覧と対処法｜invalid_grantなど

編集

この記事の要点

Google OAuth 2.0 で返るエラーは RFC 6749 準拠の error コードと Google 固有の文字列が混在
頻出: invalid_request / invalid_client / invalid_grant / redirect_uri_mismatch / access_denied
redirect_uri_mismatch はCloud Console の「承認済みリダイレクト URI」と完全一致が必要（末尾スラッシュ・http/https・ポートまで含む）
invalid_grant はリフレッシュトークン無効化（再同意 / パスワード変更 / 7日経過の未公開アプリ）が多い
スコープ変更時は再同意 (consent) が必要。prompt=consent で強制可

Google OAuth 2.0 のエラーレスポンス

Google の OAuth 2.0 エンドポイント（accounts.google.com/o/oauth2/v2/auth や oauth2.googleapis.com/token）が返すエラーは、RFC 6749 で定められた error / error_description の形式で返ります。原因究明には error_description と Cloud Console の OAuth クライアント設定の突き合わせが基本です。

// token エンドポイントの例
{
  "error": "invalid_grant",
  "error_description": "Token has been expired or revoked."
}

主要エラー一覧と対処

error	意味	主な原因 / 対処
`invalid_request`	パラメータ不足 / 形式不正	必須パラメータ（`client_id`, `redirect_uri`, `response_type`, `scope`）の漏れ。スペル / URL エンコードを確認
`invalid_client`	クライアント認証失敗	`client_id` / `client_secret` の値が違う。シークレットを再生成して環境変数を更新
`invalid_grant`	付与情報が無効	リフレッシュトークン失効、認可コードを 2 回使った、コード期限切れ（数十秒）、ユーザがパスワード変更、未公開アプリで 7 日経過、時刻ずれ
`unauthorized_client`	クライアントが許可されていない	そのクライアントタイプに許可されていないグラントを使った。Cloud Console のアプリ種別を確認
`unsupported_grant_type`	未対応 grant_type	サポートされる: `authorization_code` / `refresh_token` / `urn:ietf:params:oauth:grant-type:jwt-bearer`
`invalid_scope`	スコープ不正	スコープ文字列のスペル誤り、有効化していない API のスコープ要求
`access_denied`	ユーザが同意を拒否	同意画面で「許可しない」を押した。アプリ未公開で対象外ユーザがログインした場合も発生
`redirect_uri_mismatch`	リダイレクト URI 不一致	Cloud Console の「承認済みリダイレクト URI」と完全一致していない。プロトコル / ポート / 末尾スラッシュ / クエリすべて含む
`admin_policy_enforced`	Workspace 管理者が制限	組織管理者がアプリを許可していない
`disallowed_useragent`	埋め込み WebView 拒否	WebView / 古い UA からのログインは 2021 年以降不可。システムブラウザを使う
`org_internal`	組織内ユーザ限定	「内部」公開設定のアプリに組織外ユーザがアクセス
`deleted_client`	削除済みクライアント	Cloud Console で削除した `client_id` を使っている
`idpiframe_initialization_failed`	旧 GIS / GAPI クライアント側	サードパーティ Cookie 無効化など。新 GIS（Google Identity Services）に移行

頻発: redirect_uri_mismatch

OAuth 開発で最も詰まるのがこれです。Google は文字列の完全一致を見ています。

Cloud Console 登録	リクエスト URI	結果
`http://localhost:3000/callback`	`http://localhost:3000/callback`	OK
`http://localhost:3000/callback`	`http://localhost:3000/callback/`	NG（末尾スラッシュ）
`http://localhost:3000/callback`	`http://127.0.0.1:3000/callback`	NG（ホスト名違い）
`https://app.example.com/cb`	`http://app.example.com/cb`	NG（プロトコル違い）

頻発: invalid_grant

下記いずれかで起きます。とくにリフレッシュトークンの失効条件を覚えておくとよいです。

認可コードを2 回トークンエンドポイントに送った
認可コードの有効期限切れ（数十秒〜数分）
ユーザがパスワードを変更した、または「アカウントへのアクセス権を取り消し」した
未公開（テスト）アプリのリフレッシュトークンは7 日で失効
サーバの時刻ずれ（JWT で iat/exp が不整合）
1 ユーザあたり 100 個を超えるリフレッシュトークンを発行（古いものから失効）

同意のリセットと再取得

スコープを追加した、または失効したリフレッシュトークンを取り直したいときは、認可リクエストに prompt=consent と access_type=offline を付けます。

https://accounts.google.com/o/oauth2/v2/auth
  ?client_id=...
  &redirect_uri=https://app.example.com/oauth/callback
  &response_type=code
  &scope=openid%20email%20profile
  &access_type=offline       (リフレッシュトークン要求)
  &prompt=consent            (毎回同意画面を出して再発行)
  &state=xxxxxxxx

デバッグの手順

error と error_description を必ずログに残す
Cloud Console の OAuth クライアント設定（種別 / 承認済み JS 元 / 承認済みリダイレクト URI）を再確認
使っているスコープに対応する API が「有効な API とサービス」で有効化されているか
未公開アプリならテストユーザに対象 Google アカウントを追加
サーバ時刻が NTP で同期されているか確認

ページ一覧

その他