OAuth2のinvalid_grantエラーの意味

n8nを利用してGoogle DriveやGoogle SheetsなどのGoogleサービスと連携していると、突然ワークフローが停止し、「The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.」というエラーメッセージに遭遇することがあります。この長いメッセージは、OAuth2の文脈では「invalid_grant」エラーとして知られています。私自身もこのエラーに直面した際、最初はどこから手をつけて良いか途方に暮れました。

この「invalid_grant」エラーは、一言で言えば「発行された認可コードやリフレッシュトークンが無効扱いになっている」ことを示すものです。OAuth2の仕様上、アクセストークンは短命であり、その更新にはリフレッシュトークンが使われます。このリフレッシュトークンが何らかの理由で使えなくなると、このエラーが発生します。

具体的に、このエラーメッセージが指し示す原因は複数あります。認可コードやリフレッシュトークンが「無効」になっているか、「有効期限切れ（expired）」、「取り消された（revoked）」、あるいは「認可リクエスト時に使ったredirect_uriと一致していない」、または「そのトークンが発行されたものとは別のクライアントID（別クライアント）で使おうとしている」のいずれか、または複数に該当する場合に表示されます。

一般的な発生条件としては、例えば、一度アクセストークンに交換した認可コードを再度使おうとした場合や、リフレッシュトークンの有効期限が過ぎた、またはサーバー側で無効化された場合が挙げられます。また、トークン発行時と異なるredirect_uriを指定してトークン取得や更新を試みた場合、あるいはトークンを発行したクライアントとは別のclient_id/client_secretでトークンエンドポイントを叩いた場合にもこのエラーは発生します。

これらの原因を理解することは、問題解決の第一歩となります。特にn8nのような自動化ツールでGoogleサービスと連携している場合、バックグラウンドでトークンが更新されるため、エラーが発生した際にはこれらの基本的な原因に立ち返って考えることが重要です。

n8nとGoogle連携で特に多い原因

• Google OAuth同意画面がTestingモードのままのためリフレッシュトークンが7日で失効する問題
  これは最も多く、かつ見落としがちな原因です。Google CloudプロジェクトのOAuth同意画面が「Testing（テスト）」状態のままだと、そのプロジェクトから発行されるリフレッシュトークンは7日で自動的に期限切れとなります。7日を過ぎると、n8nがリフレッシュトークンを使ってアクセストークンを更新しようとした際に、Google側から「invalid_grant」エラーが返され、ワークフローが停止してしまいます。この問題は、特に開発環境から本番環境へ移行する際に忘れられがちです。
• Authorized redirect URIの不一致による認証失敗
  Google Cloud Consoleに登録した「Authorized redirect URI」と、n8nが実際に使っている「OAuth Redirect URL」が完全に一致していない場合も、認証が失敗し「invalid_grant」エラーが発生します。これは、スキーム（http/https）、ドメイン、ポート番号、そしてパス（例: /rest/oauth2-credential/callback）まで、1文字単位で完全に一致している必要があります。少しでも異なると、Google側は不正なリクエストと判断し、トークンの発行や更新を拒否します。
• Docker運用時のデータボリューム未永続化によるトークン消失
  n8nをDockerコンテナで運用している場合、/home/node/.n8nなどのデータディレクトリが永続ボリュームにマウントされていないと、コンテナの再作成や再起動時に保存されていた資格情報（リフレッシュトークンを含む）が失われてしまいます。これにより、n8nは既存のトークンを使えなくなり、再認証が必要となります。この問題は、特に開発環境で手軽にコンテナを立て直す際に発生しやすいです。
• ユーザー側でGoogleアプリのアクセス権を取り消したケース
  Googleアカウントのセキュリティ設定から、ユーザー自身がn8nアプリへのアクセス権を取り消した場合も、リフレッシュトークンは無効化されます。また、Googleアカウントのパスワード変更や、セキュリティ設定の変更などによって、既存のトークンが無効になることもあります。これはユーザーの意図的な操作や、セキュリティ上の理由で発生するため、n8n側から見ると突然認証が切れたように見えます。

根本対策：OAuth同意画面をProductionに切り替える

• 「invalid_grant」エラーの最も一般的な原因がGoogle OAuth同意画面のTestingモードによるリフレッシュトークンの7日失効である場合、その根本的な解決策は、同意画面の公開ステータスを「Production（本番環境）」に切り替えることです。この手順は、長期的な安定運用を目指す上で不可欠であり、私自身もこの設定変更で多くの問題を解決してきました。
• 具体的な手順は以下の通りです。

1. Google Cloud Consoleにアクセス:
   まずは、エラーが発生しているGoogle Cloudプロジェクトのコンソールにログインします。
2. OAuth同意画面を開く:
   左側のナビゲーションメニューから「APIとサービス」→「OAuth同意画面」を選択します。
3. 公開ステータスの確認と変更:
   現在の公開ステータスが「Testing」になっていることを確認します。これを「In production（本番環境）」に変更します。通常、「アプリを公開」のようなボタンやリンクが表示されているはずです。この変更により、発行されるリフレッシュトークンが長寿命化され、7日での失効問題が解消されます。
4. 必要な情報の入力:
   Production化には、いくつかの情報入力が求められます。これには、アプリ名、ユーザーサポートメール、アプリのロゴ、プライバシーポリシーURL、利用規約URLなどが含まれます。これらの情報は、ユーザーが認証を行う際に表示される同意画面に表示されるため、正確かつ適切に設定することが重要です。特にプライバシーポリシーURLは必須となる場合が多いので、事前に用意しておきましょう。
5. センシティブ・制限付きスコープの審査プロセス:
   もし、Google DriveやGoogle Sheetsなどのサービスで、ユーザーデータへのアクセス権限（スコープ）が「センシティブ」または「制限付き」に分類されるものを使用している場合、Production化の際にGoogleによる審査プロセスが必要になることがあります。この審査には数日から数週間かかる場合があるため、余裕を持ったスケジュールで対応することが肝心です。審査が通らないと、Production状態に移行できない、または一部の機能が利用できない可能性があります。
6. 変更の保存と公開:
   必要な情報をすべて入力し終えたら、変更を保存して公開プロセスを完了させます。これにより、OAuth同意画面が正式にProduction状態となり、長寿命のリフレッシュトークンが発行される準備が整います。

この手順を完了することで、リフレッシュトークンの失効問題は根本的に解決され、n8nとGoogleサービスの連携が安定します。手間がかかるように思えるかもしれませんが、一度設定してしまえば、その後の運用が格段に楽になります。

n8nでの再認証手順

Google Cloud ConsoleでOAuth同意画面をProductionに切り替えただけでは、既存のn8nの資格情報が自動的に更新されるわけではありません。新しい長寿命のリフレッシュトークンを取得するためには、n8n側で再度認証を行う必要があります。この手順は非常にシンプルですが、忘れずに行うことが重要です。

1. n8nの資格情報画面を開く:
   n8nのUIにログインし、左側のメニューから「Credentials（資格情報）」を選択します。Googleサービスと連携している既存の資格情報（例: Google Sheets Credential）を見つけてクリックし、編集画面を開きます。
2. 「Sign in with Google」ボタンをクリック:
   資格情報の編集画面内に、「Sign in with Google」または「Reauthenticate with Google」といったボタンが表示されているはずです。このボタンをクリックします。これにより、Googleの認証フローが再度開始されます。
3. Googleアカウントを選択し、権限を許可する:
   Googleの認証画面が表示されたら、n8nと連携させたいGoogleアカウントを選択し、n8nが要求する権限（スコープ）を許可します。この際、OAuth同意画面がProductionになっているため、以前のように7日で失効するリフレッシュトークンではなく、長寿命のリフレッシュトークンが発行されます。
4. 動作確認:
   再認証が完了したら、該当のワークフローを再度実行してみてください。以前発生していた「invalid_grant」エラーが解消され、ワークフローが正常に動作することを確認します。これで、Googleサービスとの連携が安定的に行われるようになります。私の場合も、この再認証を行うことで、すぐにワークフローが動き出すことを確認できました。

すぐできるワークアラウンド案

Google Cloud ConsoleでのProduction化や審査プロセスには時間がかかる場合があります。あるいは、小規模な個人利用でそこまで厳密な設定は避けたい、というケースもあるかもしれません。そのような場合に、一時的または限定的な解決策として利用できるワークアラウンドをいくつかご紹介します。これらは根本解決ではありませんが、緊急時の対応や特定の状況下での運用に役立ちます。

• 定期的に手動でn8nの資格情報画面から再認証する運用方法
  OAuth同意画面がTestingモードのままである場合、リフレッシュトークンは7日で失効します。このため、ワークフローが停止する前に、定期的に（例えば週に1回など）n8nのGoogle資格情報画面を開き、「Sign in with Google」ボタンをクリックして再認証を行うことで、新しいリフレッシュトークンを取得し直すことができます。これは手動での運用が必要になりますが、Production化の手間をかけずに一時的に問題を回避できます。ただし、再認証を忘れるとワークフローが停止するため、運用上の注意が必要です。
• Service Accountを利用可能なサービスで切り替えるメリットと方法
  Google DriveやGoogle Sheets、Google Calendarなど、一部のGoogleサービスは、ユーザーアカウントのOAuth認証だけでなく、「Service Account（サービスアカウント）」を利用して認証を行うことが可能です。サービスアカウントは、特定のGoogle Cloudプロジェクトに紐づく仮想的なアカウントであり、ユーザーの同意画面を介さずにAPIアクセスが可能です。これにより、リフレッシュトークンの7日失効問題や、ユーザーによるアクセス権取り消しといった問題から解放されます。
  • メリット: トークン失効の心配がなく、安定した運用が可能。ユーザーアカウントに依存しないため、セキュリティ面でもメリットがあります。
  • 方法: Google Cloud Consoleでサービスアカウントを作成し、必要な権限（ロール）を付与します。その後、サービスアカウントのキーファイル（JSON形式）をダウンロードし、n8nのGoogle資格情報で「Service Account」を選択してキーファイルをアップロードします。各Googleノードの設定で、このサービスアカウント資格情報を選択することで利用できます。
• ワークアラウンドのメリット・デメリット
  • メリット: 迅速な問題回避、Production化の手間や審査プロセスを回避できる、Service Account利用で安定性を向上できる。
  • デメリット: 手動再認証は運用負荷が高い、Service Accountは対応していないサービスもある、Service Accountの権限管理を適切に行う必要がある。これらのワークアラウンドは、あくまで一時的な対応や特定のユースケースに限定して利用を検討すべきです。長期的な安定運用を目指すのであれば、やはりOAuth同意画面のProduction化が最善策です。