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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Google API では、認証および承認に OAuth 2.0 プロトコルが使用されます。Google では、一般的な OAuth 2.0 シナリオ(ウェブサーバー、クライアントサイド、インストール、限定入力のデバイス アプリケーションなど)をサポートしています。

まず、 Google API Console から OAuth 2.0 クライアント認証情報を取得します。次に、クライアント アプリケーションが Google Authorization サーバーからアクセス トークンをリクエストし、レスポンスからトークンを抽出して、アクセスする 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 とアプリケーションの両方で認識されている OAuth 2.0 認証情報(クライアント ID やクライアント シークレットなど)を取得します。値のセットは、構築するアプリケーションの種類によって異なります。たとえば、JavaScript アプリケーションではシークレットは必要ありませんが、ウェブサーバー アプリケーションでは必要です。

2. Google の認可サーバーからアクセス トークンを取得します。

アプリケーションが Google API を使用して限定公開データにアクセスするには、その API へのアクセスを許可するアクセス トークンを取得する必要があります。単一のアクセス トークンにより、複数の 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 パラメータは完全に安全ではないログファイルに保存される可能性があるため、おすすめしません。また、REST では不要な 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 にアクセスする必要があります。アクセス トークンが期限切れになると、アプリケーションは更新トークンを使用して新しいアクセス トークンを取得します。

アプリケーションは、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 にアクセスする必要があります。アクセス トークンが期限切れになると、アプリケーションは更新トークンを使用して新しいアクセス トークンを取得します。

アプリケーションは、Google 承認サーバーにトークン リクエストを送信し、認証コードを受信して、コードをトークンと交換し、そのトークンを使用して Google API エンドポイントを呼び出します。

詳しくは、インストール済みアプリケーションに OAuth 2.0 を使用するをご覧ください。

クライアントサイド(JavaScript)アプリケーション

Google OAuth 2.0 エンドポイントは、ブラウザで実行される JavaScript アプリケーションをサポートします。

認可シーケンスは、アプリケーションがブラウザを Google URL にリダイレクトすると始まります。この URL には、リクエストされたアクセスのタイプを示すクエリ パラメータが含まれています。Google がユーザー認証、セッション選択、ユーザーの同意を処理します。

結果として、アクセス トークンをクライアントが Google API リクエストに含める前に検証する必要があります。トークンの有効期限が切れた場合、アプリケーションはこのプロセスを繰り返します。

JS アプリケーションが、Google Authorization Server にトークン リクエストを送信し、トークンを受信して、トークンを検証し、そのトークンを使用して 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 に対して自身の身元を証明する必要がありますが、ユーザーの同意は不要です。同様に、企業のシナリオでも、アプリケーションは一部のリソースへの委任アクセスをリクエストできます。

このようなサーバー間のやり取りには、サービス アカウントが必要です。サービス アカウントとは、個々のエンドユーザーではなくアプリケーションに属しているアカウントです。アプリケーションはサービス アカウントに代わって 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 は、これらの上限内でトークンサイズを変更する権利を有しており、アプリケーションはそれに応じて変数トークンサイズをサポートする必要があります。

更新トークンの有効期限

指定された更新トークンが機能しなくなる可能性がある場合に備えて、コードを記述する必要があります。更新トークンは、次のいずれかの理由により機能しなくなる場合があります。

  • ユーザーがアプリのアクセス権を取り消しました
  • 更新トークンが 6 か月間使用されていない。
  • ユーザーがパスワードを変更し、更新トークンに Gmail のスコープが含まれている。
  • ユーザー アカウントに付与されている更新トークンの最大数を超えました。
  • ユーザーが、セッション制御ポリシーが有効になっている Google Cloud Platform 組織に属しています。

外部ユーザータイプ用に OAuth 同意画面が構成され、公開ステータスが「テスト中」である Google Cloud Platform プロジェクトは、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_token で失敗します。サブエラーの種類を使用すると、取り消しトークンとセッション管理ポリシーによる失敗を区別できます。セッション継続時間は非常に限られているため(1 時間から 24 時間の間)、このシナリオでは、認証セッションを再起動して適切に処理する必要があります。

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

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

クライアント ライブラリ

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