OAuth 2.0 を使用して Google API にアクセスする

Google API は、認証と認可に OAuth 2.0 プロトコルを使用します。Google は、ウェブサーバー アプリケーション、クライアントサイド アプリケーション、インストール済みデバイス、制限付き入力デバイス アプリケーションなど、OAuth 2.0 の一般的なシナリオをサポートしています。

まず、 Google API Console から OAuth 2.0 クライアント認証情報を取得します。次に、クライアント アプリケーションが Google 承認サーバーにアクセス トークンをリクエストし、レスポンスからトークンを抽出し、アクセスする Google API にそのトークンを送信します。Google で OAuth 2.0 を使用する方法をインタラクティブなデモンストレーションで確認するには（独自のクライアント認証情報を使用するオプションも含めて）、OAuth 2.0 Playground を試してください。

このページでは、Google がサポートする OAuth 2.0 認可シナリオの概要を説明し、さらに詳細なコンテンツへのリンクを紹介します。認証に OAuth 2.0 を使用する方法については、OpenID Connect をご覧ください。

基本手順

OAuth 2.0 を使用して Google API にアクセスする場合、すべてのアプリケーションは基本的なパターンに従います。大まかには、次の 5 つの手順を行います。

1. Google API Consoleから OAuth 2.0 認証情報を取得します。

Google API Console にアクセスして、Google とアプリケーションの両方が認識している OAuth 2.0 認証情報（クライアント ID やクライアント シークレットなど）を取得します。値のセットは、構築するアプリのタイプによって異なります。たとえば、JavaScript アプリケーションにはシークレットは必要ありませんが、ウェブサーバー アプリケーションには必要です。

アプリが実行されるプラットフォームに適した OAuth クライアントを作成する必要があります。次に例を示します。

2. Google 承認サーバーからアクセス トークンを取得します。

アプリケーションが Google API を使用して個人データにアクセスするには、その API へのアクセスを許可するアクセス トークンを取得する必要があります。1 つのアクセス トークンで、複数の API にさまざまなレベルのアクセス権を付与できます。scope という変数パラメータにより、アクセス トークンで許可されるリソースとオペレーションのセットが制御されます。アクセス トークンのリクエスト中に、アプリケーションは scope パラメータで 1 つ以上の値を送信します。

このリクエストを行う方法はいくつかあり、構築するアプリケーションの種類によって異なります。たとえば、JavaScript アプリケーションは、ブラウザが Google にリダイレクトしてアクセス トークンをリクエストし、ブラウザのないデバイスにインストールされているアプリケーションはウェブサービス リクエストを使用します。

一部のリクエストでは、ユーザーが Google アカウントでログインする認証手順が必要です。ログイン後、ユーザーは、アプリがリクエストしている 1 つ以上の権限を付与するかどうかを尋ねられます。このプロセスをユーザーの同意と呼びます。

ユーザーが少なくとも 1 つの権限を付与した場合、Google 承認サーバーはアクセス トークン（またはアプリケーションがアクセス トークンを取得するために使用できる認可コード）と、そのトークンによって付与されるアクセスのスコープのリストをアプリケーションに送信します。ユーザーが権限を付与しないと、サーバーからエラーが返されます。

通常は、事前にではなく、アクセスが必要になったときに段階的にスコープをリクエストすることをおすすめします。たとえば、カレンダーへのイベントの保存をサポートするアプリでは、ユーザーが [カレンダーに追加] ボタンを押すまで Google カレンダーへのアクセスをリクエストしないでください。段階的な承認をご覧ください。

3. ユーザーが付与したアクセス権のスコープを調べる

アクセス トークンのレスポンスに含まれるスコープと、関連する Google API へのアクセスに依存するアプリケーションの機能にアクセスするために必要なスコープを比較します。関連する API にアクセスしないと動作しないアプリの機能をすべて無効にします。

リクエスト内のスコープが、リクエストされたスコープをすべて付与したとしても、レスポンスに含まれるスコープと一致しない場合があります。アクセスに必要なスコープについては、各 Google API のドキュメントをご覧ください。API は、複数のスコープ文字列値を 1 つのアクセス スコープにマッピングし、リクエストで許可されたすべての値に対して同じスコープ文字列を返すことがあります。 たとえば、アプリがユーザーに https://www.google.com/m8/feeds/ のスコープの承認をリクエストした場合、Google People API は https://www.googleapis.com/auth/contacts のスコープを返すことがあります。Google People API のメソッド people.updateContact には、https://www.googleapis.com/auth/contacts の許可されたスコープが必要です。

4. アクセス トークンを API に送信します。

アプリケーションはアクセス トークンを取得した後、 HTTP 認可リクエスト ヘッダーを使用してトークンを Google API に送信します。トークンを URI クエリ文字列パラメータとして送信することは可能ですが、推奨されません。URI パラメータがログファイルに保存され、完全には保護されない可能性があるためです。また、不要な URI パラメータ名を作成しないように、REST を使用することをおすすめします。

アクセス トークンは、トークン リクエストの scope に記述されている一連のオペレーションとリソースに対してのみ有効です。たとえば、Google Calendar API 用のアクセス トークンが発行されても、Google Contacts API へのアクセスは付与されません。ただし、同様の操作を行うために、そのアクセス トークンを Google Calendar API に複数回送信できます。

5. 必要に応じてアクセス トークンを更新します。

アクセス トークンには有効期間があります。アプリケーションで 1 つのアクセス トークンの有効期間を超えて Google API にアクセスする必要がある場合は、更新トークンを取得できます。更新トークンを使用すると、アプリケーションは新しいアクセス トークンを取得できます。

シナリオ

ウェブサーバーアプリケーション

Google OAuth 2.0 エンドポイントは、PHP、Java、Python、Ruby、ASP.NET などの言語とフレームワークを使用するウェブサーバー アプリケーションをサポートしています。

アプリケーションがブラウザを Google URL にリダイレクトすると、認可シーケンスが開始されます。この URL には、リクエストされているアクセスの種類を示すクエリ パラメータが含まれています。Google がユーザー認証、セッションの選択、ユーザーの同意を処理します。その結果が認証コードとなり、アプリケーションはこれをアクセス トークンと更新トークンと交換できます。

アプリケーションは、今後使用するために更新トークンを保存し、そのアクセス トークンを使用して Google API にアクセスする必要があります。アクセス トークンが期限切れになると、アプリケーションは更新トークンを使用して新しいトークンを取得します。

アプリケーションが Google 承認サーバーにトークン リクエストを送信して認可コードを受信し、コードをトークンと交換して、そのトークンを使用して Google API エンドポイントを呼び出します。

詳しくは、ウェブサーバー アプリケーションに OAuth 2.0 を使用するをご覧ください。

インストール型アプリケーション

Google OAuth 2.0 エンドポイントは、パソコン、モバイル デバイス、タブレットなどのデバイスにインストールされているアプリケーションをサポートします。 Google API Console を使用してクライアント ID を作成する場合は、これがインストール済みのアプリケーションであることを指定し、アプリケーションの種類として Android、Chrome アプリ、iOS、ユニバーサル Windows プラットフォーム（UWP）、デスクトップ アプリを選択します。

このプロセスによりクライアント ID が生成されます。また、場合によってはクライアント シークレットが生成されます。これをアプリケーションのソースコードに埋め込みます。（この場合、クライアント シークレットは明らかにシークレットとして扱われません）。

アプリケーションがブラウザを Google URL にリダイレクトすると、認可シーケンスが開始されます。この URL には、リクエストされているアクセスの種類を示すクエリ パラメータが含まれています。Google がユーザー認証、セッションの選択、ユーザーの同意を処理します。その結果が認証コードとなり、アプリケーションはこれをアクセス トークンと更新トークンと交換できます。

アプリケーションは、今後使用するために更新トークンを保存し、そのアクセス トークンを使用して Google API にアクセスする必要があります。アクセス トークンが期限切れになると、アプリケーションは更新トークンを使用して新しいトークンを取得します。

アプリケーションが Google 承認サーバーにトークン リクエストを送信して認可コードを受信し、コードをトークンと交換して、そのトークンを使用して Google API エンドポイントを呼び出します。

詳しくは、 インストール済みのアプリケーションに OAuth 2.0 を使用するをご覧ください。

クライアントサイド（JavaScript）アプリケーション

Google OAuth 2.0 エンドポイントは、ブラウザ内で動作する JavaScript アプリケーションをサポートしています。

アプリケーションがブラウザを Google URL にリダイレクトすると、認可シーケンスが開始されます。この URL には、リクエストされているアクセスの種類を示すクエリ パラメータが含まれています。Google がユーザー認証、セッションの選択、ユーザーの同意を処理します。

その結果がアクセス トークンになります。クライアントはこのトークンを検証してから、Google API リクエストに含める必要があります。トークンが期限切れになると、アプリケーションはこのプロセスを繰り返します。

JS アプリケーションが Google 承認サーバーにトークン リクエストを送信し、トークンを受信して検証し、そのトークンを使用して Google API エンドポイントを呼び出します。

詳しくは、クライアントサイド アプリケーションに OAuth 2.0 を使用するをご覧ください。

入力が限られたデバイス上のアプリケーション

Google OAuth 2.0 エンドポイントは、ゲーム機、ビデオカメラ、プリンタなどの制限付き入力デバイスで実行されるアプリケーションをサポートしています。

認可シーケンスは、アプリケーションがウェブサービス リクエストを Google URL に対して認可コードを求めることから始まります。レスポンスには、アプリケーションがユーザーに表示する URL やコードなど、いくつかのパラメータが含まれます。

ユーザーはデバイスから URL とコードを取得してから、入力機能を備えた別のデバイスまたはパソコンに切り替えます。ユーザーがブラウザを起動して指定された URL に移動し、ログインしてコードを入力します。

一方、アプリケーションは指定された間隔で Google URL をポーリングします。ユーザーがアクセスを承認すると、Google サーバーからのレスポンスにアクセス トークンと更新トークンが含まれます。アプリケーションは、今後使用するために更新トークンを保存し、そのアクセス トークンを使用して Google API にアクセスする必要があります。アクセス トークンが期限切れになると、アプリケーションは更新トークンを使用して新しいトークンを取得します。

ブラウザを搭載した別のデバイスでユーザーがログインしている

詳細については、デバイスに OAuth 2.0 を使用するをご覧ください。

サービス アカウント

Prediction API や Google Cloud Storage などの Google API は、ユーザー情報にアクセスすることなく、アプリケーションに代わって動作できます。このような場合、アプリケーションは API に対して自身の ID を証明する必要がありますが、ユーザーの同意は必要ありません。同様に、企業のシナリオでは、アプリケーションから一部のリソースへの委任アクセスをリクエストできます。

このようなサーバー間インタラクションには、個々のエンドユーザーではなく、アプリケーションに属するアカウントであるサービス アカウントが必要です。アプリケーションがサービス アカウントに代わって Google API を呼び出し、ユーザーの同意は必要ありません。（サービス アカウント以外のシナリオでは、アプリケーションがエンドユーザーに代わって Google API を呼び出し、ユーザーの同意が必要になる場合があります）。

Google API Consoleから取得するサービス アカウントの認証情報には、生成された一意のメールアドレス、クライアント ID、1 つ以上の公開鍵/秘密鍵のペアが含まれます。クライアント ID と 1 つの秘密鍵を使用して署名付き JWT を作成し、適切な形式のアクセス トークン リクエストを作成します。次に、アプリケーションがトークン リクエストを Google OAuth 2.0 認可サーバーに送信し、そこからアクセス トークンが返されます。アプリケーションはこのトークンを使用して Google API にアクセスします。トークンが期限切れになると、アプリケーションはこのプロセスを繰り返します。

サーバー アプリケーションは、JWT を使用して Google 承認サーバーにトークンをリクエストし、そのトークンを使用して Google API エンドポイントを呼び出します。エンドユーザーは関与しません。

詳細については、 サービス アカウントのドキュメントをご覧ください。

トークンサイズ

トークンのサイズは、次の上限までさまざまです。

  • 認証コード: 256 バイト
  • アクセス トークン: 2,048 バイト
  • 更新トークン: 512 バイト

Google Cloud の Security Token Service API から返されるアクセス トークンは、Google API OAuth 2.0 アクセス トークンとよく似ていますが、トークンサイズの上限が異なります。詳しくは、 API ドキュメントをご覧ください。

Google は、この制限内でトークンのサイズを変更する権限を有します。また、アプリは、それに応じた可変トークンサイズをサポートする必要があります。

更新トークンの有効期限

付与された更新トークンが機能しなくなる可能性を考慮したコードを記述する必要があります。更新トークンは、次のいずれかの理由で機能しなくなることがあります。

外部ユーザータイプ用に OAuth 同意画面が構成され、公開ステータスが「テスト」である Google Cloud Platform プロジェクトには、7 日後に期限切れになる更新トークンが発行されます。ただし、リクエストされた OAuth スコープが、（ userinfo.email, userinfo.profile, openid スコープまたは OpenID Connect の同等のものを介して）名前、メールアドレス、ユーザー プロファイルのサブセットである場合を除きます。

現在、1 つの OAuth 2.0 クライアント ID につき、Google アカウントごとに 100 個の更新トークンという上限があります。上限に達した場合、新しい更新トークンを作成すると、警告なしで最も古い更新トークンが自動的に無効になります。この上限はサービス アカウントには適用されません。

また、ユーザー アカウントまたはサービス アカウントがすべてのクライアントで保持できる更新トークンの総数には、さらに上限があります。通常のユーザーの多くはこの上限を超えることはありませんが、実装のテストに使用されるデベロッパー アカウントであれば上限を超える可能性があります。

複数のプログラム、マシン、デバイスを承認する必要がある場合は、回避策の 1 つとして、Google アカウントごとに承認するクライアントの数を 15 個または 20 個に制限します。 Google Workspace 管理者は、管理者権限を持つ追加ユーザーを作成し、それらを使用して一部のクライアントを認可できます。

Google Cloud Platform（GCP）組織のセッション管理ポリシーの取り扱い

GCP 組織の管理者は、GCP リソースにアクセスする際に、Google Cloud セッション管理機能を使用してユーザーの再認証を頻繁に行うことが必要になる場合があります。このポリシーは、Google Cloud コンソール、Google Cloud SDK（gcloud CLI）、Cloud Platform スコープを必要とするサードパーティの OAuth アプリケーションへのアクセスに影響します。ユーザーがセッション コントロール ポリシーを設定している場合、セッション継続時間が終了すると、API 呼び出しは、更新トークンが取り消された場合と同じようにエラーになります。呼び出しはエラータイプ invalid_grant で失敗します。error_subtype フィールドを使用すると、取り消されたトークンとセッション制御ポリシー（"error_subtype": "invalid_rapt" など）による失敗を区別できます。このシナリオでは、セッション継続時間は 2 時間から 1 時間まで、非常に制限可能です。

同様に、サーバー間のデプロイにユーザー認証情報を使用したり、使用を奨励したりすることはできません。長時間実行されるジョブまたはオペレーションのためにユーザー認証情報がサーバーにデプロイされていて、お客様がそのようなユーザーにセッション管理ポリシーを適用した場合、セッション継続時間が終了したときにユーザーを再認証する方法がないため、サーバー アプリケーションは失敗します。

お客様によるこの機能のデプロイをサポートする方法の詳細については、こちらの管理者に焦点を当てたヘルプ記事をご覧ください。

クライアント ライブラリ

次のクライアント ライブラリは一般的なフレームワークと統合されているため、OAuth 2.0 の実装がより簡単になります。今後、さらに多くの機能がライブラリに追加される予定です。