Google Data Protocol クライアント ライブラリの AuthSub

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

このドキュメントでは、Google Data API クライアント ライブラリを使用して Google のウェブ アプリケーション用の AuthSub 認証に接続する方法について説明します。

AuthSub インターフェースにより、ウェブベースのアプリケーションは、ユーザーに代わって Google サービスにアクセスできます。高レベルのセキュリティを維持するには、AuthSub インターフェースにより、アプリケーションでユーザーのアカウント情報を処理することなく認証トークンを取得できます。

Google Data API クライアント ライブラリには、ウェブ アプリケーションで AuthSub を使用するためのメソッドが用意されています。具体的には、リクエスト URL の作成、1 回限りの認証トークンの取得、セッション トークンの 1 回限りのトークンの交換、リクエストへの署名を行うメソッドが用意されています。

注: JavaScript クライアント ライブラリには、AuthSubJS と呼ばれる独自の AuthSub 種類があります。JavaScript アプリケーションで AuthSubJS を使用する方法については、JavaScript クライアント ライブラリで AuthSub 認証を使用するをご覧ください。

対象者

このドキュメントは、Google Data API クライアント ライブラリを使用して、ウェブベースのアプリケーションがユーザーに代わって Google サービスにアクセスする必要があるプログラマーを対象としています。

このドキュメントは、AuthSub インターフェースと、ウェブ アプリケーションに AuthSub を組み込むための一般的なプロセスについて理解していることを前提としています。AuthSub のプロトコルの詳細については、ウェブ アプリケーション用の AuthSub 認証をご覧ください。

クライアント ライブラリなしで AuthSub と Google Data API を使用する

認証アプリケーションとして AuthSub を使ってウェブ アプリケーション クライアントと Google データサービスを連携させる場合は、ウェブ アプリケーション用の AuthSub 認証をご覧ください。 使用しない場合は、Google Data API クライアント ライブラリを使用する必要はありません。

アプリケーションが AuthSub を使用してユーザーを認証する方法の概要は次のとおりです。

アプリケーションは、適切な SubSub URL を作成してユーザーを URL に誘導し、そこでユーザーがログインできるようにします。AuthSub システムはユーザーを指定されたサイトの URL に送り返し、1 回限りのトークンを返します。アプリケーションはそのトークンをセッション トークンと交換し、アプリケーションがサービスに送信するリクエストごとに、Authorization ヘッダーでトークンを送信します。

Google Data API クライアント ライブラリを使用すると、さまざまな詳細を自動的に処理して、承認プロセスを簡略化できます。このドキュメントでは、その方法について説明します。

AuthSub と Google Data API を使用する: クライアント ライブラリの例

このセクションは、Google Data API クライアント ライブラリ メソッドを使用して、AuthSub ドキュメントのAuthSub の操作セクションで説明されている手順を実行します。

この例では、Google カレンダーとやり取りする AuthSub インターフェースをウェブ アプリケーションに統合します（ただし、この例に従うために Google カレンダーについて知っている必要はありません）。この例では、ウェブ アプリケーションが example.com でホストされていることを前提としています。

使用するトークンの種類（session=0 または session=1）を指定する

1 回限りのトークン（session=0）とセッション トークン（session=1）のどちらを使用するかを選択できます。このドキュメントではセッション トークンを使用します。これらのトークンは、複数の API リクエストを行うアプリケーションで使用すると便利です。AuthSub のドキュメントで説明したように、ウェブ アプリケーションでセッション トークンを使用する場合は、トークン ストレージの管理を各自で行う必要があります。このドキュメントでは、トークンの管理については説明しません。また、session=0 でリクエストされたトークンを、長期間有効なセッション トークンに交換（アップグレード）することはできません。

ウェブ アプリケーションを登録するかどうかを指定します（secure=0 または secure=1）。

AuthSub は、未登録、登録済み、強化されたセキュリティで登録済みの 3 種類のモードで使用できます。このドキュメントの以降の部分では、最後のオプションをセキュア AuthSub と呼びます。 未登録/登録済みモードは、安全な AuthSub よりも設定が簡単ですが、強化されたセキュリティのためにセキュア トークンを使用することをおすすめします。

登録方法

[ウェブベースのアプリケーションの登録] を選択すると、アプリケーションに次のようなメリットがあります。

1. 高度なセキュリティ。
2. Google からの信頼（Google の承認ページには警告は表示されません）。

登録済み + セキュア AuthSub

セキュアな AuthSub を選択する場合は、ウェブ アプリケーションの登録に加えて、自己署名 RSA 秘密鍵と公開証明書のペアを作成する必要があります。X.509 証明書を作成する例については、後述の登録モードで使用する鍵と証明書を生成するをご覧ください。

データアクセスの範囲を決定する

各 Google サービスは、ユーザーのデータへのアクセスに関するトークンのアクセスを決定（さらには絞り込み）する scope 値を定義します。使用可能な scope の値の一覧については、よくある質問をご覧ください。

Google Calendar API とやり取りすることにしたため、scope は http://www.google.com/calendar/feeds/ になります。

注: より細かな制限が不要な場合は、必ずスコープ値を可能な限り広い URL に設定してください。 たとえば、scope=http://www.google.com/calendar/feeds/default/allcalendars/full のような狭いスコープは、トークンのアクセスを allcalendars/full フィードのみに制限します。scope=http://www.google.com/calendar/feeds/ を使用すると、カレンダーのすべてのフィード（http://www.google.com/calendar/feeds/*）にアクセスできるようになります。

マルチスコープ トークン

複数の Google Data API にアクセスするトークンを作成するには、各スコープを URL エンコードされたスペースで区切ります。次の例では、ユーザーの Google コンタクトと Google カレンダーの両方のデータにアクセスできるトークンを作成します。

scope=http://www.google.com/calendar/feeds/%20http://www.google.com/m8/feeds/

1 回限りの認証トークンをリクエストする

特定のユーザーとサービスの AuthSub トークンを取得するには、アプリケーションがユーザーを AuthSubRequest URL にリダイレクトする必要があります。これにより、ユーザーは Google アカウントにログインすることになります。AuthSubRequest URL の詳細については、ウェブ アプリケーションの AuthSub 認証をご覧ください。

アプリケーションで AuthSubRequest URL を作成するには、クライアント ライブラリごとに次のものを使用します。

Java

import com.google.gdata.client.*;

String nextUrl = "http://www.example.com/RetrieveToken.jsp";
String scope = "http://www.google.com/calendar/feeds/";
boolean secure = false;  // set secure=true to request secure AuthSub tokens
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(nextUrl, scope, secure, session);

G Suite ドメインのユーザーを認証する場合:

import com.google.gdata.client.*;

String hostedDomain = "example.com";
String nextUrl = "http://www.example.com/RetrieveToken.jsp";
String scope = "http://www.google.com/calendar/feeds/";
boolean secure = false;  // set secure=true to request AuthSub tokens
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(hostedDomain, nextUrl, scope, secure, session);

.NET

using Google.GData.Client;

String nextUrl = "http://www.example.com/RetrieveToken.aspx";
String scope = "http://www.google.com/calendar/feeds/";
bool secure = false; // set secure=true to request secure AuthSub tokens
bool session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(nextUrl, scope, secure, session);

G Suite ドメインのユーザーを認証する場合:

using Google.GData.Client;

String hostedDomain = "example.com";
String nextUrl = "http://www.example.com/RetrieveToken.aspx";
String scope = "http://www.google.com/calendar/feeds/";
bool secure = false; // set secure=true to request secure AuthSub tokens
bool session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(hostedDomain, nextUrl, scope, secure, session);

PHP

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');

$nextUrl = 'http://www.example.com/RetrieveToken.php';
$scope = 'http://www.google.com/calendar/feeds/';
$secure = 0;  // set $secure=1 to request secure AuthSub tokens
$session = 1;
$authSubUrl = Zend_Gdata_AuthSub::getAuthSubTokenUri($nextUrl, $scope, $secure, $session);

G Suite ドメインのユーザーを認証する場合:

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');

$hostedDomain = 'example.com';
$nextUrl = 'http://www.example.com/RetrieveToken.php';
$scope = 'http://www.google.com/calendar/feeds/';
$secure = 0;  // set $secure=1 to request secure AuthSub tokens
$session = 1;
$authSubUrl = Zend_Gdata_AuthSub::getAuthSubTokenUri($nextUrl, $scope, $secure, $session) . '&hd=' . $hostedDomain;

Python

import gdata.auth

next = 'http://www.example.com/RetrieveToken.pyc'
scope = 'http://www.google.com/calendar/feeds/'
secure = False  # set secure=True to request secure AuthSub tokens
session = True
auth_sub_url = gdata.auth.GenerateAuthSubRequestUrl(next, scope, secure=secure, session=session)

G Suite ドメインのユーザーを認証する場合:

import gdata.auth

hosted_domain = 'example.com'
next = 'http://www.example.com/RetrieveToken.pyc'
scope = 'http://www.google.com/calendar/feeds/'
secure = False  # set secure=True to request secure AuthSub tokens
session = True
auth_sub_url = gdata.auth.GenerateAuthSubRequestUrl(next, scope, secure=secure, session=session, domain=hosted_domain)

「次へ」URL を作成した後、さまざまな方法で URL を使用して AuthSubRequest ハンドラにユーザーを誘導できます。最も一般的な方法は、アプリケーションが Google アカウントにアクセスできるようリンクを承認する必要があることをユーザーに伝えるページを表示し、リンクにリクエスト URL を添付することです。たとえば、ウェブアプリに次の文字列を出力できます。

String authorizationUrl =
        "<p>MyApp needs access to your Google Calendar account to read your Calendar feed. " +
        "To authorize MyApp to access your account, <a href=\"" + authSubUrl + "\">log in to your account</a>.</p>";

ユーザーは Google の AuthSub ページへのリンクをたどってログインします。AuthSub システムは、指定された「次へ」URL を使用してユーザーをアプリケーションにリダイレクトします。

単一用途トークンの抽出

Google からアプリケーションにリダイレクトされると、トークンがクエリ パラメータとして「次の」URL に追加されます。上記の例の場合、ユーザーがログインすると、Google は http://www.example.com/RetrieveToken?token=DQAADKEDE のような URL にリダイレクトします。アプリケーションは、その URL クエリ パラメータからトークン値を抽出する必要があります。

アプリケーションで AuthSub システムに送信される前にユーザーのブラウザに認証 Cookie が設定されていた場合、Google は「次の」URL にリダイレクトして戻り、認証 URL を訪れたユーザーを認識できます。このような Cookie は、アプリケーションのユーザー ID と Google から取得した AuthSub トークンを関連付けるために利用できます。

クライアント ライブラリには、単一用途トークンを抽出する便利なメソッドが用意されています。

Java

String singleUseToken = AuthSubUtil.getTokenFromReply(httpServletRequest.getQueryString());

.NET

String singleUseToken = Request.QueryString["token"];
// or
String singleUseToken = AuthSubUtil.getTokenFromReply(new Uri(Request.QueryString));

PHP

$singleUseToken = $_GET['token'];

Python

current_url = 'http://' + req.hostname + req.unparsed_uri
# Unlike the other calls, extract_auth_sub_token_from_url() will create an AuthSubToken or SecureAuthSubToken object.
# Use str(single_use_token) to return the token's string value.
single_use_token = gdata.auth.extract_auth_sub_token_from_url(current_url)

セキュアな AuthSub を使用している場合は、SecureAuthSubToken が作成されるように、必ず RSA 秘密鍵を設定してください。

f = open('/path/to/yourRSAPrivateKey.pem')
rsa_key = f.read()
f.close()
current_url = 'http://' + req.hostname + req.unparsed_uri
# Unlike the other calls, extract_auth_sub_token_from_url() will create an AuthSubToken or SecureAuthSubToken object.
# Use str(single_use_token) to return the token's string value.
single_use_token = gdata.auth.extract_auth_sub_token_from_url(current_url, rsa_key=rsa_key)

セッション トークンをリクエストする

URL から取得したトークンは常に 1 回限りのトークンです。次のステップでは、AuthSubSessionToken URL を使用して、有効期間の長いセッション トークンのトークンをアップグレードします。詳細については、ウェブ アプリケーションの AuthSub 認証のドキュメントをご覧ください。セキュアな AuthSub を使用している場合は、交換を行う前に RSA 秘密鍵を設定する必要があります。各クライアント ライブラリを使用した例を以下に示します。

Java

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;

String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, null);

CalendarService calendarService = new CalendarService("google-ExampleApp-v1.0");
calendarService.setAuthSubToken(sessionToken, null);

// ready to interact with Calendar feeds

セキュアな AuthSub では、null をパスする代わりに、RSA 秘密鍵を exchangeForSessionToken に渡します。

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;

java.security.PrivateKey privateKey =
    AuthSubUtil.getPrivateKeyFromKeystore("AuthSubExample.jks", "privKeyPa$$word", "AuthSubExample", "privKeyPa$$word");
String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, privateKey);

CalendarService calendarService = new CalendarService("google-ExampleApp-v1.0");
calendarService.setAuthSubToken(sessionToken, privateKey);

// ready to interact with Calendar feeds

.NET

using Google.GData.Client;
using Google.GData.Calendar;

String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, null).ToString();

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "google-ExampleApp-v1.0");
authFactory.Token = (String) sessionToken;

CalendarService calendarService = new CalendarService(authFactory.ApplicationName);
calendarService.RequestFactory = authFactory;

// ready to interact with Calendar feeds

セキュアな AuthSub では、null をパスする代わりに、RSA 秘密鍵を exchangeForSessionToken に渡します。

using Google.GData.Client;
using Google.GData.Calendar;

protected AsymmetricAlgorithm getRsaKey()
{
  X509Certificate2 cert = new X509Certificate2("C:/MyAspSite/test_cert.pfx", "privKeyPa$$word");
  RSACryptoServiceProvider privateKey = cert.PrivateKey as RSACryptoServiceProvider;
  return privateKey;
}

AsymmetricAlgorithm rsaKey = getRsaKey();
String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, rsaKey).ToString();

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "google-ExampleApp-v1.0");
authFactory.Token = (String) sessionToken;
authFactory.PrivateKey = rsaKey;

CalendarService calendarService = new CalendarService(authFactory.ApplicationName);
calendarService.RequestFactory = authFactory;

// ready to interact with Calendar feeds

PHP

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');
Zend_Loader::loadClass('Zend_Gdata_Calendar');

$sessionToken = Zend_Gdata_AuthSub::getAuthSubSessionToken($singleUseToken);

// Create a Calendar service object and set the session token for subsequent requests
$calendarService = new Zend_Gdata_Calendar(null, 'google-ExampleApp-v1.0');
$calendarService->setAuthSubToken($sessionToken);

// ready to interact with Calendar feeds

セキュアな AuthSub では、交換のためにまず Zend_Gdata_HttpClient をセットアップし、setAuthSubPrivateKeyFile() を使用して RSA 秘密鍵を設定する必要があります。

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');
Zend_Loader::loadClass('Zend_Gdata_Calendar');

$client = new Zend_Gdata_HttpClient();
$client->setAuthSubPrivateKeyFile('/path/to/myrsakey.pem', null, true);
$sessionToken = Zend_Gdata_AuthSub::getAuthSubSessionToken($singleUseToken, $client);

$calendarService = new Zend_Gdata_Calendar($client, 'google-ExampleApp-v1.0');
$calendarService->setAuthSubToken($sessionToken);

// ready to interact with Calendar feeds

Python

import gdata.calendar
import gdata.calendar.service

calendar_service = gdata.calendar.service.CalendarService()
calendar_service.UpgradeToSessionToken(single_use_token)  # calls gdata.service.SetAuthSubToken() for you

# ready to interact with Calendar feeds

注: セキュアな SubSub のプロセスは gdata.auth.extract_auth_sub_token_from_url(url, rsa_key=rsa_key) を使用して 1 回限りのトークンを抽出する限り同じです。

注: 安全な AuthSub を使用する場合、秘密鍵自体はネットワーク経由で送信されません。クライアント ライブラリは、鍵自体ではなく、鍵を使用してリクエストに署名することで生成された一意の署名を送信します。

セッション トークンを使用する

セッション トークンを使用してサーバーに対するリクエストを認証するには、AuthSub のドキュメントで説明されているように、トークンを Authorization ヘッダーに配置します。

セッション トークンを設定すると、トークンを気にすることなく、標準の Google Data API クライアント ライブラリ呼び出しを使用してサービスを操作できます。詳細については、クライアント ライブラリのドキュメントと、対象のサービスと言語に関する Google Data API デベロッパー ガイドをご覧ください。

セッション トークンに関する情報を取得する

クライアントとサーバーがトークンのパラメータに同意するかどうかをテストするには、トークンを AuthSubTokenInfo ハンドラに渡します。これにより、トークンに関する情報を含む名前と値のペアのセットが返されます。

Java

Map<String, String> tokenInfo = AuthSubUtil.getTokenInfo(sessionToken, null);

セキュアな AuthSub を使用している場合は、RSA 秘密鍵を渡します。

Map<String, String> tokenInfo = AuthSubUtil.getTokenInfo(sessionToken, privateKey);

.NET

Dictionary<String, String> tokenInfo = AuthSubUtil.GetTokenInfo(sessionToken, null);

セキュアな AuthSub を使用している場合は、RSA 秘密鍵を渡します。

Dictionary<String, String> tokenInfo = AuthSubUtil.GetTokenInfo(sessionToken, privateKey);

PHP

$tokenInfo = Zend_Gdata_AuthSub::getAuthSubTokenInfo($sessionToken);

セキュアな AuthSub を使用している場合は、Zend_Gdata_HttpClient を渡し、リクエストが RSA 秘密鍵で署名されるようにします。

$tokenInfo = Zend_Gdata_AuthSub::getAuthSubTokenInfo($sessionToken, $client);

Python

token_info = calendar_service.AuthSubTokenInfo()

セッション トークンを取り消す

AuthSub セッション トークンに有効期限はありません。クライアントはセッション トークンを必要な期間だけ保存できます。

そのため、クライアントがセッション トークンを使用して完了すると、AuthSub のドキュメントに記載されているとおり、AuthSubRevokeToken ハンドラを使用してトークンを取り消すことができます。

たとえば、従来のセッション形式の方法でトークンを管理する場合、クライアントはユーザー セッションの開始時にトークンを取得し、ユーザー セッションの終了時にトークンを取り消すことができます。

トークンを取り消すには、各クライアント ライブラリで次のものを使用します。

Java

AuthSubUtil.revokeToken(sessionToken, null);

セキュアな AuthSub を使用している場合は、RSA 秘密鍵を渡します。

AuthSubUtil.revokeToken(sessionToken, privateKey);

.NET

AuthSubUtil.revokeToken(sessionToken, null);

セキュアな AuthSub を使用している場合は、RSA 秘密鍵を渡します。

AuthSubUtil.revokeToken(sessionToken, privateKey);

PHP

$wasRevoked = Zend_Gdata_AuthSub::AuthSubRevokeToken($sessionToken);

セキュアな AuthSub を使用している場合は、Zend_Gdata_HttpClient を渡し、リクエストが RSA 秘密鍵で署名されるようにします。

$wasRevoked = Zend_Gdata_AuthSub::AuthSubRevokeToken($sessionToken, $client);

Python

calendar_service.RevokeAuthSubToken()

その他のリソースとサンプル

• Google Data API ガイド ブログの AuthSub の例
• Python クライアント ライブラリの AuthSub サンプル
• Java クライアント ライブラリの AuthSub サンプル
• 記事: .NET クライアント ライブラリで AuthSub を使用する
• 記事: JavaScript クライアント ライブラリで AuthSub 認証を使用する

トップへ戻る

セキュアな AuthSub で使用する自己署名秘密鍵と公開鍵証明書を生成する

秘密鍵は署名の生成に使用されます。署名は各リクエストに含める必要があります。証明書に埋め込まれた公開鍵は、Google によって署名の検証に使用されます。公開鍵は、PEM 形式の X.509 証明書でエンコードされた 1,024 ビット RSA 鍵である必要があります。証明書は登録時に Google に送信する必要があります。

以降のセクションでは、OpenSSL ユーティリティと Java の keytool ユーティリティという 2 つのツールを使用して鍵と証明書を生成する例を示します。

以下の例は Google Data API に固有のものではありませんが、同じユーティリティを使用し、どのような目的でも鍵を生成できます。

会社名が「My_Company」で、米国カリフォルニア州マウンテンビューに、ドメイン名が「example.com」であることを前提としています。

OpenSSL を使用して鍵を生成する

RSA 鍵とそれに対応する証明書のペアを作成するには、次のコマンドを使用します。

# Generate the RSA keys and certificate
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -sha1 -subj \
  '/C=US/ST=CA/L=Mountain View/CN=www.example.com' -keyout \
  myrsakey.pem -out /tmp/myrsacert.pem

警告: -nodes パラメータを含めると、パスワードなしで秘密鍵が作成されます。ただし、セキュリティ強化のため、このパラメータを省略することを検討してください。

-sha1 パラメータでは、鍵を使用して SHA1 署名を生成するよう指定します。

-subj パラメータでは、証明書が表すアプリケーションの ID を指定します。

-keyout パラメータに、鍵を格納するファイルを指定します。このファイルには機密情報が含まれているため、保護し、誰とも共有しないでください。

-out パラメータで、証明書を含むファイルを PEM 形式で指定します（登録中に Google に送信できます）。

.NET クライアントの鍵を生成する

PEM 形式で保存されている鍵や証明書は、.NET フレームワークでは認識されません。そのため、.pem ファイルを作成したら、以下の追加手順が必要です。

openssl pkcs12 -export -in test_cert.pem -inkey myrsacert.pem -out myrsacert.pfx -name "Testing Certificate"

このステップでは、秘密鍵と証明書から PFX ファイルを生成します。このファイルは .NET クライアント ライブラリにインポートして、Google Data API に対するリクエストにデジタル署名できます。

Java クライアントの鍵を生成する

Java クライアントは PKCS#8 形式の秘密鍵を受け入れます。上記の手順で鍵/証明書を生成した後、生成された .pem ファイルから .pk8 ファイルを作成します。

openssl pkcs8 -in myrsakey.pem -topk8 -nocrypt -out myrsakey.pk8

または、Java キーストアと keytool ユーティリティを使用して、RSA 鍵とそれに対応する証明書のペアを作成することもできます。次のコマンドを使用します。

# Generate the RSA keys and certificate
keytool -genkey -v -alias Example -keystore ./Example.jks\
  -keyalg RSA -sigalg SHA1withRSA\
  -dname "CN=www.example.com, OU=Engineering, O=My_Company, L=Mountain  View, ST=CA, C=US"\
  -storepass changeme -keypass changeme

警告: 「changeme」は適切なパスワードではありません。これは例にすぎません。

-dname パラメータでは、証明書が表すアプリケーションの ID を指定します。-storepass パラメータで、キーストアを保護するパスワードを指定します。-keypass パラメータは、秘密鍵を保護するためのパスワードを指定します。

ManageDomains ツールで使用できるファイルに証明書を書き込むには、次のコマンドを使用します。

# Output the public certificate to a file
keytool -export -rfc -keystore ./Example.jks -storepass changeme \
  -alias Example -file mycert.pem

トップへ戻る