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 Playground を試してください。

このページでは、Google がサポートする OAuth 2.0 認証シナリオの概要を説明し、詳細へのリンクを紹介します。認証に OAuth 2.0 を使用する方法については、OpenID Connect をご覧ください。

基本手順

すべてのアプリケーションは、OAuth 2.0 を使用して Google API にアクセスする際、基本的なパターンに従います。大きく分けて、次の 5 つのステップを行います。

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 では、複数のスコープの文字列値を 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 にアクセスする必要があります。アクセス トークンの有効期限が切れると、アプリケーションは更新トークンを使用して新しいトークンを取得します。

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

詳細については、ウェブサーバー アプリケーションに OAuth 2.0 を使用するをご覧ください。

インストール型アプリケーション

Google OAuth 2.0 エンドポイントは、パソコン、モバイル デバイス、タブレットなどのデバイスにインストールされたアプリケーションをサポートします。 Google API Console を使用してクライアント ID を作成する場合、インストール済みのアプリであることを指定し、アプリケーションの種類として [Android]、[Chrome アプリ]、[iOS]、[Universal Windows Platform(UWP)、デスクトップ アプリ] のいずれかを選択します。

このプロセスにより、クライアント 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 認可サーバーにトークン リクエストを送信し、トークンを受信して検証します。その後、トークンを使用して 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 プロジェクトには、7 日後に期限切れになる更新トークンが発行されます。ただし、リクエストされた OAuth スコープが、名前、メールアドレス、ユーザー プロファイル( userinfo.email, userinfo.profile, openid スコープ、または OpenID Connect の同等のもの)のサブセットである場合を除きます。

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

すべてのクライアントでユーザー アカウントまたはサービス アカウントが保持できる更新トークンの総数には、より大きな上限があります。通常のユーザーの多くはこの上限を超えることはありませんが、実装のテストに使用するデベロッパー アカウントでは超過する場合があります。

複数のプログラム、マシン、デバイスを承認する必要がある場合は、回避策の 1 つとして、承認するクライアント数を Google アカウントごとに 15 または 20 に制限します。 Google Workspace 管理者は、管理者権限を持つ追加のユーザーを作成し、そのユーザーを使用して一部のクライアントを承認できます。

Google Cloud Platform(GCP)組織のセッション管理ポリシーの操作

GCP 組織の管理者は、GCP リソースにアクセスする際に、Google Cloud のセッション管理機能を使用してユーザーの再認証を頻繁に行う必要がある場合があります。このポリシーは、Google Cloud コンソール、Google Cloud SDK(gcloud CLI)、Cloud Platform スコープを必要とするサードパーティの OAuth アプリケーションへのアクセスに影響します。ユーザーがセッション管理ポリシーを設定している場合、セッション継続時間が終了すると、API 呼び出しはエラーになります(更新トークンが取り消された場合と同じようなエラーになります)。呼び出しはエラータイプ invalid_grant で失敗します。error_subtype フィールドを使用すると、取り消されたトークンとセッション制御ポリシーに起因する失敗を区別できます(例: セッション継続時間は、認証の間隔は 2 時間~ 1 時間です)。"error_subtype": "invalid_rapt"

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

お客様によるこの機能のデプロイを支援する方法について詳しくは、管理者を対象としたヘルプ記事をご覧ください。

クライアント ライブラリ

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