警告: このページでは、Google の古い API である Google Data APIs について説明します。このページは、Google Data APIs ディレクトリに記載されている 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 APIs クライアント ライブラリを使用して、ユーザーに代わってウェブベースのアプリケーションから Google サービスにアクセスしたいプログラマーを対象としています。
このドキュメントは、AuthSub インターフェースと、AuthSub をウェブ アプリケーションに組み込む一般的なプロセスを理解していることを前提としています。AuthSub のプロトコルの詳細については、ウェブ アプリケーションの AuthSub 認証をご覧ください。
クライアント ライブラリを使用せずに AuthSub と Google Data API を使用する
ウェブ アプリケーション クライアントが認証システムとして AuthSub を使用して Google Data サービスとやり取りする場合は、ウェブ アプリケーションの AuthSub 認証をご覧ください。必要に応じて、Google Data APIs クライアント ライブラリを使用しなくてもかまいません。
AuthSub を使用してアプリケーションがユーザーを認証する手順の概要は次のとおりです。
アプリケーションは適切な AuthSub URL を構築し、ユーザーがログインできるようにその URL にユーザーを送信します。AuthSub システムは、指定したサイトの URL にユーザーを戻し、1 回限りのトークンを返します。アプリケーションは、必要に応じてそのトークンをセッション トークンと交換します。その後、アプリケーションは、サービスに送信する各リクエストの Authorization ヘッダーでトークンを送信します。
Google Data APIs クライアント ライブラリは、さまざまな詳細を処理することで、この認証プロセスを簡素化します。このドキュメントでは、その方法について説明します。
AuthSub と Google Data API の使用: クライアント ライブラリの例
このセクションでは、Google Data APIs クライアント ライブラリ メソッドを使用して、AuthSub ドキュメントの「AuthSub の使用」セクションで説明されている手順を行う例を示します。
この例では、AuthSub インターフェースを Google カレンダーとやり取りするウェブ アプリケーションに統合します(この例を理解するうえで Google カレンダーについて知っておく必要はありません)。この例では、ウェブ アプリケーションが example.com でホストされていることを前提としています。
使用するトークンのタイプ(session=0 または session=1)を決定する
使い捨てトークン(session=0)またはセッション トークン(session=1)を使用できます。
このドキュメントでは、複数の API リクエストを行うアプリケーションでより有用なセッション トークンを使用します。AuthSub のドキュメントで説明したように、ウェブ アプリケーションでセッション トークンを使用する場合は、トークンの保存を自分で管理する必要があります。このドキュメントでは、トークン管理については説明しません。また、session=0 でリクエストされたトークンは、後で有効期間の長いセッション トークンに交換(アップグレード)できないことにも注意してください。
ウェブ アプリケーションを登録するかどうかを決定する(secure=0 または secure=1)
AuthSub は、未登録、登録済み、セキュリティ強化済みで登録済みの 3 つのモードで使用できます。このドキュメントの残りの部分では、最後のオプションを安全な AuthSub と呼びます。未登録/登録モードは安全な AuthSub よりも簡単に設定できますが、セキュリティを強化するために安全なトークンを使用することをおすすめします。
登録方法
[Registration for Web-Based Applications] を選択すると、アプリケーションには次のようなメリットがあります。
- セキュリティ レベルの向上。
- 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 システムは、提供された「next」URL を使用して、ユーザーをアプリケーションにリダイレクトします。
1 回限りのトークンを抽出する
Google がアプリケーションにリダイレクトすると、トークンはクエリ パラメータとして「next」URL に追加されます。上記の例では、ユーザーがログインすると、Google は http://www.example.com/RetrieveToken?token=DQAADKEDE のような URL にリダイレクトします。アプリケーションは、URL クエリ パラメータからトークン値を抽出する必要があります。
アプリケーションがユーザーを AuthSub システムに送信する前にユーザーのブラウザに認証 Cookie を設定した場合、Google が「次へ」の URL にリダイレクトしたときに、アプリケーションは認証 Cookie を読み取って、その 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 anAuthSubTokenorSecureAuthSubTokenobject. # 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 anAuthSubTokenorSecureAuthSubTokenobject. # 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
注: gdata.auth.extract_auth_sub_token_from_url(url, rsa_key=rsa_key) を使用して 1 回限りのトークンを抽出している限り、セキュア AuthSub でも同じプロセスが適用されます。
注: 安全な AuthSub を使用する場合、秘密鍵自体はネットワーク経由で送信されません。クライアント ライブラリは、キー自体ではなく、キーでリクエストに署名して生成された一意の署名を送信します。
セッション トークンを使用する
AuthSub のドキュメントに記載されているように、セッション トークンを Authorization ヘッダーに配置することで、セッション トークンを使用してサーバーへのリクエストを認証できます。
セッション トークンを設定したら、トークンについて考慮することなく、標準の Google Data APIs クライアント ライブラリ呼び出しを使用してサービスを操作できます。詳細については、クライアント ライブラリのドキュメントと、操作するサービスと言語の Google Data APIs デベロッパー ガイドをご覧ください。
セッション トークンに関する情報を取得する
クライアントとサーバーがトークンのパラメータについて合意していることをテストする場合は、トークンを 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 Tips Blog の 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 クライアントのキーを生成する
.NET Framework は、PEM 形式で保存された鍵や証明書を認識しません。したがって、.pem ファイルを作成したら、次の追加の手順が必要です。
openssl pkcs12 -export -in test_cert.pem -inkey myrsacert.pem -out myrsacert.pfx -name "Testing Certificate"
この手順では、秘密鍵と証明書から PFX ファイルが生成されます。このファイルは、.NET クライアント ライブラリにインポートして、Google Data APIs へのリクエストにデジタル署名するために使用できます。
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