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 プレイグラウンドでテストを行ってください。
このページでは、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 とアプリケーションの両方に認識されるクライアント ID やクライアント シークレットなどの OAuth 2.0 認証情報を取得します。値のセットは、作成するアプリケーションの種類によって異なります。たとえば、JavaScript アプリケーションではシークレットは必要ありませんが、ウェブサーバー アプリケーションでは必要です。
アプリが実行されるプラットフォームに適した OAuth クライアントを作成する必要があります。次に例を示します。
- Android アプリの場合は、Android アプリケーション タイプを使用します。
-
iOS アプリの場合は、iOS アプリケーション タイプを使用します。
- desktop_windows デスクトップ アプリ（Windows、macOS、Linux アプリケーション、CLI ツールなど）の場合は、デスクトップ アプリのアプリケーション タイプを使用します。
- code サーバーサイドまたは JavaScript ウェブアプリの場合は、[ウェブ アプリケーション] アプリケーション タイプを使用します。このアプリケーション タイプは、ネイティブ アプリやモバイルアプリなど、他のアプリケーションには使用しないでください。
- chrome_extension Chrome 拡張機能の場合は、Chrome 拡張機能のアプリケーション タイプを使用します。
- tv テレビや組み込みデバイスなどの入力デバイスが限られたデバイスの場合は、テレビと入力デバイスが限られたデバイスのアプリケーション タイプを使用します。
- ホスト サーバー間のやり取りには、サービス アカウントを使用します。OAuth クライアント ID は必要ありません。
2. Google 認証サーバーからアクセス トークンを取得します。
アプリケーションが Google API を使用して非公開データにアクセスするには、その API へのアクセスを許可するアクセス トークンを取得する必要があります。1 つのアクセス トークンで、複数の API に対してさまざまなレベルのアクセス権を付与できます。scope という変数パラメータは、アクセス トークンが許可するリソースとオペレーションのセットを制御します。アクセス トークンのリクエスト時に、アプリは scope パラメータで 1 つ以上の値を送信します。
このリクエストを行う方法はいくつかあり、構築するアプリケーションの種類によって異なります。たとえば、JavaScript アプリケーションは、Google へのブラウザ リダイレクトを使用してアクセス トークンをリクエストする場合があります。一方、ブラウザのないデバイスにインストールされたアプリケーションは、ウェブサービス リクエストを使用します。リクエスト方法について詳しくは、Scenariosと、各アプリタイプの実装ガイドをご覧ください。
リクエストによっては、ユーザーが 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 カレンダー API 用に発行されたアクセス トークンでは、Google コンタクト API へのアクセスは許可されません。ただし、同様のオペレーションのために、そのアクセス トークンを Google カレンダー API に複数回送信することはできます。
5. 必要に応じて、アクセス トークンを更新します。
アクセス トークンには有効期間があります。アプリケーションが 1 つのアクセス トークンの有効期間を超えて Google API にアクセスする必要がある場合は、更新トークンを取得できます。更新トークンを使用すると、アプリケーションは新しいアクセス トークンを取得できます。
シナリオ
これらのシナリオでは、OAuth 2.0 を使用して認可コードをリクエストし、さまざまなタイプのアプリケーションのアクセス トークンと更新トークンを取得する方法について説明します。
ウェブサーバー アプリケーション
Google OAuth 2.0 エンドポイントは、PHP、Java、Go、Python、Ruby、ASP.NET などの言語やフレームワークを使用するウェブサーバー アプリケーションをサポートしています。
認証シーケンスは、アプリケーションがブラウザを Google URL にリダイレクトしたときに開始されます。この URL には、リクエストされているアクセスの種類を示すクエリ パラメータが含まれています。ユーザー認証、セッションの選択、ユーザーの同意は Google が処理します。認証コードが返され、アプリケーションはそれをアクセス トークンおよび更新トークンと交換できます。
アプリケーションは、更新トークンを今後使用するために保存し、アクセス トークンを使用して Google API にアクセスします。アクセス トークンの有効期限が切れると、アプリケーションは更新トークンを使用して新しいアクセス トークンを取得します。
詳しくは、ウェブサーバー アプリケーションに OAuth 2.0 を使用するをご覧ください。
インストールしたアプリケーション
Google OAuth 2.0 エンドポイントは、パソコン、モバイル デバイス、タブレットなどのデバイスにインストールされているアプリケーションをサポートしています。 Google API Console でクライアント ID を作成する際に、インストール済みアプリケーションであることを指定し、アプリケーション タイプとして Android、Chrome 拡張機能、iOS、デスクトップ アプリのいずれかを選択します。
このプロセスにより、クライアント ID と、場合によってはクライアント シークレットが生成されます。これらをアプリケーションのソースコードに埋め込みます。（このコンテキストでは、クライアント シークレットは明らかにシークレットとして扱われません）。
認証シーケンスは、アプリケーションがブラウザを Google URL にリダイレクトしたときに開始されます。この URL には、リクエストされているアクセスの種類を示すクエリ パラメータが含まれています。ユーザー認証、セッションの選択、ユーザーの同意は Google が処理します。認証コードが返され、アプリケーションはそれをアクセス トークンと交換できます。アプリケーションは、アクセス トークンを Google API リクエストに含める前に検証する必要があります。トークンの有効期限が切れると、アプリケーションはプロセスを繰り返します。
必要に応じて、バックエンド サーバーは認証コードを更新トークンと交換し、安全な場所に保存できます。アクセス トークンの有効期限が切れると、バックエンド サーバーは更新トークンを使用してアプリケーション用の新しいアクセス トークンを取得します。
詳しくは、Android のGoogle ユーザーデータへのアクセスを承認する、iOS アプリで Google API にアクセスする、デスクトップ アプリ用 OAuth 2.0 をご覧ください。
クライアントサイド（JavaScript）アプリケーション
Google OAuth 2.0 エンドポイントは、ブラウザで実行される JavaScript アプリケーションをサポートしています。
認証シーケンスは、アプリケーションがブラウザを Google URL にリダイレクトしたときに開始されます。この URL には、リクエストされているアクセスの種類を示すクエリ パラメータが含まれています。ユーザー認証、セッションの選択、ユーザーの同意は 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 にアクセスします。トークンの有効期限が切れると、アプリケーションはプロセスを繰り返します。
詳細については、 サービス アカウントのドキュメントをご覧ください。
トークンサイズ
トークンのサイズは、次の上限まで変動する可能性があります。
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 個の更新トークンが上限となっています。 この上限値に達すると、新しい更新トークンが作成された際に自動的に一番古い更新トークンが警告なく無効化されます。この上限はサービス アカウントには適用されません。
また、ユーザー アカウントまたはサービス アカウントがすべてのクライアントで保持できる更新トークンの合計数にも、より大きな上限があります。通常のユーザーがこの上限を超えることはほとんどありませんが、実装のテストに使用されるデベロッパーのアカウントでは、上限を超える可能性があります。
複数のプログラム、マシン、デバイスを承認する必要がある場合は、Google アカウントごとに承認するクライアントの数を 15 または 20 に制限するという回避策があります。 Google Workspace 管理者は、管理者権限を持つ追加のユーザーを作成し、それらのユーザーを使用して一部のクライアントを承認できます。
Google Cloud Platform（GCP）組織のセッション管理ポリシーへの対応
GCP 組織の管理者は、Google Cloud セッション管理機能を使用して、GCP リソースにアクセスするユーザーに頻繁な再認証を要求することがあります。このポリシーは、Google Cloud コンソール、Google Cloud SDK（gcloud CLI とも呼ばれます）、Cloud Platform スコープを必要とするサードパーティの OAuth アプリケーションへのアクセスに影響します。ユーザーにセッション制御ポリシーが適用されている場合、セッション継続時間が終了すると、更新トークンが取り消された場合と同様に API 呼び出しがエラーになります。呼び出しはエラータイプ invalid_grant で失敗します。error_subtype フィールドを使用すると、取り消されたトークンと、セッション制御ポリシーによるエラー（"error_subtype": "invalid_rapt" など）を区別できます。セッション継続時間は非常に短い（1 ～ 24 時間）場合があるため、このシナリオは、認証セッションを再開することで適切に処理する必要があります。
同様に、サーバー間デプロイにユーザー認証情報を使用したり、使用を推奨したりしてはなりません。長時間実行されるジョブまたはオペレーションのためにユーザー認証情報がサーバーにデプロイされ、お客様がそのようなユーザーにセッション制御ポリシーを適用すると、セッション継続時間が終了したときにユーザーを再認証する方法がないため、サーバー アプリケーションは失敗します。
お客様がこの機能をデプロイするのをサポートする方法について詳しくは、こちらの管理者向けヘルプ記事をご覧ください。
クライアント ライブラリ
次のクライアント ライブラリは、一般的なフレームワークと統合されているため、OAuth 2.0 の実装が簡単になります。今後、ライブラリにさらに多くの機能が追加される予定です。