2015/10 追記 : 今後、商用向け (Commercial) の Office 365 (Azure AD のアイデンティティ) と一般向け (Consumer) の Office 365 (Microsoft Account のアイデンティティ) の Idenity Endpoint と REST Endpoint が統一される予定です。詳細は「Office 365 API の Commercial & Consumer の Unified 開発」を参照してください。

こんにちは。

以下に、Live Services 開発 (Outlook.com, OneDrive などの開発) についてまとめておきます。

なお、かなり昔 (数年前) に「Office & Office 365 Development Sample」にサンプル プログラムをアップしましたので、そちらもご参照ください。(この中のサンプル「SharePoint Online へのファイル保存」で OneDrive への保存も実装しています。一部、古い API を使ってましたので、本日、修正版のコードを push しておきました。。。)

今回、改めて流れを解説しておきます。

ここでは、おおまかな概念を紹介しますので、API Reference などの詳細は「MSDN : Windows Live Services」を参照してください。

Live Services と Office 365

Live Services では、サービスとして、Outlook.com (旧 Hotmail)、連絡先リスト (People)、Calendar、OneDrive (旧 SkyDrive)、および関連する Office Online (OneNote Online 含む) を対象としています。
Microsoft には他にも似たようなサービスのラインアップがありましたね。そうです、本日解説した Office 365 です。

Office 365 が Enterprise (Business) 利用を想定しているのに対し、Live Services は Consumer 利用を想定しており、SLA なども異なっています。
開発者にとって重要な点は、Identity 基盤として、Office 365 では Azure Active Directory (Azure AD) を使用しているのに対し、Live Services は Microsoft Account (MSA) を使用している点です。
接続先のエンドポイントはもちろん異なりますし、Windows Live Services には「管理者」という概念もないので、例えば、Azure AD におけるユーザー管理用の API なども提供されていません。(ユーザーの Bulk 作成も不可能です。)

しかし、基本概念は本日紹介した OAuth 2.0 をベースとしているので、Office 365 はもちろん、Facebook、Twitter、Google、LinkedIn など昨今のインターネット サービスの開発を一度でも扱ったことがある方なら、容易に受け入れられるでしょう。
以下に手順を記載しますが、以前このブログで紹介した「Office 365 API 入門」と ほぼ同様の流れです。

補足 (2015/10 追記) : OneDrive など Consumer サービス (一般向けサービス) の有償版として、Office 365 Home (日本では Office 365 Solo) が提供されています。(現在、Office 365 ブランドとして統一されています。)

Register your application

では、以下に基本的なフローを紹介します。
まず、OAuth 2.0 を使った認証フローを実装する前に、アイデンティティ基盤にアプリケーション登録をおこなって、API 呼び出しの際に必要になる client id (app id), client secret (app secret) などを取得します。

Azure Portal (https://portal.azure.com/) に Office 365 の管理者アカウントでログインをおこなって、Azure AD の管理画面でアプリケーションを登録します。(設定手順詳細は「Office 365 API 入門」を参照してください。) アプリケーションの種類として、[Accounts in any organizational directory (Any Azure AD directory – Multitenant) and personal Microsoft accounts] を選択します。

なお、アプリケーションを登録すると Application Id (Client Id) が作成されるので、この値をコピーしておきます。

登録したアプリケーションの [Authentication] (認証) メニューを選択して、[Live SDK support] が [Yes] (はい) になっていることを確認してください。

また、登録されたアプリケーションの [Redirect URIs] に皆さんが作成するアプリケーションの URL を設定してください。OAuth のフローでログイン直後に戻る URL で、この Redirect URI も このあと使用しますので、コピーしておきます。

登録が完了したら、[Certificates & secrets] (証明書とシークレット) メニューを選択して Client Secret を作成し、この値も同様にコピーしておきます。

HTTP Flow – Authentication (認証)

では、HTTP Flow を見てみましょう。OAuth 2.0 で認証をおこない、OneDrive のフォルダー一覧を取得するサンプルを紹介します。

まず、Web Browser (Mobile アプリの場合は、Browser Component など) を使って以下の URL にアクセスします。
下記で client_id と redirect_uri には、上記の値を設定します。
また、処理の内容に応じ、下記の scope を設定します。今回は、ログインをおこなって OneDrive の情報の読み込むため、下記の通り、wl.signin と wl.skydrive を「wl.signin wl.skydrive」のように空白 (Space) で区切って指定します。(指定可能な scope については、「MSDN : Windows Live Services – Scopes and permissions」を参照してください。)

GET https://login.live.com/oauth20_authorize.srf?response_type=code&client_id=<client id>&scope=wl.signin%20wl.skydrive&redirect_uri=<redirect uri>

この Url にアクセスすると、Web Browser (Browser Component) は、下図のような SignIn 画面を表示するので、Microsoft Account でログインします。
Azure AD 同様、Microsoft Account で二要素認証 (多要素認証) を使っている場合などでも、必要な処理はすべて Browser がおこなってくれるので、開発者は、こうした応用的なインフラ構成に対しても特別な処理 (追加の処理) を実装する必要はありません。

なお、ユーザーがはじめて この Appication を使用する場合、下図のような Consent UI が表示されます。
ここでは、このアプリケーション (LiveDemoApp01) に OneDrive の情報を参照する権限 (アクセス許可) の付与を求めており、一度、[はい] (Yes) をクリックすると、以降、この Consent UI は表示されません。

補足 : このアクセス許可は、Microsoft Account の管理画面 (Consent 管理)で削除できます。(あとでこのアプリが信用できなくなった場合は、利用者自身が、この画面で削除できます。この辺りも、Google Account, Facebook など他と同様です。)

認証に成功すると、Browser は下記の Url にリダイレクトします。auth code には、認証結果としての Authorization code (auth code) が入っています。

<redirect uri>?code=<auth code>

例えば、以下のような Url です。

https://tsmatsuz-test1.azurewebsites.net/?code=f8244459-53...

つぎに、上記で取得した auth code を使って、下記の POST 要求 (Request) を出します。

POST https://login.live.com/oauth20_token.srfContent-Type: application/x-www-form-urlencodedgrant_type=authorization_code&code=<auth code>&client_id=<client id>&client_secret=<client secret>&redirect_uri=<redirect uri>

この POST 要求の結果として、下記の Json フォーマットの Response Body が返ってきます。
下記の通り、access token と呼ばれるものが取得できています。

{  "access_token": "EwAwAq1DBAAUGCCXc8w...",  "authentication_token": "eyJhbGciOiJIUzI1NiI...",  "expires_in": 3600,  "scope": "wl.signin wl.skydrive",  "token_type": "bearer"}

なお、scope として wl.offline_access を指定すると、下記の通り refresh token と呼ばれるものが取得できます。
refresh token は、access token が期限切れになった場合の取り直しなどで必要になります。(既定では 1 時間で期限切れになります。) Mobile Application などでは、この wl.offline_access も設定しておくと良いでしょう。

{  "access_token": "EwA4Aq1DBAAUGCCXc8w...",  "authentication_token": "eyJhbGciOiJIUzI1NiI...",  "expires_in": 3600,  "refresh_token": "tzUSQAAAHgA%241R4eG...",  "scope": "wl.offline_access wl.signin wl.skydrive",  "token_type": "bearer"}

HTTP Flow – Service 呼び出し

2015/10 追記 : 今後、OneDrive, Outlook.com, Skype などの一般向け (Consumer 向け) 開発では、商用版の Office 365 との共通化がおこなわれます。(既に OneDrive, Outlook では、共通の REST API が正式提供されています。) 詳細は、「Office 365 API 開発 – OneDirve API」、「Office 365 API 開発 – Outlook REST API」を参照してください。(下記は、古い REST API です。)

あとは、取得した token を使って、必要なサービスを呼び出します。
今回は、OneDrive の (root の) Folder 一覧を取得するため、以下の通り GET 要求 (Request) を出します。

GET https://apis.live.net/v5.0/me/skydrive/files?access_token=EwA4Aq1DBAAUGCCXc8w...

上記の結果として、OneDrive の REST サービスは、以下のような Json フォーマットの Body を返します。

{  "data":  [{  "id": "folder.9c0af81b735e29ea.9C0AF81B735E29EA!2386",   "from":  {"name": "Tsuyoshi Matsuzaki", "id": "9c0af81b735e29ea"  },   "name": "Test Folder 1",  "description": "",   "parent_id": "folder.9c0af81b735e29ea",   "size": 63701264,   "upload_location": "https://apis.live.net/v5.0/folder.9c0af81b735e29ea.9C0AF81B735E29EA!2386/files/",   . . .},{  "id": "folder.9c0af81b735e29ea.9C0AF81B735E29EA!4010",   "from": {"name": "Tsuyoshi Matsuzaki", "id": "9c0af81b735e29ea"  },   "name": "Test Folder 2",   "description": "",   "parent_id": "folder.9c0af81b735e29ea",   "size": 4489499,   "upload_location": "https://apis.live.net/v5.0/folder.9c0af81b735e29ea.9C0AF81B735E29EA!4010/files/",   . . .},. . .  ]}

OneDrive にファイルをアップロードする場合には、scope に wl.skydrive_update を設定し、POST メソッドで登録します。
OneDrive API (REST) の詳細については「MSDN : OneDrive API」を参照してください。

補足 : 実は、Live Services では、他に、下記の OAuth Endpoint も使えます。ただし、下記の Endpoint では、後述する wl.imap など、一部の新しい scope には対応していないので注意してください。(古い Endpoint です。)
https://oauth.live.com/authorize
https://oauth.live.com/token

なお、下記の通り response_type=token とすることで、URI Fragment の一部として access token を返す Implicit Grant Flow にも対応できます。(例えば、https://tsmatsuz-test1.azurewebsites.net/#access_token=EwB4Aq1D…&authentication_token=eyJhbGci…&token_type=bearer&expires_in=3600&scope=wl.signin%20wl.offline_access&user_id=6b58b4a… などのフォーマットで戻されます。)
JavaScript からのアクセスなどに向いています。

https://login.live.com/oauth20_authorize.srf?response_type=token&client_id=<client id>&scope=<scopes>&redirect_uri=<redirect uri>

Live Services API で可能なこと

上記では OneDrive の読み込みをおこないましたが、「MSDN : Windows Live Services」に記載されている通り、以下のような処理が可能です。(2014/06 月現在)

• Profile 情報との連携
• OneDrive への読み書き (Document, Photo, Video など含む)
• Outlook.com を使用したメールの送受信や Sync
• Calendar (カレンダー) との連携
• Contacts (連絡先) リストへの読み書き
• OneNote Service API の使用

なお、Outlook.com (旧 Hotmail) では、SMTP (server: smtp-mail.outlook.com)、ActiveSync (server: s.outlook.com) に加え、昨年 (2013 年) 秋に OAuth 2.0 サポートと IMAP (server: imap-mail.outlook.com) にも対応しました。
IMAP なので、メール受信の通知なども実装できます。

補足 : Outlook.com の設定で POP も有効 (Enable) にできます。(既定では、POP は Disable になっています。)

例えば、下記のプログラムは、上記の Flow で取得した Access Token を使って、Mail を送信する Node.js のプログラムです。(このプログラムを outlook_oauth2_test.js と仮定します。)
Node.js パッケージの nodemailer を使っています。
(ただし、Access token を取得する際、scope に wl.imap を指定する必要があります。)

var nodemailer = require("nodemailer");var trans = nodemailer.createTransport("SMTP", {  host: 'smtp-mail.outlook.com',  port: 587,  ssl: false,  use_authentication: true,  auth: {XOAuth2: {  user: "dummyuser01@hotmail.com",  clientId: "00000000401235B7",  clientSecret: "2ZDjDbVgm0wm20...",  accessToken: "EwB4Aq1DBAAUGC..."}  }});var options = {  from: "dummyuser01@hotmail.com",  to: "dummyuser02@gmail.com",  subject: "Are you busy ?",  generateTextFromHTML: true,  html: "<b>Are you busy ?</b>"};trans.sendMail(options, function(err, res) {  if (err) {console.log(err);  } else {console.log(res);  }  trans.close();});

以下のコマンドで nodemailer をインストールして、上記プログラム (outlook_oauth2_test.js) を実行すると、OAuth 2.0 と SMTP による Outlook.com からの Mail 送信がおこなわれます。

npm install nodemailernode outlook_oauth2_test.js

C# (.NET) の場合、.NET 標準の System.Net.Mail.SmtpClient は OAuth に対応していないため、NuGet から取得可能な Mail.dll などを使用すると良いでしょう。(コードは省略します。)

Live SDK

上記では Live Services 開発の HTTP Flow を紹介しましたが、こうした処理を API 化した Live SDK が提供されています。
この SDK は、以下で使用可能です。

• Windows store app の Managed Code (.NET)
• Windows phone app の Managed Code (.NET)
• Windows store app の JavaScript (JavaScript)
• Web アプリ (JavaScript)
• iOS
• Android

例えば、下記は、[Login] ボタンを押すと Microsoft Account の SignIn 画面を表示してログインをおこない、[Get Folders] ボタンを押すと OneDrive からフォルダー一覧を取得する Web Application のサンプルです。

<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head>  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />  <title></title>  <script src="http://blogs.msdn.com//ajax.aspnetcdn.com/ajax/jquery/jquery-1.9.0.min.js"></script>  <script src="http://blogs.msdn.com//js.live.net/v5.0/wl.debug.js"></script>  <script>$(document).ready(function () {  WL.Event.subscribe('auth.login', function () {// change to enabled !$('#foldersBtn').removeAttr('disabled');  });  WL.init({client_id: '00000000401235B7′,redirect_uri: 'https://tsmatsuz-test1.azurewebsites.net/',response_type: 'token'  });  $('#loginBtn').click(function () {WL.login({ scope: 'wl.signin wl.skydrive' }).then(  function (res) {// some post login processes...  },  function (res) {alert('error occured !');  });  });  $('#foldersBtn').click(function () {WL.api({  path: 'me/skydrive/files',  method: 'GET'}, function (res) {  if (res.error) {alert(res.error.message);  } else {$.each(res.data, function (i, val) {  alert(val.name);});  }});  });});  </script></head><body>  <button id="loginBtn">Login</button>  <button id="foldersBtn" disabled>Get Folders</button></body></html>

以下の通り、内部の Access token も取得できます。

WL.getLoginStatus(function (status) {  var access_token = status.session.access_token;  alert(access_token);});

実は、この Live SDK、内部では複雑なことをやっています。
例えば、上記の Web Application 用の Live SDK では、別の Window (Web Browser) を Popup してログイン (SignIn) 画面を表示し、上記の Implicit Grant Flow により access token を取得して、返された access token を呼び出し元の Window (親 Window) に渡して Popup 画面を閉じます。
OneDrive API の呼び出しでは、JSONP を使って access token を受け渡すことで Cross-Domain 呼び出しの問題を回避しています。(Cross-Domain 呼び出しの考え方については、「クロス ドメイン (Cross-Domain) 問題の回避と諸注意」を参照してください。)

これら一連の流れは、すべて Live SDK のライブラリー自身が内部で処理しているので、開発者 (API 利用者) は、こうした複雑な Flow を意識する必要はありません。

※ 修正記録

2016/04/21  アプリ登録を Live Connect Developer Site (https://account.live.com/developers/applications/) から Application Registration Portal (https://apps.dev.microsoft.com/) に変更

2019/06/30  アプリ登録を Application Registration Portal から新 Azure Portal (https://portal.azure.com) に変更