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 にアクセスする場合、基本的なパターンに従います。大まかな手順は次のとおりです。

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

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

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

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

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

一部のリクエストでは、ユーザーが Google アカウントでログインする認証手順が必要になります。ログイン後、アプリからリクエストされている 1 つまたは複数の権限を付与するかどうかをユーザーに確認します。このプロセスをユーザーの同意といいます。

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

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

3. ユーザーが付与したアクセス スコープを調べます。

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

ユーザーがリクエストしたすべてのスコープを付与していても、リクエストに含まれるスコープはレスポンスに含まれるスコープと一致しないことがあります。アクセスに必要なスコープについては、各 Google API のドキュメントをご覧ください。API は複数のスコープ文字列値を単一のアクセス スコープにマッピングし、リクエストで許可されたすべての値に対して同じスコープ文字列を返すことができます。例: ユーザーがアプリにスコープ 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 パラメータは完全に安全なログファイルではなくなる可能性があるためです。また、REST URI が不要な URI の名前を作らないようにすることをおすすめします。

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

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

アクセス トークンには有効期間があります。アプリケーションが単一のアクセス トークンの有効期間を超えて 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 と秘密鍵を使用して署名付き 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 は、これらの制限内でトークンサイズを変更する権利を有しており、アプリケーションは、それに応じて可変のトークンサイズをサポートする必要があります。

更新トークンの有効期限

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

  • ユーザーがアプリのアクセス権を取り消しました
  • 更新トークンは 6 か月間使用されていません。
  • ユーザーがパスワードを変更し、更新トークンに Gmail のスコープが含まれています。
  • このユーザー アカウントで、付与できる更新トークンの最大数を超えました。
  • ユーザーが、セッション管理ポリシーが有効になっている Google Cloud Platform 組織に属している。

外部ユーザータイプ用に OAuth 同意画面が構成され、公開ステータスが「テスト中」である Google Cloud Platform プロジェクトは、7 日後に有効期限切れの更新トークンが発行されます。

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

また、ユーザー アカウントまたはサービス アカウントがすべてのクライアントに対して使用できる更新トークンの合計数にも上限があります。通常のユーザーは通常この上限を超えることはありませんが、実装のテストに使用されるデベロッパー アカウントは通常、

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

Google Cloud Platform(GCP)組織のセッション管理ポリシーに対処する

GCP 組織の管理者は、ユーザーが Google Cloud セッション管理機能を使用して GCP リソースにアクセスする際に、頻繁に再認証を行う可能性があります。このポリシーは、Google Cloud Console、Google Cloud SDK(gcloud CLI とも呼ばれます)、Cloud Platform スコープを必要とするサードパーティの OAuth アプリケーションへのアクセスに影響します。ユーザーがセッション管理ポリシーを適用している場合、セッション継続期間が終了すると、更新トークンが取り消された場合に発生する可能性のある呼び出しと同様のエラーが API 呼び出しで発生します。つまり、呼び出しは失敗し、エラータイプ invalid_token で失敗します。サブエラーの種類は、取り消しトークンとセッション管理ポリシーによる失敗を区別するために使用できます。セッション継続時間は非常に限られているため(1 時間~ 24 時間)、このシナリオでは認証セッションを再開して適切に処理する必要があります。

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

顧客がこの機能を展開できるようにする方法については、こちらの管理者向けのヘルプ記事をご覧ください。

クライアント ライブラリ

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