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 にアクセスする場合、すべてのアプリケーションは基本的なパターンに従います。大まかな手順は次のとおりです。
1. Google API Consoleから OAuth 2.0 認証情報を取得します。
Google API Console にアクセスして、Google とアプリケーションの両方で認識されるクライアント ID やクライアント シークレットなどの OAuth 2.0 認証情報を取得します。値のセットは、構築するアプリケーションのタイプによって異なります。たとえば、JavaScript アプリケーションにはシークレットは必要ありませんが、ウェブサーバー アプリケーションには必要です。
アプリが実行されるプラットフォームに適した OAuth クライアントを作成する必要があります。例:
- コード サーバーサイドまたは JavaScript ウェブアプリの場合は、クライアント タイプとして「ウェブ」を使用します。このクライアント タイプは、ネイティブ アプリやモバイルアプリなどの他のアプリケーションには使用しないでください。
- Android アプリの場合は、「Android」クライアント タイプを使用します。
-
iOS アプリと macOS アプリの場合は、「iOS」クライアント タイプを使用します。 - ユニバーサル Windows プラットフォーム アプリの場合は、「ユニバーサル Windows プラットフォーム」クライアント タイプを使用します。
- tv テレビや組み込みデバイスなどの入力が限られたデバイスの場合は、「テレビと入力が限られたデバイス」クライアント タイプを使用します。
- ホスト : サーバー間のやり取りには、サービス アカウントを使用します。
2. Google 認可サーバーからアクセス トークンを取得します。
Google API を使用してアプリケーションによる個人データへのアクセスを許可する際は、事前に API によるアクセスを許可するアクセス トークンを取得する必要があります。単一のアクセス トークンで、複数の API へのさまざまなレベルのアクセス権を付与できます。scope という変数パラメータは、アクセス トークンが許可するリソースとオペレーションのセットを制御します。アクセス トークンのリクエスト中は、アプリケーションによって scope パラメータの値が送信されます。
このリクエストを行う方法はいくつかあり、構築するアプリケーションのタイプによって異なります。たとえば、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 パラメータは完全に安全ではないログファイルに記録される可能性があるため、おすすめしません。また、不要な URI パラメータ名を作成しないことも、REST の良いプラクティスです。
アクセス トークンは、トークン リクエストの scope で説明されているオペレーションとリソースのセットに対してのみ有効です。たとえば、Google Calendar API 用に発行されたアクセス トークンは、Google Contacts API へのアクセス権を付与しません。ただし、同様のオペレーションに対して、そのアクセス トークンを Google Calendar API に複数回送信することはできます。
5. 必要に応じてアクセス トークンを更新します。
アクセス トークンには有効期間があります。アプリケーションが単一のアクセス トークンの有効期間を超えて Google API にアクセスする必要がある場合は、更新トークンを取得できます。更新トークンを使用すると、アプリケーションは新しいアクセス トークンを取得できます。
シナリオ
ウェブサーバー アプリケーション
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、ユニバーサル Windows プラットフォーム（UWP）、またはデスクトップ アプリを選択します。
このプロセスにより、クライアント ID と（場合によっては）クライアント シークレットが生成されます。これらはアプリケーションのソースコードに埋め込みます。（このコンテキストでは、クライアント シークレットは明らかにシークレットとして扱われません）。
認証シーケンスは、アプリケーションがブラウザを Google URL にリダイレクトしたときに開始されます。この URL には、リクエストされているアクセスの種類を示すクエリ パラメータが含まれています。ユーザー認証、セッションの選択、ユーザーの同意は Google が処理します。認証コードが返され、アプリケーションはそれをアクセス トークンおよび更新トークンと交換できます。
アプリケーションは、更新トークンを今後使用するために保存し、アクセス トークンを使用して 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 の同等スコープ）のサブセットのみである場合は除きます。
現在、Google アカウント 1 つあたり、OAuth 2.0 クライアント ID 1 つあたり、100 個の更新トークンという制限があります。この上限値に達すると、新しい更新トークンが作成された際に自動的に一番古い更新トークンが警告なく無効化されます。この上限はサービス アカウントには適用されません。
また、ユーザー アカウントまたはサービス アカウントがすべてのクライアントで持つことができる更新トークンの合計数には、より大きな上限があります。通常、ほとんどのユーザーはこの上限を超えることはありませんが、実装のテストに使用されるデベロッパー アカウントは上限を超える可能性があります。
複数のプログラム、マシン、デバイスを承認する必要がある場合は、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_grant で失敗します。error_subtype フィールドを使用して、取り消されたトークンとセッション制御ポリシーによる失敗（"error_subtype": "invalid_rapt" など）を区別できます。セッション期間は非常に短く（1 時間から 24 時間）、このシナリオは認証セッションを再開することで適切に処理する必要があります。
同様に、サーバー間デプロイにユーザー認証情報を使用したり、使用を推奨したりしてはなりません。長時間実行されるジョブやオペレーションのためにユーザー認証情報がサーバーにデプロイされ、お客様がそのようなユーザーにセッション制御ポリシーを適用すると、セッション期間が終了したときにユーザーを再認証する方法がないため、サーバー アプリケーションは失敗します。
お客様がこの機能を導入できるようサポートする方法について詳しくは、こちらの管理者向けのヘルプ記事をご覧ください。
クライアント ライブラリ
次のクライアント ライブラリは一般的なフレームワークと統合されているため、OAuth 2.0 の実装が簡単になります。ライブラリには今後さらに多くの機能が追加される予定です。