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

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

まず、OAuth 2.0 クライアント認証情報を Google API Console から取得します。次に、クライアント アプリケーションは 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、Go、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 の同等のもの）である場合を除く。

現在、更新トークンの上限は、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" など）による失敗を区別できます。セッション継続時間は、グレースフル リスタートのシナリオでは 4 時間から 2 時間までと非常に制限されるため、セッション継続時間は 1 時間から非常に制限されます。

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

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

クライアント ライブラリ

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