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 アプリケーションではシークレットは必要ありませんが、ウェブサーバー アプリケーションではシークレットは必要ありません。
アプリを実行するプラットフォームに適した OAuth クライアントを作成する必要があります。次に例を示します。
- サーバーサイドまたは JavaScript ウェブアプリの場合は、「ウェブ」クライアント タイプを使用します。ネイティブ アプリやモバイルアプリなど、他のアプリにこのクライアント タイプを使用しないでください。
- Android アプリの場合は、クライアント タイプとして「Android」を使用します。
- iOS アプリと macOS アプリの場合は、「iOS」クライアント タイプを使用します。
- ユニバーサル Windows プラットフォーム アプリの場合は、「Universal Windows Platform」クライアント タイプを使用します。
- テレビや埋め込みデバイスなど、制限付き入力デバイスの場合は、「テレビと制限付き入力デバイス」クライアント タイプを使用します。
- サーバー間インタラクションには、サービス アカウントを使用します。
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 パラメータは完全に安全ではないログファイルになってしまう可能性があるため、おすすめしません。また、不要な 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 にアクセスする必要があります。アクセス トークンが期限切れになると、アプリケーションは更新トークンを使用して新しいトークンを取得します。
詳しくは、ウェブサーバー アプリケーションに 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 にアクセスします。トークンが期限切れになると、アプリケーションはこのプロセスを繰り返します。
詳しくは、サービス アカウントのドキュメントをご覧ください。
トークンのサイズ
トークンのサイズには次のような上限があります。
- 認証コード: 256 バイト
- アクセス トークン: 2,048 バイト
- 更新トークン: 512 バイト
Google Cloud の Security Token Service API によって返されるアクセス トークンは、Google API OAuth 2.0 アクセス トークンに似ていますが、トークンサイズの上限が異なります。詳しくは、API ドキュメントをご覧ください。
Google は、これらの上限内でトークン サイズを変更する権利を留保します。アプリケーションはそれに応じて可変トークン サイズをサポートする必要があります。
更新トークンの有効期限
提供された更新トークンが機能しなくなる可能性を予測するコードを記述する必要があります。更新トークンは、次のいずれかの理由で機能しなくなる場合があります。
- ユーザーがアプリのアクセス権を取り消しました。
- 更新トークンが 6 か月間使用されていない。
- ユーザーがパスワードを変更し、更新トークンに Gmail のスコープが含まれている。
- ユーザー アカウントが、付与できる（ライブ）更新トークンの最大数を超えました。
- 管理者がアプリのスコープでリクエストされたサービスを制限付きに設定している場合（エラーは
admin_policy_enforced）。 - Google Cloud Platform API - 管理者が設定したセッション継続時間を超過している可能性があります。
外部ユーザータイプに OAuth 同意画面が構成され、公開ステータスが「テスト中」の Google Cloud Platform プロジェクトは、7 日で期限切れの更新トークンが発行されます。ただし、リクエストされた OAuth スコープが、名前、メールアドレス、ユーザー プロファイルのサブセット（または
userinfo.email, userinfo.profile, openid のスコープ内の OpenID Connect の同等のもの）のみである場合を除きます。
現在、OAuth 2.0 クライアント ID ごとに 1 つの Google アカウントにつき 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 時間進めてその間にセッションを持続できます（その間の猶予期間が 1 時間）。
同様に、サーバー間のデプロイにユーザー認証情報を使用したり、その使用を推奨したりしてはなりません。長時間実行されているジョブやオペレーションのためにサーバーにユーザー認証情報がデプロイされ、そのようなユーザーにセッション制御ポリシーを適用している場合、セッション継続時間の経過後にユーザーを再認証する方法がないため、サーバー アプリケーションは失敗します。
お客様がこの機能を導入できるようサポートする方法について詳しくは、こちらの管理者向けのヘルプ記事をご覧ください。
クライアント ライブラリ
以下のクライアント ライブラリは一般的なフレームワークと統合されており、OAuth 2.0 の実装が簡単になります。今後さらにライブラリに機能が追加される予定です。