Google Data Protocol の認証と認可

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

サードパーティ製アプリケーションは、特定のタイプのアクティビティでユーザーの Google アカウントへの限定的なアクセスを必要とすることがよくあります。ユーザーデータの不正使用を防ぐため、すべてのアクセス リクエストはアカウント所有者の承認が必要です。アクセス制御には、認証と認可の 2 つのコンポーネントがあります。

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

認証サービスを使用すると、ユーザーは Google アプリケーションに保存されているデータへのアクセス権をアプリケーションに付与できます。Google はプライバシーを重視しており、ユーザーのデータへのアクセスを必要とするアプリケーションは、ユーザーの承認を得る必要があります。

認証サービスと認可サービスは、まとめて「認証」と呼ばれることがよくあります。

Google APIs の認証と認可により、サードパーティ製アプリケーションは特定のタイプのアクティビティについて、ユーザーの Google アカウントへの限定的なアクセス権を取得できます。このドキュメントでは、利用可能な認証メカニズムを紹介し、各メカニズムがアプリケーションに提供する機能について説明します。

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

非推奨のサービス AuthSub、ClientLogin、OAuth 1.0 は、一部の Google API で OAuth 2.0 の代替として使用できます。2012 年にお知らせしたとおり、これらの非推奨サービスは 2015 年 4 月 20 日に終了します。これらの認証情報を使用するアプリケーションがすでにある場合は、OAuth 2.0 に移行する必要があります。

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

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

Google アカウント API の使用に関するディスカッションについては、Google Accounts API グループもご覧ください。

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

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

Google は、ユーザーの Google データへの承認済みアクセスを取得するための OAuth の 2 つのバージョン（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 APIs クライアント ライブラリには、ウェブ アプリケーションで OAuth を使用するのに役立つメソッドが用意されています。具体的には、リクエスト トークンの作成、リクエスト トークンの承認、承認済みリクエスト トークンとアクセス トークンの交換を行うメソッドがあります。また、ライブラリは、Google データ サービスにリクエストを行う際に必要な署名アルゴリズムも処理します。Google Data API クライアント ライブラリで OAuth を使用する方法の詳しい例については、Google Data APIs クライアント ライブラリで OAuth を使用するをご覧ください。

OAuth 認証プロセス

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

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

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

アプリケーションがユーザーデータへのアクセスを最初にリクエストすると、Google は未承認のリクエスト トークンをアプリケーションに発行します。

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

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

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

OAuth の準備

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

ウェブ アプリケーションを登録するかどうかを決定する

ユーザーにデータのセキュリティをさらに保証するために、ウェブ アプリケーションを Google に登録し、登録したセキュリティ証明書でリクエストに署名することもできます。一部の Google Data API フィードは、登録済みアプリケーションでのみ利用できます。対象の Google Data API のドキュメントを参照して、その API が登録済みアプリケーションでのみ動作するかどうかを確認してください。

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

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

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

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

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

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

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

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

アプリケーションは、各トークンが有効な Google サービスを追跡するなど、トークンの保存を安全に管理する必要があります。複数の Google サービスへのアクセスが必要な場合は、複数のアクセス トークンを取得できますが、ユーザーとアプリケーションごとに同時に有効にできるアクセス トークンは 10 個までです。

アプリケーションが複数のユーザー アカウントをサポートしている場合は、各トークンがどのユーザー アカウントに関連付けられているかを追跡する必要があります。各 OAuth トークンは、アクセスを承認したユーザーに固有のものです。アプリケーションは、トークンを正しいユーザーに関連付けることができる必要があります。この問題を管理する方法の 1 つは、トークン リクエストを行う前にユーザーに 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/Retrievetoken?Lang=de」の場合、リダイレクトは「http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE」になります。トークンと言語パラメータを解析することで、ユーザーがサイトの正しいバージョンにリダイレクトされるようになります。

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

ユーザーにアプリケーションを識別させる

通常、Google はユーザーにアクセス権限の同意を求める際に、アプリケーションの名前を表示します（例を参照）。

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

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

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

Google Apps ドメインの操作

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

OAuth の詳細

アプリケーションの登録方法や必要な OAuth パラメータの作成方法など、Google の OAuth 実装の詳細については、次の追加リソースをご覧ください。

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

トップへ戻る

インストール型アプリケーションでの OAuth の使用

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

OAuth 認証プロセス

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

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

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

アプリケーションがユーザーデータへのアクセスを最初にリクエストすると、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 パラメータを使用して、アプリケーションの名前を指定します。このパラメータが指定されていない場合、Google は oauth_callback パラメータで指定された URL のドメイン名を表示します。コールバック URL が指定されていない場合、Google は「anonymous」という文字列を表示します。

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

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

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

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

AutoDetect モード

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

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

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

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

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

デバイスのモード

アプリケーションで完全なウェブブラウザを起動できない場合は、リッチ クライアント デバイスでウェブブラウザなしで認証することもできます。

このモードでは、デベロッパーはユーザーがアクセス リクエストを承認できるウェブサイトを設定できます。承認後、ユーザーには Google が生成したコードが提供され、デベロッパーのサイトにリダイレクトされます。このサイトでは、認証プロセスを完了するためにデバイスにコードを入力する方法をお客様に説明する必要があります。

開発モード

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

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

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

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

OAuth の詳細

アプリケーションの登録方法や必要な OAuth パラメータの作成方法など、Google の OAuth 実装の詳細については、次の追加リソースをご覧ください。

• Google Data APIs クライアント ライブラリでの OAuth の使用
• 記事: Google Data API での OAuth の使用。OAuth を試すためのインタラクティブなツールである OAuth Playground の説明も含まれています。
• インストール型アプリケーションの 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 値（ステップ 3 で決定）を指定するなど、整形式の AuthSubRequest 呼び出しを生成する必要があります。セキュア トークンを使用している場合やセッション トークンを管理している場合は、リクエストにこれらの変数の値も含まれている必要があります。

   次の 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 から受け取ったリダイレクト（1 回限りのトークンを含む）を解析し、それを使用してアクションを実行する機能が備わっている必要があります。認証トークンはユーザー固有であるため、アプリはトークンをユーザーに関連付ける必要があります。トークン リクエストを行う前にユーザーに Cookie を発行することをおすすめします。その後、Google がユーザーをサイトにリダイレクトし、トークンが追加されると、アプリケーションは Cookie を読み取り、トークンを正しいユーザー ID に関連付けることができます。

5. 関連する場合は、セッション トークンをリクエストして保存または取り消すメカニズムを設定します。

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

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

   適切なリクエスト形式については、Google サービスのドキュメントをご覧ください。Google サービスに対するすべてのリクエストには、有効な認証トークンを含める必要があります。一般に、Google サービスへのリクエストは HTTP GET（新しいデータを書き込む場合は 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 APIs クライアント ライブラリで AuthSub を使用する
• 鍵と証明書を生成する（安全な AuthSub）
• AuthSub を使用したリクエストの署名（安全な AuthSub）
• ウェブベースのアプリケーションの登録

トップへ戻る

認可に ClientLogin を使用する

ClientLogin は、ほとんどの Google API で OAuth の代替として使用できる Google 独自の認可 API です。可能な限り、ClientLogin の使用は避けるべきです。ClientLogin を使用するアプリケーションがすでにある場合は、OAuth またはハイブリッド プロトコルに移行する必要があります。

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

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

注: Google Data APIs クライアント ライブラリには、インストールされたアプリケーションで ClientLogin を使用するのに役立つメソッドが用意されています。具体的には、認証トークンの取得、CAPTCHA チャレンジの処理、後で使用するための認証トークンの呼び出し、すべてのリクエストで正しい Authorization ヘッダーの送信を行うメソッドがあります。ライブラリのいずれかを使用している場合は、Google Data APIs クライアント ライブラリでの ClientLogin の使用をご覧ください。

ClientLogin 認証プロセス

ClientLogin を使用した認証では、インストールされたアプリケーション、Google サービス、ユーザーの 3 つのエンティティ間で一連のやり取りが行われます。次の図は、このシーケンスを示しています。

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

ClientLogin の使用

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

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

1. ユーザーからログインデータを取得する UI 要素を作成します。

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

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

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

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

   ログイン リクエストに対するレスポンスは次の 4 つです。

   • 成功（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 プロキシ

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

注: OAuth プロキシは、gadgets.* API を使用し、OpenSocial コンテナで実行されるガジェットでのみサポートされます。以前のガジェット 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 とカレンダーのデータにアクセスできます。この例のように、ガジェットは単一のスコープまたは複数のスコープのデータをリクエストできます。

oauth_callback

認証 URL の省略可能なパラメータ。ユーザーがデータへのアクセスを承認すると、OAuth 承認ページはこの URL にリダイレクトされます。ユーザーがガジェットをインストールする際に最適なユーザー エクスペリエンスを提供するには、このパラメータを http://oauth.gmodules.com/gadgets/oauthcallback に設定する必要があります。そのページには、ポップアップ ウィンドウを自動的に閉じる JavaScript のスニペットが用意されています。このパラメータを独自に「承認済み」のページに設定することも、単に空白のままにすることもできます。

認証された Google Data API フィードにアクセスする

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

ガジェットの詳細

OAuth プロキシの詳細、スタートガイド、gadgets.* 仕様など、Google Data API ガジェットの作成に関する完全な情報については、次の追加リソースをご覧ください。

• JavaScript クライアント ライブラリの使用
• Google Data APIs ガジェットの作成（記事）
• OAuth ガジェットの作成（ガジェットの完全なドキュメント）
• ガジェット API のドキュメント

トップへ戻る