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 パラメータの値が送信されます。
このリクエストを行う方法は複数あり、構築するアプリケーションの種類によって異なります。たとえば、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 Authorization リクエスト ヘッダーでトークンを 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 にアクセスする必要があります。アクセス トークンの有効期限が切れると、アプリケーションは更新トークンを使用して新しいトークンを取得します。
詳しくは、ウェブサーバー アプリケーションに OAuth 2.0 を使用するをご覧ください。
インストールしたアプリケーション
Google OAuth 2.0 エンドポイントは、パソコン、モバイル デバイス、タブレットなどのデバイスにインストールされているアプリケーションをサポートします。 Google API Console でクライアント ID を作成する場合は、これがインストール済みアプリケーションであることを指定してから、アプリケーションの種類として [Android]、[Chrome アプリ]、[iOS]、[ユニバーサル Windows プラットフォーム（UWP）]、[デスクトップ アプリ] のいずれかを選択します。
このプロセスにより、クライアント ID が作成され、場合によってはクライアント シークレットも作成されます。これらの 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 同等物を介して）のみである場合を除きます）。
現在のところ、Google アカウントあたり、OAuth 2.0 クライアント ID あたりの更新トークンの上限は 100 個です。この上限値に達すると、新しい更新トークンが作成された際に自動的に一番古い更新トークンが警告なく無効化されます。この上限はサービス アカウントには適用されません。
また、ユーザー アカウントまたはサービス アカウントがすべてのクライアントで保持できる更新トークンの合計数にも上限があります。ほとんどの一般ユーザーはこの上限を超えることはありませんが、実装のテストに使用されるデベロッパーのアカウントでは上限を超える可能性があります。
複数のプログラム、マシン、デバイスを承認する必要がある場合は、回避策の 1 つとして、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 の実装が簡単になります。今後、ライブラリにさらに多くの機能が追加される予定です。