はじめに
今回から数回に渡って、Windows Live ID SDKとWindows LiveユーザーデータAPIについて紹介します。Windows Live ユーザーデータAPIを利用すると、Windows Liveサービスに格納されているWindows Liveユーザーの情報へのアクセスがWebアプリケーションから可能になります。このAPIを利用するにはWidows Live ID SDKのWindows Live ID DelegatedAuthenticationも利用する必要があります。本連載では最初に認証の仕組みを紹介し、次回以降の記事にてユーザーデータをアクセスする方法を紹介します。
Windows Live ID DelegatedAuthentication
Windows Live ID Delegated Authentication(委任認証)は、Windows Liveサービスのアカウント(Windows Live ID)を所有しているユーザーの、Windows Liveサービスに対応したデータに、Webアプリケーションからアクセスするための仕組みです。
委任認証を利用するとWindows Live IDによる認証が必要なデータにアクセスできます。そのためにはWebアプリケーション側は、ユーザーにアクセス許可を承認してもらいます。このときユーザーは、Windows Live IDサービスのWebページ上にて認証および承認を行います。WebアプリケーションへWindows Live IDアカウント情報が送信されることはありません。
委任認証を利用したWebアプリケーションの利点として、Windows Liveサービス上のユーザーデータにアクセスでき、ユーザー個人に対応したアプリケーションが提供できることが考えられます。また、データベースやストレージを用意する必要がありません(提供されていない情報を格納するためには必要です) 。
Windows LiveサービスのユーザーデータとそのAPIは、今のところ次のものが用意されています。これらのAPI群をユーザーデータAPIと呼んでいます。いずれも正式バージョンではありませんが、今後アップデートや新たなAPIの追加が予想されます。
Windows Live Contacts API : Windows Live HotmailやMessengerに使用するコンタクト情報にアクセス
Windows Live Photo API : Windows Liveスペース上の写真にアクセス
Windows Live Application Based Storage API : Webアプリケーション用のデータストレージ
承認の流れ
ユーザーデータへアクセスするため、実際的な委任認証を使用したときの承認プロセスを図1 に示します。また、委任認証で使用する用語についても説明します。
図1 承認プロセス
ユーザーが委任認証を利用したWebサイトへアクセスします。Webアプリケーションを提供しているWebサイトのことをアプリケーションプロバイダ と呼びます。
WebサイトはWindows Liveの承認要求ページへリダイレクトします。Webサイトは、ユーザーデータにアクセスするためにユーザーに承認を要求します。具体的には承認要求ページへのURLを示し、ユーザーがクリックすることで移動します。移動先のユーザーデータに対する承認・拒否するページを承認要求ページ (図2 )と呼びます。また、この承認情報を管理するサービスをWindows Live ID承認サービス と呼びます。
図2 承認要求ページ
ユーザーは表示された承認要求ページにて、アプリケーションプロバイダから要求されたユーザーデータへのアクセス許可に対して承認または拒否を行います。
対象となるユーザーデータのカテゴリをオファー 、そのオファーに対して操作可能な機能(読み取りや書き込みなど)をアクション と呼びます。この組み合わせを「許可 」と呼びます。
承認要求ページからWebサイトへ承認情報とともにリダイレクトされます。ユーザーが承認または拒否を行うと(ボタンをクリックすると) 、Webサイトが戻り先URLとして指定していたページへ移動します。このときPOSTデータに承認結果の情報が含まれています。ユーザーが承諾した場合「承認トークン 」と呼ばれるユーザーデータのアクセスに必要な文字列が返ります。
承認トークンの内容を使用して、WebサイトはユーザーデータAPIを利用してユーザーデータにアクセスできます。このユーザーデータを提供しているWindows Liveサービスをリソースプロバイダ と呼びます。
ここまでがユーザーデータにアクセスするまでの一連の流れになります。一度、承認トークンを受け取るとアクセス許可が有効な限りWebサイトは直接リソースプロバイダとやり取りが可能です(アクセスのたびにユーザーの承認は必要ありません) 。また、ユーザーが再び承認要求ページへアクセスした場合、既に承認したオファーおよびアクションへの要求であり、その承認が有効な場合はすぐにWebサイトへリダイレクトされます。
アプリケーションIDの取得
委任認証を利用するためにWebアプリケーションを登録しアプリケーションIDを取得します。登録時にWebサイトのURLドメインを指定する必要があるため、そのドメインを所有している必要があります。オファーの内容によっては登録なしでもアクセスできるものがありますが、その場合でも独自のドメインが必要です。また、SDK文書には明示されていませんが、アプリケーションのIDの有無により取得できる値に違いがある場合があるようです。気付いた差異については今後 記事中に登場した時点でコメントします。
アプリケーションIDを取得するには、Windows Live ID Application Center へアクセスします。登録にはWindows Live IDによるサインインが必要です。「 Register an Application」をクリックし登録ページ(図3 )を表示します。
図3 アプリケーションID登録ページ
次の項目を入力します
Application Name
アプリケーション名。適当なものを入力します。登録後に変更はできません。
Return URL
戻り先URL。承認要求ページからリダイレクトされるWebサイトのアドレスです。
Domain Name
ドメイン名。アプリケーションの完全修飾のドメイン名を指定します(例: www.gihyo.jp) 。戻り先URLに使用しているドメインと同じである必要があります。ひとつのドメインに対してひとつのアプリケーションIDしか登録できません。
Secret Key
シークレットキー。アプリケーションプロバイダとWindows Liveサービスとの間で共有する暗号用の文字列を指定します。
Application verifier required
アプリケーション検証が必須かどうか。後ほど説明に出てきますが、アプリケーションが承認を要求するとき、承認要求ページへのURLにアプリケーション検証トークンを必ず含めるかどうかを示す数値です。1を選択すると必須になります。
画像の文字列を入力し、およびWindows Live IDの利用規約を確認し同意のチェックボックスをチェックします。
[Submit]ボタンをクリックします。問題がなければ登録が完了し、アプリケーションIDが表示されます。アプリケーションIDは16文字の文字列です。
承認の要求
まずは、承認サービスに承認を要求してみましょう。Webアプリケーションの動作としては、ユーザーに承認要求ページへのURLを示します。
承認要求のURLは「https://consent.live.com/Delegation.aspx」に次のパラメータを指定したものになります。
ru
承認要求ページからの戻り先URLを指定します。アプリケーションIDを取得している場合、この値を登録しているため省略できます。登録したURLとは異なるものをドメインが変わらない範囲で指定することもできます。
ps
アプリケーションプロバイダが必要とする許可(オファーとアクション)を表す文字列を指定します。今回は扱いませんが例えば次のようなものになります。
SpacesPhotos.ReadWrite,ContactsSync.FullSync,ApplicationStorage.ReadWrite
SpacesPhotosがオファー、ReadWriteがアクションになります。オファーとアクションはピリオド(.)でつなぎます。複数の許可を指定する場合は各許可をコンマ(,)で区切ります。
pl
プライバシーポリシーのURLを指定します。アプリケーションプロバイダのプライバシーポリシーを表示するためのものです。承認要求ページから参照されます。必須のパラメータです。
app
アプリケーション検証トークンと呼ばれる文字列を指定します。これはアプリケーションIDを取得している場合のみ有効です。アプリケーション登録時にアプリケーション検証を必須にしていた場合、必ず指定する必要があります。アプリケーション検証トークンは、承認サービスがアプリケーションプロバイダを識別するために使用されます。作成方法はこの後説明します。
mkt
Webサイトのカルチャ名を指定します。たとえば日本(言語が日本語で地域が日本)の場合は「ja-JP」となります。この値は省略可能です。
appctx
Webアプリケーションが必要に応じて指定するためのものです。承認のプロセスにおいてユーザーは一度Webサイトから承認要求ページに移動します。移動前にこのパラメータを使用し値を指定しておくことで、承認要求ページから戻ってきた際にその値が取得でき、何らかの処理の継続を可能にします。
以上が承認要求のパラメータです。
例えばパラメータを次のようにした場合、
ru :http://sample.gihyo.jp/Sample/Default.aspx
pl :http://sample.gihyo.jp/Sample/PrivacyPolicy.aspx
ps :ApplicationStorage.ReadWrite
mkt :ja-JP
承認要求ページへのリンクのHTMLは以下のようになります。
<a href="https://consent.live.com/Delegation.aspx?ru=http%3a%2f%2fsample.gihyo.jp%2fSample%2fDefault.aspx&ps=ApplicationStorage.ReadWrite&pl=http%3a%2f%2fsample.gihyo.jp%2fSample%2fPrivacyPolicy.aspx&mkt=ja-JP">Requesting Consent</a>
パラメータに指定した値はURLエンコードしてあります。また、例で指定した許可はアプリケーション登録なしで使用できるものです。このリンク先へ移動すれば承認要求ページが表示されます。
アプリケーション検証トークンの作成
承認要求のURLのパラメータに必要なアプリケーション検証トークンを作成します。アプリケーション検証トークンのパラメータ(app)には、次のパラメータを含めます。
appid
16文字の取得したアプリケーションID。
ts
1970年1月1日(UTC)から経過した秒数
sig
シークレットキーを使用したHMAC-SHA256ハッシュ関数によるappidとtsのハッシュ値をBase64でエンコードした文字列。
以上の値を「appid=…&ts=…&sig=…」のように連結してURLエンコードした文字列をappパラメータに指定します。
具体的なコードをVB.NET(ASP.NET)を使用して示します。まずは1970年からの経過秒を文字列として返すメソッドです。
Public Shared Function GetTimestamp () As String
Dim refTime As DateTime = New DateTime ( 1970 , 1 , 1 , 0 , 0 , 0 , DateTimeKind . Utc )
Return CUInt (( DateTime . UtcNow - refTime ). TotalSeconds ). ToString
End Function
次に委任認証で使用されるシークレットキーからハッシュ値を得るメソッドを示します。シークレットキーに接頭辞を付け、SHA256ハッシュ値をバイト配列として取得し、先頭の16バイトを返しています。System.Securityを参照し、Imports宣言しているものとします。
Public Shared Function Derive ( ByVal secretKey As String , ByVal prefix As String ) As Byte ()
Dim hashAlgorithm As New SHA256Managed
Dim buffer () As Byte = System . Text . Encoding . Default . GetBytes ( prefix & secretKey )
Dim hashOutput () As Byte = hashAlgorithm . ComputeHash ( buffer )
Dim byteKey ( 15 ) As Byte
Array . Copy ( hashOutput , byteKey , byteKey . Length )
Return byteKey
End Function
アプリケーション検証トークンを作成する場合、このメソッドに登録したシークレットキーと「SIGNATURE」という接頭辞を渡し、戻ってきたバイト配列値をHMAC-SHA256ハッシュ関数の共有キーとして使用します。その処理を行っているメソッドは次のようになります。sigパラメータの値を返すメソッドです。
Public Shared Function GetSignatureToken ( ByVal secretKey As String , ByVal token As String ) As Byte ()
Dim key () As Byte = Derive ( secretKey , "SIGNATURE" )
Dim hashAlgorithm As New HMACSHA256 ( key )
Dim data () As Byte = System . Text . Encoding . Default . GetBytes ( token )
Return hashAlgorithm . ComputeHash ( data )
End Function
GetSignatureTokenメソッドに与える文字列は「appid=…&ts=…」というクエリ文字列の形式になります。アプリケーション検証トークンを返すメソッドを次に示します。
Public Shared Function GetAppVerifierToken ( ByVal applicationId As String , ByVal secretKey As String ) As String
Dim timeStamp As String = GetTimestamp ()
Dim token As String = String . Format ( "appid={0}&ts={1}" , applicationId , timeStamp )
Dim signature As String = HttpUtility . UrlEncode ( Convert . ToBase64String ( GetSignatureToken ( secretKey , token )))
Return HttpUtility . UrlEncode ( String . Format ( "appid={0}&ts={1}&sig={2}" , applicationId , timeStamp , signature ))
End Function
アプリケーションIDとシークレットキーを渡すとアプリケーション検証トークンを返します。
先ほどの承認要求ページへリンク例のURLに作成したメソッドを使ってアプリケーション検証トークンを付けると次のように書くことができます。
<%
Dim ru As String = HttpUtility . UrlEncode ( "http://sample.gihyo.jp/Sample/Default.aspx" )
Dim pl As String = HttpUtility . UrlEncode ( "http://sample.gihyo.jp/Sample/PrivacyPolicy.aspx" )
Dim ps As String = "ApplicationStorage.ReadWrite"
Dim mkt As String = "ja-JP"
Dim params As String = String . Format ( "ru={0}&ps={1}&pl={2}&mkt={3}&app={4}" , ru , ps , pl , mkt , GetAppVerifierToken ( "****Application ID****" , "****SecretKey****" ))
%>
< a href= "https://consent.live.com/Delegation.aspx? <% =params %> " >Requesting Consent </ a >
今回はここまでです。以上の内容だけではまだ何もできませんが、今回は委任認証の流れとアプリケーションプロバイダが承認要求を行うところまでの処理を紹介しました。次回は承認情報を受信して承認トークンの解析を行いユーザーデータアクセスの準備ができるところまで紹介する予定です。