Google データ プロトコルにおける認証と認可

警告: このページは、Google の古い API である Google Data API を対象としています。Google Data API ディレクトリに記載されている API のみを対象としており、その多くは新しい API に置き換えられています。特定の新しい API については、その新しい API のドキュメントをご覧ください。新しい API を使用してリクエストを承認する方法については、Google アカウントの認証と承認をご覧ください。

サードパーティ アプリケーションでは通常、特定の種類のアクティビティにおいて、ユーザーの Google アカウントへのアクセスが制限される場合があります。ユーザーデータが悪用されないようにするには、アクセスのリクエストはすべてアカウント所有者の承認が必要です。アクセス制御には、認証と認可の 2 つのコンポーネントがあります。

認証サービスでは、ユーザーが Google アカウントを使用してアプリケーションにログインできます。

認可サービスでは、Google アプリケーションに保存されているデータにアプリケーションからアクセスできるようにします。Google はプライバシーを重視しており、ユーザーのデータへのアクセスを必要とするアプリケーションは、ユーザーによって承認される必要があります。

認証サービスと認可サービスは、まとめて認証と呼ばれます。

Google API の認証と認可を使用すると、サードパーティ アプリは特定のタイプのアクティビティについてユーザーの Google アカウントへのアクセスを制限できます。このドキュメントでは、利用可能な認証メカニズムを紹介し、それぞれがアプリケーションに提供するものについて説明します。

• Google ログインは、ユーザーが Google 認証情報を使用してサイトにログインできるようにする簡単な方法です。さまざまなデバイス間で簡単に統合できるツールのセットが含まれています。
• OAuth 2.0 は、すべての Google API の認可プロトコルです。OAuth 2.0 は、アプリケーションに直接暗号署名の実行を義務付けるのではなく、SSL を使用してセキュリティを確保します。このプロトコルを使用することで、アプリケーションはユーザーの Google アカウントに関連付けられたデータへのアクセスをリクエストできます。
• OAuth 2.0 を使用したログイン（OpenID Connect）では、ユーザーに Google アカウントでログインしてもらうことで認証を行います。これは OpenID に代わるもので、OpenID のユーザーは OAuth 2.0 を使用したログインへの移行を計画する必要があります。

アプリケーションがガジェット（iGoogle や他の OpenSocial コンテナで使用）の場合は、ガジェットの認証のセクションをご覧ください。

注: このドキュメントでは、各認証方法の概要を説明します。各メソッドの詳細については、Google Account Authentication API のドキュメントをご覧ください。

Google Accounts API の使用方法については、Google Accounts API グループもご覧ください。

OAuth - ウェブ アプリケーションやインストール済みアプリケーションの認可

多くの Google サービスでは、アクセスがユーザーによって承認されている限り、ユーザーが作成したデータ（カレンダーやドキュメントのデータなど）にサードパーティによるアクセスが許可されます。この機能により、ユーザーはさまざまな目的で Google アプリケーションとサードパーティ アプリケーション間でデータを共有したり交換したりできます。

Google では、ユーザーの Google データへの承認済みアクセスを取得するために 2 つのバージョンの OAuth をサポートしています。OAuth 1.0 と OAuth 2.0 はどちらも、ウェブ アプリケーションとインストール済みアプリケーションの両方へのアクセスを提供します。

ウェブ アプリケーションおよびインストール済みアプリケーション用の OAuth 2.0

ウェブ アプリケーションまたはインストール済みのアプリケーションは、新しい簡素化された OAuth 2.0 プロトコルを使用して、Google アカウントに関連付けられたデータへのアクセスを承認できます。Google で OAuth 2.0 を実装する方法の詳細と例については、OAuth 2.0 のドキュメントをご覧ください。

ウェブ アプリケーション用の OAuth 1.0

Google アカウントまたは Google Apps アカウントに関連付けられたデータへの承認済みアクセスが必要なウェブ アプリケーションでは、Google による OAuth API 実装が可能です。ウェブベースのアプリケーション用の OAuth の実装（例を含む）について詳しくは、ウェブアプリ向け OAuth ガイドまたは本ドキュメントの概要をご覧ください。

インストール済みアプリケーション用の OAuth 1.0

ユーザーのパソコンやモバイル デバイスにインストールされているアプリケーションは、OAuth を使用して、Google アカウントに関連付けられたデータへのアクセスを承認できます。インストール済みアプリケーション向け OAuth の実装について詳しくは、インストール済みアプリケーション向け OAuth のガイドまたは本ドキュメントの概要をご覧ください。

ウェブ アプリケーションで OAuth を使用する

すべての Google Data API は、ウェブ アプリケーションでのデータの使用を承認するためのオープン標準である OAuth をサポートしています。OAuth リクエストを行うすべてのウェブ アプリケーションでは、セキュリティ証明書をアップロードして Google に登録する必要があります。詳しくは、ウェブベースのアプリケーションの登録をご覧ください。

Google Data API クライアント ライブラリには、ウェブ アプリケーションで OAuth を使用するためのメソッドが用意されています。具体的には、リクエスト トークンの構築、リクエスト トークンの認可、承認済みのリクエスト トークンとアクセス トークンの交換を行うメソッドが用意されています。また、Google Data サービスに対してリクエストを行う際に、必要な署名アルゴリズムを処理します。Google Data API クライアント ライブラリで OAuth を使用する方法の広範な例については、Google Data API クライアント ライブラリで OAuth を使用するをご覧ください。

OAuth 承認プロセス

OAuth 承認プロセスには、ウェブ アプリケーション、Google の承認サーバー、エンドユーザーの間で一連のやり取りが行われます。

基本的なプロセスは次のとおりです。

1. アプリケーションがアクセスをリクエストし、Google の承認サーバーから未承認のリクエスト トークンを取得します。
2. 必要なデータへのアクセス権をユーザーに付与するように、Google はユーザーに求めます。
3. アプリケーションが認可サーバーから認可されたリクエスト トークンを取得する。
4. 承認済みのリクエスト トークンをアクセス トークンと交換します。
5. アクセス トークンを使用して、Google のサービス アクセス サーバーからデータをリクエストします。

アプリケーションがユーザーのデータへのアクセス権を最初にリクエストすると、Google からそのアプリケーションに対して不正なリクエスト トークンが発行されます。

ユーザーがまだログインしていない場合は、ログインするように求められます。その後、承認ページが表示され、ユーザーはアプリケーションがアクセスをリクエストしている Google サービスデータを確認できます。

ユーザーがアプリケーションのアクセス リクエストを承認すると、Google は承認済みのリクエスト トークンを発行します。各リクエスト トークンの有効期間は 1 時間です。アクセス トークンと交換できるのは、承認されたリクエスト トークンのみです。また、この交換は承認されたリクエスト トークンごとに 1 回だけ行うことができます。

デフォルトでは、アクセス トークンは長期間有効です。各アクセス トークンは、最初の認可リクエストで指定されたユーザー アカウントに固有であり、そのリクエストで指定されたサービスにのみアクセス権を付与します。アクセス トークンはユーザーのデータに対するすべてのアクセスに必須であるため、安全に保管する必要があります。

OAuth の準備

OAuth で Google 認可サービスを使用するようにアプリケーションを設定する前に、次のタスクを完了する必要があります。

ウェブ アプリケーションを登録するかどうかの判断

ユーザーのデータのセキュリティをさらに強化するには、ウェブ アプリケーションを Google に登録し、登録されたセキュリティ証明書を使用してリクエストに署名します。一部の Google Data API フィードは、登録済みアプリケーションでのみ使用できます。お使いの Google Data API が登録済みアプリケーションでのみ機能しているかどうかを確認するには、該当するドキュメントのドキュメントをご覧ください。

アプリケーションは、各 OAuth リクエストに署名する必要があります。RSA-SHA1 署名を使用してリクエストに署名する場合は、登録プロセスの一環としてセキュリティ証明書をアップロードする必要があります。

また、HMAC-SHA1 署名を使用してリクエストに署名することもできます。HMAC-SHA1 署名に証明書は必要ありません。代わりに、OAuth の consumer secret 値が生成され、登録後、ドメインの登録ページに表示されます。

登録プロセスの詳細については、ウェブ アプリケーションの登録をご覧ください。

アプリケーションがアクセスするデータの範囲を決定する

各 Google サービスでは、Google Data API により許可されるアクセス権が制限されています。このアクセス権は、スコープ値として表されます。一部のサービスでは、スコープ値を指定することで、どのアプリがどのデータにアクセスするかをユーザーが選択できるようになっています。アクセス対象の Google サービスで使用可能なスコープ値については、そのサービスのドキュメントをご覧ください。

一般的には、必要なデータを含む最も狭いスコープのトークンをリクエストする必要があります。たとえば、アプリケーションでユーザーの「すべてのカレンダー」フィードにアクセスする必要がある場合は、スコープ http://www.google.com/calendar/feeds/default/allcalendars/full のトークンをリクエストする必要があります。

OAuth トークンを管理するメカニズムの設定

ユーザーデータの OAuth アクセス トークンを取得する場合、そのトークンを使用して、ユーザーの代わりに指定された Google サービスとのすべてのやり取りを行う必要があります。

アプリケーションは、各トークンが有効である Google サービスの追跡を含め、トークン ストレージを安全に管理する必要があります。 複数の Google サービスにアクセスする必要がある場合は、複数のアクセス トークンを取得できますが、ユーザーとアプリケーションごとに発行できるアクセス トークンは常に 10 個までです。

アプリケーションで複数のユーザー アカウントがサポートされている場合は、各トークンが関連付けられているアカウントを追跡する必要があります。各 OAuth トークンは、アクセスを承認したユーザーに固有のものです。アプリケーションは、トークンを正しいユーザーに関連付けることができる必要があります。その方法の一つは、トークンのリクエストを行う前に、ユーザーに Cookie を発行することです。リクエストされたデータへのアクセス権をユーザーが付与すると、Google は承認済みリクエスト トークンを送信し、ユーザーをアプリケーションにリダイレクトします。その後、アプリケーションの Cookie を使用してトークンを正しいユーザーに関連付けます。

Google サービスへのアクセスをリクエストするメカニズムを設定する

Google サービスに対する各リクエストに署名し、有効な OAuth アクセス トークンを含める必要があります。一般に、各リクエストは HTTP GET リクエストの形式で行われ、アクセス トークンと署名がヘッダーに含まれます。新しいデータを書き込むリクエストでは、HTTP POST を使用する必要があります。

各 Google Data API の正しいリクエスト形式の詳細については、その API のドキュメントをご覧ください。

OpenID の実装（省略可）

ユーザー認証に OpenID を実装する場合は、ハイブリッド プロトコルを使用して 2 つのプロセスを組み合わせることを検討してください。OpenID+OAuth を使用すると、リクエスト トークンを取得して承認するタスクが、OAuth 拡張機能付きの OpenID リクエストの一部として処理されます。OAuthGetRequestToken と同様に、これらの拡張機能は、アクセスされる Google サービスを識別するために使用されます。OpenID リクエストへの成功のレスポンスには、承認済みのリクエスト トークンが含まれます。このトークンを受信したら、OAuthGetAccessToken を使用してアクセス トークンと交換します。

OAuth トークンの使用

OAuth を使用するには、次の順序で、正しい形式の署名付きトークン リクエスト呼び出しを生成し、そのレスポンスを処理する必要があります。

1. 未承認のリクエスト トークン（OAuthGetRequestToken）を取得する
2. リクエスト トークンを承認する（OAuthAuthorizeToken）
3. 承認済みのリクエスト トークンをアクセス トークン（OAuthGetAccessToken）と交換します。

アプリケーションが登録されているかどうかにかかわらず、すべての OAuth リクエストは署名する必要があります。詳しくは、OAuth リクエストに署名するをご覧ください。

OAuth Playground で、認証トークンのリクエストと受信をテストできます。

詳細については、OAuth API リファレンスをご覧ください。

コールバック URL の設定

OAuthGetRequestToken リクエストで oauth_callback の値を指定すると、ユーザーがアクセス リクエストを認可した後の Google によるユーザーのリダイレクト先を確認できます。コールバック URL にはクエリ パラメータを含めることができます。リダイレクトには、アプリケーションで解析できる必要がある同じクエリ パラメータと承認済みリクエスト トークンが含まれます。

たとえば、複数の言語をサポートする場合に、ユーザーが閲覧しているアプリのバージョンを識別するクエリ パラメータを含めることができます。値が oauth_callback "http://www.yoursite.com/Fetchtoken?Lang=de" の場合、リダイレクトは「http://www.yoursite.com/Fetchtoken?Lang=de&oauth_token=DQAADKEDE」になります。 トークンと言語パラメータを解析することで、ユーザーは正しいバージョンのサイトにリダイレクトされます。

oauth_callback パラメータが含まれていない場合は、アクセス リクエストを承認した後、確認番号（例）を表示するウェブページにユーザーを誘導します。承認済みのリクエスト トークンを取得するには、ユーザーがアプリに手動で戻って確認番号を入力する必要があります。

ユーザーに対するアプリケーションの識別

Google では通常、ユーザーの同意を求める際にアプリの名前が表示されます（例をご覧ください）。

アプリケーションが登録されていない場合は、OAuthGetRequestToken リクエストで xoauth_displayname パラメータを使用してアプリケーションの名前を指定します。このパラメータが指定されていない場合は、oauth_callback パラメータで指定した URL のドメイン名が表示されます。コールバック URL が指定されていない場合、Google は文字列「anonymous」を表示します。

アプリが登録されている場合は、このパラメータを設定しないでください。デフォルトでは、登録時に指定した表示名が Google に表示されます。OAuthGetRequestToken リクエストで表示名を設定すると、登録済みの表示名の代わりにこの名前が使用され、アプリケーションの ID を確認できないというメッセージが含まれます。

注: OAuth Playground で xoauth_displayname パラメータを設定するには、リクエスト トークンを取得する前に [Advanced] チェックボックスをオンにします。

Google Apps ドメインを使用する

アプリケーションがホストされている Google アカウント ドメインのユーザー向けに設計されている場合は、トークンを承認する際に hd パラメータの使用を検討してください。hd パラメータの詳細については、複数のアカウントを使用しているユーザーの処理をご覧ください。

OAuth の詳細

アプリケーションの登録方法や必要な OAuth パラメータの作成方法など、Google による OAuth の実装について詳しくは、以下の参考情報をご覧ください。

• Google Data API クライアント ライブラリでの OAuth の使用
• 記事: Google Data API で OAuth を使用する。OAuth Playground の詳細と、OAuth を試すためのインタラクティブ ツールについて説明します。
• ウェブ アプリケーション用の OAuth（ドキュメント全体）
• ウェブベースのアプリケーションの登録
• 鍵と証明書の生成
• OAuth 仕様

トップへ戻る

インストール済みアプリケーションで OAuth を使用する

すべての Google Data API は、アプリケーションでのデータの使用を承認するためのオープン標準である OAuth をサポートしています。OAuth を使用するインストール済みのアプリケーションを Google に登録する必要はありません。

OAuth 承認プロセス

OAuth 認証プロセスでは、アプリケーション、Google の承認サーバー、エンドユーザーの間で一連の操作が行われます。

基本的なプロセスは次のとおりです。

1. アプリケーションがアクセスをリクエストし、Google の承認サーバーから未承認のリクエスト トークンを取得します。
2. 必要なデータへのアクセス権をユーザーに付与するように、Google はユーザーに求めます。
3. アプリケーションが認可サーバーから認可されたリクエスト トークンを取得する。
4. 承認済みのリクエスト トークンをアクセス トークンと交換します。
5. アクセス トークンを使用して、Google のサービス アクセス サーバーからデータをリクエストします。

アプリケーションがユーザーのデータへのアクセス権を最初にリクエストすると、Google からそのアプリケーションに対して不正なリクエスト トークンが発行されます。

ユーザーがまだログインしていない場合は、ログインするように求められます。その後、承認ページが表示され、ユーザーはアプリケーションがアクセスをリクエストしている Google サービスデータを確認できます。

ユーザーがアプリケーションのアクセス リクエストを承認すると、Google は承認済みのリクエスト トークンを発行します。各リクエスト トークンの有効期間は 1 時間です。アクセス トークンと交換できるのは、承認されたリクエスト トークンのみです。また、この交換は承認されたリクエスト トークンごとに 1 回だけ行うことができます。

OAuth は、登録解除モードを使用するインストール済みアプリケーションをサポートします。承認済みリクエスト トークンを取得する方法は複数あるため、たとえインストール先のデバイスにウェブブラウザがなくても、アプリは OAuth を使用してアプリケーションを承認できます。

デフォルトでは、アクセス トークンは長期間有効です。各アクセス トークンは、最初の認可リクエストで指定されたユーザー アカウントに固有であり、そのリクエストで指定されたサービスにのみアクセス権を付与します。アクセス トークンはユーザーのデータに対するすべてのアクセスに必須であるため、安全に保管する必要があります。

OAuth の準備

OAuth で Google 認可サービスを使用するようにアプリケーションを設定する前に、次のタスクを完了する必要があります。

アプリケーションがアクセスするデータの範囲を決定する

各 Google サービスでは、Google Data API により許可されるアクセス権が制限されています。このアクセス権は、スコープ値として表されます。一部のサービスでは、スコープ値を指定することで、どのアプリがどのデータにアクセスするかをユーザーが選択できるようになっています。アクセス対象の Google サービスで使用可能なスコープ値については、そのサービスのドキュメントをご覧ください。

一般的には、必要なデータを含む最も狭いスコープのトークンをリクエストする必要があります。たとえば、アプリケーションでユーザーの「すべてのカレンダー」フィードにアクセスする必要がある場合は、スコープ http://www.google.com/calendar/feeds/default/allcalendars/full のトークンをリクエストする必要があります。

OAuth トークンを管理するメカニズムの設定

ユーザーデータの OAuth アクセス トークンを取得する場合、そのトークンを使用して、ユーザーの代わりに指定された Google サービスとのすべてのやり取りを行う必要があります。

アプリケーションは、各トークンが有効である Google サービスの追跡を含め、トークン ストレージを安全に管理する必要があります。

アプリケーションで複数のユーザー アカウントがサポートされている場合は、各トークンが関連付けられているアカウントを追跡する必要があります。

Google サービスへのアクセスをリクエストするメカニズムを設定する

Google サービスに対する各リクエストに署名し、有効な OAuth アクセス トークンを含める必要があります。一般に、各リクエストは HTTP GET リクエストの形式で行われ、アクセス トークンと署名がヘッダーに含まれます。新しいデータを書き込むリクエストでは、HTTP POST を使用する必要があります。

各 Google Data API の正しいリクエスト形式の詳細については、その API のドキュメントをご覧ください。

OAuth トークンの使用

OAuth を使用するには、次の順序で、正しい形式の署名付きトークン リクエスト呼び出しを生成し、そのレスポンスを処理する必要があります。

1. 未承認のリクエスト トークン（OAuthGetRequestToken）を取得する
2. リクエスト トークンを承認する（OAuthAuthorizeToken）
3. 承認済みのリクエスト トークンをアクセス トークン（OAuthGetAccessToken）と交換します。

アプリケーションが登録されているかどうかにかかわらず、すべての OAuth リクエストは署名する必要があります。詳しくは、OAuth リクエストに署名するをご覧ください。 インストール済みのアプリケーションは、未登録のアプリの指示に従ってください。

OAuth Playground で、認証トークンのリクエストと受信をテストできます。

詳細については、OAuth API リファレンスをご覧ください。

ユーザーに対するアプリケーションの識別

Google では通常、ユーザーの同意を求める際にアプリの名前が表示されます（例をご覧ください）。

OAuthGetRequestToken リクエストで xoauth_displayname パラメータを使用して、アプリケーションの名前を指定します。このパラメータが指定されていない場合は、oauth_callback パラメータで指定した URL のドメイン名が表示されます。コールバック URL が指定されていない場合、Google は文字列「anonymous」を表示します。

注: OAuth Playground で xoauth_displayname パラメータを設定するには、リクエスト トークンを取得する前に [Advanced] チェックボックスをオンにします。

ウェブブラウザを起動する

OAuth 承認プロセスの一環として、アプリケーションは OAuthAuthorizeToken リクエストを行う必要があります。ユーザーは Google ウェブページにログインして、アプリケーションのアクセス リクエストを承認する必要があります。

• ほとんどのアプリで自動検出モードを使用する必要があります
• デバイスモードは、完全なウェブブラウザを起動できないアプリケーションに使用します。
• 開発モードは、開発の初期段階でのみ使用します。

自動検出モード

可能であれば、アプリケーションでブラウザ ウィンドウを開き、OAuthAuthorizeToken リクエストを行って Google ページを開く必要があります。Google が承認済みトークンを返すと、アプリケーションはこのトークンを検出してウェブブラウザからフォーカスを回復する必要があります。

このモードでは、ユーザーがアクセス リクエストを承認した後にリダイレクトされるコールバック URL を指定する必要があります。この URL は、OAuthGetRequestToken リクエストの oauth_callback パラメータとして、および OAuthGetAccessToken リクエストの verifier パラメータとして指定する必要があります。

ユーザー エクスペリエンスを向上させるため、アプリケーションは、この URL にリダイレクトされたタイミングを自動的に検出して、すぐにフォアグラウンドに戻り、OAuthGetAccessToken リクエストを行って OAuth プロセスを完了する必要があります。

詳細とベスト プラクティスについては、承認を自動検出するをご覧ください。

ユーザーがコールバック URL にリダイレクトされた時点、またはフォアグラウンドに移動できなかったことをアプリが自動的に検出できない場合、コールバック URL には、アプリをフォアグラウンドに移行する方法と、アプリ内から OAuthGetAccessToken リクエストを開始する方法を説明するページが表示されるはずです。

デバイスのモード

アプリケーションで完全なウェブブラウザを起動できない場合は、リッチ クライアント デバイスがウェブブラウザを使用せずに承認できる場合もあります。

このモードを使用すると、デベロッパーはユーザーがアクセスのリクエストを承認できるウェブサイトを設定できます。承認後、ユーザーは Google によって生成されたコードを受け取り、デベロッパーのサイトにリダイレクトされます。このサイトでは、認証コードをデバイスに入力して認証プロセスを完結する方法をユーザーに説明する必要があります。

開発モード

このモードは、アプリケーションの早期開発時にのみ使用することをおすすめします。

自動検出モードの場合と同様に、アプリケーションでブラウザを起動し、ユーザーがリクエストを承認する必要があります。ただし、コールバック URL のウェブページを作成する代わりに、oauth_callback パラメータの値を "oob"（帯域外）に設定できます。

その場合、ユーザーがリクエストを承認すると、Google はユーザーを Google アカウントのページに誘導し、確認番号を表示します（例を参照）。

OAuthGetAccessToken リクエストを行う前に、ユーザーはアプリケーションに戻って確認番号を入力する必要があります。

OAuth の詳細

アプリケーションの登録方法や必要な OAuth パラメータの作成方法など、Google による OAuth の実装について詳しくは、以下の参考情報をご覧ください。

• Google Data API クライアント ライブラリでの OAuth の使用
• 記事: Google Data API で OAuth を使用する。OAuth Playground の詳細と、OAuth を試すためのインタラクティブ ツールについて説明します。
• インストール済みアプリケーションの OAuth（ドキュメント全体）
• 鍵と証明書の生成
• OAuth 仕様

トップへ戻る

認証に AuthSub を使用する

AuthSub は Google 独自の承認 API であり、ほとんどの Google API で OAuth の代わりに使用できます。可能であれば、AuthSub は使用しないでください。AuthSub を使用するアプリケーションがすでにある場合は、OAuth プロトコルまたはハイブリッド プロトコルに移行する必要があります。

AuthSub 承認プロセス

AuthSub を使った認証では、ウェブ アプリケーション、Google サービス、ユーザーの 3 つのエンティティ間で一連の操作が行われます。次の図は、シーケンスを示しています。

1. ウェブ アプリケーションがユーザーの Google サービスにアクセスする必要があるときは、Google の Authorization Proxy サービスに対して AuthSub の呼び出しを行います。
2. 承認サービスは、[アクセス リクエスト] ページを提供して応答します。この Google が管理するページでは、Google サービスへのアクセスを許可または拒否するよう求められます。ユーザーは最初にアカウントにログインするよう求められる場合があります。
3. ユーザーは、ウェブ アプリケーションへのアクセスを許可するか拒否するかを決定します。ユーザーがアクセスを拒否した場合、ウェブ アプリケーションに戻るのではなく、Google ページにリダイレクトされます。
4. ユーザーがアクセス権を付与すると、承認サービスはユーザーをウェブ アプリケーションにリダイレクトします。リダイレクトには、1 回の使用に適した認証トークンが含まれます。有効期間の長いトークンと交換できます。
5. ウェブ アプリケーションは、ユーザーのエージェントとして機能する認証トークンを使用して、リクエストを使用して Google サービスに接続します。
6. Google サービスがトークンを認識すると、リクエストされたデータが提供されます。

AuthSub を操作する

ウェブ アプリケーションに AuthSub を組み込むには、次の作業が必要です。

1. ウェブ アプリケーションを登録するかどうかを指定します。

   登録済みのウェブ アプリケーションには、Google が認識できるというメリットがあります。Google ログインページでユーザーに表示される標準の注意事項は、変更または省略されます。また、登録済みのウェブ アプリケーションは、単に呼び出し元の URL ではなく、わかりやすい名前で識別されます。一部の Google サービスでは、未登録のウェブ アプリケーションへのアクセスが制限されています。登録する場合は、こちらの自動登録プロセスを使用します。

   登録する場合は、セキュリティ証明書と鍵を指定することもできます。証明書が登録されているウェブ アプリケーションは、Google サービスからデータをリクエストするときに使用できる安全なトークンを取得できます。（必要に応じて、保護されていないトークンを使用することもできます）。

2. 使用するトークンの種類とその管理方法を決定します。

   Google から受け取った認証トークンは、そのユーザーが特定の Google サービスと今後行うすべてのやり取りで使用されます。使用するトークンの種類（1 回限り使用またはセッション）は、ウェブ アプリケーションと Google サービスとのインタラクションのタイプによって異なります。たとえば、操作が 1 回限りのイベントでもまれなイベントでも、1 回限りのトークンで十分かもしれません。

   セッション トークンを取得し、定期的に使用して Google サービスにアクセスする場合は、ウェブ アプリケーションでトークン ストレージを管理する必要があります。これには、トークンが有効なユーザーと Google サービスの追跡も含まれます。Google アカウントは多数のトークンを管理するようには設定されていません。実際、有効なトークン（ユーザーごと、ウェブ アプリケーションごと）が一度に 10 個まで存在することは許可されません。この制限により、ウェブ アプリケーションは必要に応じてさまざまなサービスをカバーするために複数のトークンを取得できます。ウェブ アプリケーションが Google サービスにアクセスする必要があるたびに新しいトークンを取得することはできません。セッション トークンを保存する場合は、トークンをサーバーに保存されている他の機密情報と同様に安全に扱う必要があります。

   トークン取り消しメカニズムが設定されている場合は、定期的に新しいトークンを取得することもできます。別のトークンをリクエストする前に、アプリケーションで既存のトークンを取り消す必要があります。このシナリオでは、ユーザーは新しいトークンがリクエストされるたびにログインして、アクセス権を付与する必要があります。

3. アクセスする Google サービスに必要なスコープを決定します。

   それぞれの Google サービスによって、許可されるアクセスの量と種類が決まります。このアクセス権は、スコープ値として表されます。サービスのスコープは、サービス全体を識別する単純な URL でも、より限定的なアクセスでも指定できます。一部のサービスでは、限られた情報への読み取り専用アクセスを許可するなど、アクセスが大幅に制限されます。アクセス対象の Google サービスで許可されるスコープについては、そのサービスのドキュメントをご覧ください。最も範囲が限定されたトークンをリクエストする必要があります。たとえば、Gmail の Atom フィード機能にアクセスしようとしている場合は、スコープ「http://www.google.com/calendar/」ではなく「http://www.google.com/calendar/feeds/」を使用します。大規模なリクエストの場合、Google サービスははるかに制限が強くなります。

4. 認証トークンをリクエストして受信するメカニズムを設定します。

   このメカニズムは、適切な next および scope の URL 値を指定するなど、適切な形式の AuthSubRequest 呼び出しを生成する必要があります（手順 3 で決定）。セキュア トークンを使用する場合やセッション トークンを管理している場合は、これらの変数の値もリクエストに含める必要があります。

   次の URL にはクエリ パラメータを含めることができます。たとえば、複数の言語をサポートする場合は、ユーザーが閲覧しているウェブ アプリケーションのバージョンを識別するクエリ パラメータを含めます。next の値が http://www.yoursite.com/Retrievetoken?Lang=de の場合、リダイレクト http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE が発生します。トークンと Lang パラメータを解析し、ユーザーが正しいバージョンのサイトにリダイレクトされるようにします。

   特定の状況では、hd パラメータを使用すると、Google アカウントのサイトでアクセス権を付与するよう求められたときにユーザー エクスペリエンスを簡素化できます。ほとんどの場合、プロセスはアカウントにログインして、アクセス権を付与するかどうかを選択するだけです。ただし、複数の Google アカウント（通常の Gmail アカウントや 1 つ以上の Google Apps ホスト アカウント）をお持ちのユーザーは、アクセスしたいアカウントを特定するために、追加の「ユニバーサル ログイン」プロセスが必要になることがあります。アプリケーションが特定のマネージド ドメイン向けに設計されている場合は、このパラメータを使用してドメインを特定することで、追加の手順を省略できます。hd パラメータは、ホストされているアカウントで利用できないサービスにアプリケーションにアクセスする場合にも使用できます。値を「default」に設定すると、認可は通常のアカウントのみに制限されます。hd が設定されている場合、Google は自動的に承認用に適切なアカウントを選択します。

   トークンのメカニズムでは、単一使用トークンを含む Google から受け取ったリダイレクトを解析し、それを使用して処理できるようにする必要があります。認証トークンはユーザー固有のものであるため、アプリケーションでトークンをそのユーザーに関連付けることができる必要があります。トークン リクエストを行う前に、ユーザーに Cookie を発行することをおすすめします。その後、Google がトークンを付加してユーザーをサイトにリダイレクトすると、アプリケーションは Cookie を読み取り、トークンを正しいユーザー ID に関連付けることができます。

5. セッション トークンをリクエストし、必要に応じて保存または取り消すメカニズムを設定します。

   ステップ 2 で行ったトークン管理の決定によっては、セッション トークンを取得または取り消すメカニズム（AuthSubSessionToken と AuthSub お客様と TokenToken）を作成する必要がある場合があります。セッションと取り消しのメカニズムをテストするには、AuthSubTokenInfo を使用します。これは、特定のトークンが有効かどうかを示します。トークンを保存する場合、アプリケーションはユーザー ID と、トークンの対象となるサービス（スコープ）の両方を追跡する必要があります。

6. Google サービスへのアクセスをリクエストするメカニズムを設定します。

   適切なリクエスト形式については、Google サービスのドキュメントをご覧ください。Google サービスに対するすべてのリクエストには、有効な認証トークンを含める必要があります。一般に、Google サービスへのリクエストは、HTTP ヘッダー（新しいデータを書き込む場合は POST）の形式であり、トークンはリクエスト ヘッダーで参照されます。

   リクエスト ヘッダーの形式は次のとおりです。

   Authorization: AuthSub token="token"

   token は、AuthSub リクエストへのレスポンスとして Google から受け取った認証トークン（1 回限りまたはセッション）です。トークンがセキュアである場合は、デジタル署名が添付されている必要があります。手順と例については、リクエストに署名するをご覧ください。

   次の例は、Google カレンダー フィード サービスの呼び出しのリクエスト ヘッダーを示しています。このリクエストにはセキュアでないトークンが含まれています。

   GET /calendar/feeds/default/private/full HTTP/1.1
   Content-Type: application/x-www-form-urlencoded
   Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
   User-Agent: Java/1.5.0_06
   Host: www.google.com
   Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
   Connection: keep-alive

AuthSub の詳細

Google へのアプリケーションの登録や 1 回限りのトークンをセッション トークンに交換する方法など、AuthSub の詳細については、以下の参考情報をご覧ください。

• ウェブ アプリケーションの AuthSub 認証（ドキュメント全体）
• Google Data API クライアント ライブラリで AuthSub を使用する
• 鍵と証明書の生成（セキュア AuthSub）
• AuthSub によるリクエストへの署名（セキュア AuthSub）
• ウェブベースのアプリケーションの登録

トップへ戻る

認証に SafeFrame を使用する

SafeFrame は Google 独自の承認 API で、ほとんどの Google API で OAuth の代わりに使用できます。可能であれば、OpenSSL は使用しないでください。すでに OpenSSL を使用しているアプリケーションがある場合は、OAuth またはハイブリッド プロトコルに移行する必要があります。

インストール済みアプリケーションの認証: SafeFrame

ユーザーがアプリケーション内から Google アカウントにログインできます。その後、アプリケーションはログイン データを Google に連絡し、指定の Google Data API へのアクセスをリクエストします。ログイン情報が正常に認証されると、Google はトークンを返します。アプリケーションはデータの取得や送信など、ユーザーのアカウントへのアクセスをリクエストするたびにこのトークンを参照します。トークンは、使用している Google サービスで定義されている一定の期間有効です。

注: Google Data API クライアント ライブラリには、インストールしたアプリケーションで OpenSSL を使用するためのメソッドが用意されています。具体的には、認証トークンを取得する方法、キャプチャ チャレンジを処理する方法、後で使用するために認証トークンを取り消すメソッド、リクエストごとに正しい Authorization ヘッダーを送信する方法があります。いずれかのライブラリを使用している場合は、Google Data API クライアント ライブラリで SafeFrame を使用するをご覧ください。

SafeFrame の承認プロセス

SafeFrame による認可では、インストールしたアプリケーション、Google サービス、ユーザーの 3 つのエンティティ間での一連の操作が行われます。次の図は、シーケンスを示しています。

1. サードパーティ アプリケーションがユーザーの Google サービスにアクセスする必要がある場合、ユーザーのログイン名とパスワードを取得します。
2. その第三者アプリケーションによって、Google の Authorization サービスに対する OpenSSL 呼び出しが行われます。
3. Google の認証サービスでは、さらなる調査が必要であると判断された場合、CAPTCHA トークンとチャレンジを含む失敗レスポンスを CAPTCHA 画像の URL 形式で返します。
4. CAPTCHA チャレンジを受信すると、サードパーティ アプリケーションはユーザーにキャプチャ画像を表示し、ユーザーに回答を要求します。
5. ユーザーが求められた場合、CAPTCHA チャレンジに対して回答を送信します。
6. サードパーティ アプリケーションが、今回は新しい OpenSSL 呼び出しを行います。今回は、CAPTCHA 応答とトークン（失敗レスポンスで受信されます）が含まれます。
7. CAPTCHA チャレンジの有無にかかわらず、ログインが成功すると、Google 認証サービスはトークンをアプリケーションに返します。
8. アプリケーションは、Google 認証サービスから受け取ったトークンを参照するデータアクセスのリクエストで Google サービスに連絡します。
9. Google サービスがトークンを認識すると、リクエストされたデータアクセスが提供されます。

SafeFrame の使用

インストールしたアプリケーションでこのインターフェースを使用すると、ユーザーの Google アカウントにプログラムでアクセスできます。ユーザーからログイン情報を収集したら、SafeFrame を呼び出して、ユーザー アカウントへのアクセスをリクエストします。ログイン情報が正常に認証されると、Google はトークンを返します。アプリケーションはユーザーのアカウントへのアクセスをリクエストするたびに、このトークンを参照します。トークンは設定された期間有効です。その期間は、利用している Google サービスによって定義されます。

アプリケーションに OpenSSL を組み込むには、次のタスクが必要です。

1. ユーザーからのログインデータをキャプチャする UI 要素を作成します。

   UI は、ユーザー名（ドメインを含むメールアドレス）とパスワードを要求する必要があります。 また、必要に応じて、Google から受け取った URL を使用してキャプチャ画像を表示し、ユーザーに正しい答えを求められるようにする必要があります。UI には、ユーザーが新しいアカウントへの登録やその他のアカウント メンテナンスを行う必要がある場合のために、Google アカウントのログインページ（https://www.google.com/accounts/Login）へのリンクが含まれているのが理想的です。

2. 正しい形式の HTTPS POST ClientLogin リクエストを生成し、送信するためのコードを記述します。

   このコードには、CAPTCHA チャレンジを処理するロジックと、logintoken パラメータと logincaptcha パラメータの両方を含める必要があります。また、ユーザーが必須の情報を省略したときや、ログイン失敗後に誤ったデータを繰り返し検出し、不要なリクエストを送信せずにエラーを表示できるようにする必要があります。

3. Google からのレスポンスを処理します。

   ログイン リクエストには、4 つのレスポンスが考えられます。

   • success（HTTP 200）
   • 失敗（HTTP 403）: 説明エラーコードが表示される
   • 無効なリクエスト（通常は不正なリクエストが原因で発生します）
   • CAPTCHA 確認で不合格

   成功レスポンスには、「Auth」というラベルの付いた認証トークンが含まれます。このトークンは、このアカウントに対する Google サービスへのその後のすべてのリクエストに含める必要があります。認証トークンは慎重に保護する必要があります。また、ユーザーのアカウントへのアクセスを表すため、他のアプリケーションに付与しないでください。トークンの時間制限は、トークンを発行したサービスによって異なります。

   エラー レスポンスには、1 つ以上のエラーコードと、ユーザーに表示されるエラー メッセージを含む URL が含まれます。ClientLogin は、パスワードの誤りによるエラーと認識できないユーザー名によるエラー（ユーザーがアカウントにまだ登録していない場合など）を区別できません。アプリは、考えられるすべてのエラー メッセージを適切に処理する必要があります。

   CAPTCHA 確認時の失敗レスポンスは、なんらかの理由で追加のセキュリティ対策を適用することを Google が決定したことを意味します。このレスポンスには、CAPTCHA 画像の URL と特定の CAPTCHA チャレンジを表すトークンが付属します。

4. Google の CAPTCHA チャレンジに対応する。

   このチャレンジに対応するには、アプリケーションで CAPTCHA 画像を表示し、ユーザーに回答を求める必要があります。CAPTCHA 画像を表示するには、失敗時のレスポンスとともに返された CaptchaUrl の値を使用し、先頭に Google アカウントの URL「http://www.google.com/accounts/」を付加します。ユーザーが回答を提供したら、アプリケーションはログイン リクエストを再送信します。今回は、CAPTCHA トークン（logintoken）とユーザーの回答（logincaptcha）が含まれます。Google は、アカウントへのアクセスを承認する前にユーザーの回答を検証します。

   別の方法として、ユーザーの CAPTCHA レスポンスの取得と送信のプロセスを管理したくない場合もあります。CAPTCHA チャレンジに応じて、アプリケーションは Google がホストするページ（「https://www.google.com/accounts/DisplayUnlockCaptcha」）にユーザーを誘導できます。ユーザーがそのチャレンジに正常に回答すると、Google サーバーは使用中のコンピュータを信頼します。そのうえで、アプリケーションは元のログイン リクエストを再送信して認証トークンを取得します。

注: Google は、CAPTCHA チャレンジの発行前にログイン試行を検証しません。つまり、CAPTCHA 確認後、ログイン試行が失敗する可能性があります。

* CAPTCHA はカーネギー メロン大学の商標です。

トップへ戻る

ガジェットの認証

OAuth プロキシ

標準のガジェット API を使用してガジェットを構築している場合は、OAuth プロキシと呼ばれるガジェット プラットフォームの機能を使用して、Google Data API にアクセスできます。OAuth（前述）は、iGoogle、MySpace、Blogger などのガジェット ホスティング サービスでユーザーの個人データにアクセスしたり、データを別のウェブサイトやガジェットと共有したりできるようにする認証標準です。OAuth プロキシは、OAuth 認証の詳細の多くを非表示にすることで、ガジェットのデベロッパーが開発しやすくするように設計されています。プロキシは、ガジェット仕様の実装である Shindig というオープンソース プロジェクトに基づいています。

注: OAuth プロキシは、gadgets.* API を使用し OpenOpen コンテナで実行されるガジェットでのみサポートされます。以前のガジェット API ではサポートされていません。

認証フロー

ユーザーのデータにアクセスするには、ガジェットで OAuth トークンを取得する必要があります。OAuth プロキシが認証フローを管理します。ユーザーが最初にガジェットをインストールする際、次のプロセスが行われます。

1. ガジェットが初めて読み込まれ、いずれかの Google Data API を使用してユーザーのデータにアクセスを試みます。
2. ユーザーがアクセスを許可していないため、リクエストは失敗します。レスポンス オブジェクトには、OAuth 承認ページの URL（response.oauthApprovalUrl）が含まれます。ガジェットは、この URL で新しいウィンドウを起動するメソッドを提供する必要があります。
3. 承認ページで、ユーザーはガジェットへのアクセスを許可または拒否します。成功すると、指定した oauth_callback ページがユーザーに表示されます。最良のユーザー エクスペリエンスを実現するには、http://oauth.gmodules.com/gadgets/oauthcallback を使用します。
4. 次に、ユーザーはポップアップ ウィンドウを閉じます。ユーザーが承認したことをガジェットに通知するには、ポップアップ ハンドラを使用して、承認ウィンドウの終了を検出します。または、このウィンドウを閉じた後、ユーザーがクリックできるリンク（たとえば「アクセスを承認しました」など）をガジェットに表示することもできます。
5. ユーザーのデータを再度リクエストして、ガジェットが Google Data API へのアクセスを 2 回試みます。この試行は成功しました。
6. ガジェットは認証され、正常に動作します。

ガジェットのセットアップ

1 つ以上の Google Data API にアクセスするには、最初に認証方法として OAuth を使用するよう、ガジェットに指示する必要があります。ガジェットの XML で <ModulePrefs> セクションに <OAuth> 要素を追加します。

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

このセクションでは、次のクエリ パラメータのみを変更します。

scope

リクエスト URL の必須パラメータ。ガジェットで使用されているパラメータには、ガジェットからアクセスできます。scopeこの例では、ガジェットから Blogger とカレンダーのデータにアクセスできます。ガジェットは、この例のように 1 つまたは複数のスコープのデータをリクエストできます。

oauth_callback

承認 URL のオプション パラメータ。ユーザーがデータへのアクセスを承認すると、OAuth 承認ページがこの URL にリダイレクトされます。ユーザーがガジェットをインストールしたときに最適なユーザー エクスペリエンスを実現するには、このパラメータを http://oauth.gmodules.com/gadgets/oauthcallback に設定します。このページには、ポップアップ ウィンドウを自動的に閉じる JavaScript スニペットが表示されます。または、このパラメータをご自身の「承認済み」ページに設定することも、パラメータを空白のままにすることもできます。

認証済みの Google Data API フィードへのアクセス

ガジェットがユーザーを認証した後は、Google Data API の JavaScript クライアント ライブラリを使用して Google Data API に簡単にアクセスできますOAuth プロキシでライブラリを使用する方法については、JavaScript クライアント ライブラリを使用するをご覧ください。

ガジェットの詳細

OAuth Proxy の詳細、使用を開始する方法の記事、gadgets.* の仕様など、Google Data API ガジェットの作成方法について詳しくは、以下のリソースをご覧ください。

• JavaScript クライアント ライブラリを使用する
• Google Data API ガジェットの作成（記事）
• OAuth ガジェットを作成する（ガジェットの詳細）
• Gadgets API のドキュメント

トップへ戻る