OAuth 2.0 を使用した Google API へのアクセス

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 クライアントを作成する必要があります。次に例を示します。

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 カレンダー API に対して同様のアクセス トークンを複数回送信して、同様のオペレーションを実行することは可能です。

5. 必要に応じて、アクセス トークンを更新します。

アクセス トークンには有効期間があります。アプリケーションで 1 つのアクセス トークンの有効期間を超えて Google API にアクセスする必要がある場合は、更新トークンを取得できます。更新トークンを使用すると、アプリケーションで新しいアクセス トークンを取得できます。

シナリオ

ウェブサーバーアプリケーション

Google OAuth 2.0 エンドポイントは、PHP、Java、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（場合によっては、クライアント シークレット）がアプリケーションのソースコードに埋め込まれます。（このコンテキストでは、クライアント シークレットは明らかに Secret として扱われません）。

認可シーケンスは、アプリケーションがブラウザを 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 プロジェクトでは、名前、メールアドレス、ユーザー プロファイルのサブセット（ userinfo.email, userinfo.profile, openid スコープまたは同等の OpenID Connect）のみが要求される場合を除いて、7 日後に期限切れとなる更新トークンが発行されます。

現在、OAuth 2.0 クライアント ID ごとに、Google アカウントごとに 100 個の更新トークンに制限されています。上限に達した場合は、新しい更新トークンを作成すると、最も古い更新トークンが自動的に無効化され、警告が表示されません。この上限はサービス アカウントには適用されません。

また、すべてのクライアントでユーザー アカウントまたはサービス アカウントに設定できる更新トークンの合計数にも上限があります。通常のユーザーは通常、この上限を超えませんが、実装のテストに使用するデベロッパー アカウントを使用する場合もあります。

複数のプログラム、マシン、デバイスを承認する必要がある場合、1 つの回避策として、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 など）を区別するために、セッション時間は、セッションが 1 時間、その間に 1 時間かかります。"error_subtype": "invalid_rapt"

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

お客様によるこの機能のデプロイ支援について詳しくは、こちらの管理者に焦点を当てたヘルプ記事をご覧ください。

クライアント ライブラリ

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