はじめに
今回もLive ConnectによるWindows Liveサービスと統合したアプリ開発を紹介します。これまでJavaScript APIを利用してWebブラウザー上で動作するアプリ開発について紹介してきましたが、今回はWebサーバー上で動作するWebアプリからLive Connectを使ってみましょう。
Live Connectは、Windows Liveサービス上のユーザーデータにアプリからアクセスする仕組みとして、標準的なプロトコルOAuth 2.0(以下、OAuth)を用いています。JavaScript APIを利用しないということは、OAuthで定義されている手順を実装すればよいということです。今回の内容はLive Connectの利用を前提としていますが、OAuthを実装したサービスであれば、ほかのサービスも同様の手順で利用できます。
OAuth 2.0
OAuthは、Windows LiveなどのWebサービスに、サードパーティ製のアプリから、ユーザーに代わってアクセスが制限されたデータの参照などの操作を可能にします。Live Connectの場合、Live Messenger、Hotmail、SkyDriveといったWindows Liveサービスのユーザーデータにアクセスするアプリが作れます。
通常、ユーザーがアプリに対して許可を与えることで、アプリからのアクセスを可能にします。この許可の承諾は、前回までの内容でも登場していました。JavaScript APIを利用すると、その後の処理はOAuthのプロトコルをあまり意識せずユーザーデータにアクセスができていましたが、WebアプリではOAuthの手順を知る必要があります。
アプリがユーザーデータにアクセスするためには、Access Token(アクセストークン)と呼ばれる許可内容や有効期限を示した文字列を、認証・認可を行うサーバーから受け取る必要があります。
アクセストークンの有効期限は短いため、Refresh Token(リフレッシュトークン)と呼ばれる新しいアクセストークンを取得するための文字列も利用できます。Live Connectの場合、wl.offline_accessというScope(スコープ)を要求します。スコープは許可を示す値で、これまでにも登場しています。
続いて、アクセストークンを得るまでのフローをみてみましょう。
認可フロー
Live Connectでは、アクセストークンを得る2種類の方法をサポートしています。
Authorization Code Grant Flow
ひとつめは、Authorization Code(認可コード)を使用する方法です。認可コードは、アクセストークンやリフレッシュトークンを得るために一時的に使用します。この方法は、Webサーバー上で動作するアプリの使用が想定されています。
フローは、図1のようになります。
OAuthでは、4種類のRole(ロール)が登場します。リソースオーナーは、アプリへアクセス許可を与える存在です。通常はアプリの利用者です。クライアントは、アプリを表します。認可サーバーは、認証・認可処理、認可コードやアクセストークン、リフレッシュトークンを発行します。リソースサーバーは、ユーザーデータ(リソース)を持っているサーバーです。
また、もうひとつ重要なのが、ユーザーエージェントです。通常、ユーザーエージェントはWebブラウザーのことです。リソースオーナーは、ユーザーエージェントを通してクライアントやサーバーとやりとりします。
フローの手順は次の通りです。アプリ利用者がWebサイトにアクセスした後から始まります。
①認証・認可画面(Webページ)へ移動します。通常、Webページにサインイン ボタンなどを表示し、アプリ利用者のクリックで移動します。移動先のLive Connect認可サーバーのエンドポイントは、以下のURLです。
- https://oauth.live.com/authorize?client_id=CLIENT_ID&scope=SCOPES&response_type=code&redirect_uri=REDIRECT_URL
URLのクエリーには、Client ID(クライアントID)、スコープ、リダイレクト先のURLなどを指定します。
②リソースオーナーは、Windows Liveサービスへのサインインと、アプリが要求する内容を許可します。
③①で指定したリダイレクト先へ移動します。このとき、認可サーバーは、URLのクエリーに認可コードを付けてリダイレクトします。
- http://example.jp/callback.php?code=[AuthorizationCode]
Webアプリは、ユーザーエージェントを介して認可コードを受け取ります。
④クライアントは、認可サーバーにアクセストークンを要求します。次のURLにアクセスします。
- https://oauth.live.com/token?client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&client_secret=CLIENT_SECRET&code=AUTHORIZATION_CODE&grant_type=authorization_code
URLのクエリーには、クライアントID、リダイレクトURL、Client Secret(クライアントシークレット)、認可コードなどを指定します。
⑤認可サーバーは、アクセストークンを発行します。
以上が、認可のフローです。リフレッシュトークンは、リソースオーナーに認可された場合、アクセストークンと一緒に発行され、クライアントが受け取ります。
Implicit Grant Flow
もうひとつのアクセストークンを取得する方法は、Webブラウザー上で動くアプリ向けの方法です。JavaScript APIはこの方法を使っています。デスクトップアプリでも使えます。
フローは、図2の通りです。
この場合のクライアントは、JavaScriptなどで実装されたWebブラウザー上で動作するアプリです。Webサーバーには、クライアントのリソース(HTML文書やスクリプト)があります。
フローの手順は次の通りです。
①認証・認可画面(Webページ)へ移動します。
- https://oauth.live.com/authorize?client_id=CLIENT_ID&scope=SCOPES&response_type=token&redirect_uri=REDIRECT_URL
②リソースオーナーは、Windows Liveサービスへのサインインと、アプリが要求する内容を許可します。
③①で指定したURLへリダイレクトします。このとき、認可サーバーは、URLのフラグメントにアクセストークンを付けてリダイレクトします。
- http://example.jp/callback.html#access_token=[AccessToken]
④ユーザーエージェントは、Webサーバー上のクライアントリソースのURLへリダイレクトします。このとき、URLの#以降のフラグメント部分にあるアクセストークンは、Webサーバーには送信されません。
⑤クライアントリソースは、JavaScriptなどのスクリプトを含むHTML文書を返します。
⑥ユーザーエージェントは、スクリプトを実行し、URLのフラグメントからアクセストークンを抽出します。
以上が、認可フローです。リソースへのアクセスは図では省略しています。リソースのアクセスは、ユーザーエージェントがアクセストークンを使ってリソースサーバーへ要求します。
ひとつめの認可コードを使う場合と比べると、アクセストークンをユーザーエージェントが持っている点が大きく異なります。また、この方法の場合、認可サーバーはリフレッシュトークンを発行しません。
以上が、OAuthで定義されている4種類のフローのうちの2種類でした。Live Connectでは、これ以外にJavaScript APIとサインインコントロールを使用したフローを用意しています。
サーバーサイドの処理
それでは、実際にWebサーバー上で動作するアプリのコードを書いてみましょう。認可コードによる方法を用います。今回は言語にPHPを使います。
前提条件として、アプリケーション設定サイトでアプリの登録を済ませている必要があります。アプリの登録は、第42回で説明しています。
認可コードの取得
認可コードを得るため、次のエンドポイントへアプリ利用者を誘導します。
- https://oauth.live.com/authorize?client_id=CLIENT_ID&scope=SCOPES&response_type=code&redirect_uri=REDIRECT_URL
パラメーターは次の通りです。
名前 | 説明 |
client_id | クライアントID |
scope | スコープ
複数の場合はスペース(URLエンコード「%20」)でつなげます。
例: wl.signin%20wl.basic |
response_type | レスポンスの種類
認可コードの場合 code |
redirect_uri | リダイレクトURL
ドメインは登録情報と一致している必要があります。 |
さらに次のパラメーターもオプションで指定できます。
名前 | 説明 |
display | 認可画面の表示形式
popup, touch |
locale | 認可画面の国・地域情報
例: ja |
state | アプリで使用する任意の値
指定した場合、認可サーバーからのリダイレクトURLに同値が含まれます。 |
display=touchを指定すると、モバイル端末向けのデザインになります。
認可サーバーがリダイレクトしたとき、codeパラメーターに認可コードが含まれています。
- http://example.jp/callback.php?code=[AuthorizationCode]
認可コードを取得するまでのPHPコードは、次のようにしました。認可画面へのリンクをコードで生成しています。
define部分はアプリにあわせて変更してください。上記のコードは、リダイレクト先を同じページとして処理を記述しています。
アクセストークンの取得
次は、アクセストークンを取得します。次のURLへHTTP POSTメソッドでアクセスします。
- https://oauth.live.com/token?client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&client_secret=CLIENT_SECRET&code=AUTHORIZATION_CODE&grant_type=authorization_code
パラメーターは次の通りです。
名前 | 説明 |
client_id | クライアントID |
redirect_uri | リダイレクトURL
ドメインは登録情報と一致している必要があります。 |
client_secret | クライアントシークレット |
code | 認可コード |
grant_type | 認可コードを使用する場合
authorization_code |
レスポンスは、JSON形式で次のような内容になります。
アクセストークン(access_token)のほかに、有効期限(expires_in)の秒数なども含まれています。リフレッシュトークン(refresh_token)は、スコープにwl.offline_accessを指定した場合に含まれています。
リソースのアクセス
続いて、リソースのアクセスです。リソースのアクセスはREST APIを利用します。次のURLへアクセスします。
- https://apis.live.net/v5.0/REST_PATH?access_token=ACCESS_TOKEN
REST_PATHは、アクセスするリソースのパスを指定します。前回までに紹介した内容では、meやme/albumsなどのパスです。ACCESS_TOKENにはアクセストークンを指定します。HTTPのGETやPOSTメソッドのどれを使うかは、リソースの操作内容によって異なります。
ここまでの内容をコードで書いてみましょう。認可コードを受け取った場合、リクエストトークンの取得、REST APIの呼び出しまでまとめて行っています。
上記コードは、REST APIを呼出し、サインインしているユーザーの名前を表示する単純な内容です。エラー処理はHTTP通信エラーの場合は省略、認可サーバーとREST APIのアクセスでエラーが発生したときはメッセージを表示する簡易的な記述しかしてありません。また、URLのクエリーのチェックは省略していますので注意してください。
リフレッシュトークンによる更新
リフレッシュトークンを使ったアクセストークンの更新方法についてもふれておきます。アクセストークンを更新するには次のURLにアクセスします。
- https://oauth.live.com/token?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token
認可コードからアクセストークンを取得するときと比べ、codeパラメーターの代わりにrefrsh_tokenパラメーターを使用して、リフレッシュトークンを指定します。そして、grant_typeパラメーターにはrefresh_tokenを指定します。レスポンスは同様にJSON形式で得ます。
リフレッシュトークンを使用してアクセストークンを得るアプリの場合、データベースなどにリフレッシュトークンを保存し、ユーザー管理を行う必要があります。
おわりに
今回はここまでです。いかがでしたでしょうか。PHPを使った簡単なWebサーバー上で動作するアプリを紹介しました。サーバー側で処理すると、ユーザーがサインインしていないときにも(許可されていれば)ユーザーデータにアクセスでき、SNSサービスなどのアプリも作成可能です。次回は、まだ紹介できていないWindows Liveサービスのユーザーデータ(リソース)について紹介する予定です。