POC of consuming Sharepoint online

本稿では、Sharepoint onlineのRESTサービスを利用するための処理フローを紹介します。
Javaの実装例は別の記事で紹介する予定です。

以前の投稿¹⁾でon-premise環境のSharepointサービスと連携する方法を紹介しました。
Sharepoint online連携においてon-premise環境と大きい違いは以下の2点です。

1. 認証方式
2. SSL接続(TLS)

まず、認証方式ですがon-premiseと同じくユーザー認証²⁾を使いますが、認証スキムが異なります。
on-premise環境ではNTLM認証を使いましたが、cloud環境ではSAML認証を使います。また認証cookieも利用します。
SSL接続については、POC段階ではツール³⁾が対応しているため、意識する必要はありませんが、実装段階ではTLSのバージョン、Cipher Suite(暗号スイート）等を確認する必要が出てくるかも知れません。

POCの流れを下記に示します。

1. UserRealm確認
2. SAML Security Token取得
3. Binary Token取得
4. Sharepointサイトcookie取得

Sharepointサイトのcookieが取得できれば、RESTサービスの利用はon-premise環境の手順と同じです。
つまりForm Digest valueを取得して、EndpointにHttpリクエストを送信することです。

UserRealmを確認する理由は、ADFS(Active Directory Federal Service)環境かどうかの確認と、ADFS環境の場合STS(Security Token Service)のURLを調べるためです。
調べるために、下記URLをGET送信します。

https://login.microsoftonline.com/getuserrealm.srf?login=%(UserAccount)&xml=1

ここで、%(UserAccount)に利用アカウント（XXX.onmicrosoft.com若しくは独自ドメインのアカウント）を代入します。
ADFSを利用している場合のResponse例を下に示します。

<RealmInfo Success="true">
    <State>3</State>
    <UserState>2</UserState>
    <Login>%(UserAccount)</Login>
    <NameSpaceType>Federated</NameSpaceType>
    <DomainName>独自ドメイン</DomainName>
    <FederationGlobalVersion>-1</FederationGlobalVersion>
    <AuthURL>https://xxxxxx.contoso.com/adfs/ls/?username=${UserAccount}&amp;wa=wsignin1.0&amp;wtrealm=urn%3afederation%3aMicrosoftOnline&amp;wctx=</AuthURL>
    <IsFederatedNS>true</IsFederatedNS>
    <STSAuthURL>https://xxxxx.contoso.com/adfs/services/trust/2005/usernamemixed</STSAuthURL>
    <FederationTier>0</FederationTier>
    <FederationBrandName>XXXX</FederationBrandName>
    <AllowFedUsersWLIDSignIn>false</AllowFedUsersWLIDSignIn>
    <Certificate>証明書情報</Certificate>
    <MEXURL>https://xxxx.contoso.com/adfs/services/trust/mex</MEXURL>
    <PreferredProtocol>1</PreferredProtocol>
    <EDUDomainFlags>0</EDUDomainFlags>
    <CloudInstanceName>microsoftonline.com</CloudInstanceName>
    <CloudInstanceIssuerUri>urn:federation:MicrosoftOnline</CloudInstanceIssuerUri>
</RealmInfo>

ここで、<IsFederatedNS>項目を見れば、ADFS環境かどうかが分かります。
上記の例ではtrueですので、ADFS環境になります。
また、<STSAuthURL>項目のURLがSAML Security tokenを取得するために必要なURLになります。

SAML Security tokenを取得するために、前段階で取得したSTSAuthURL宛にSOAPメッセージをPOST送信します。 SOAPメッセージ例を下に示します。

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
      xmlns:a="http://www.w3.org/2005/08/addressing"
      xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue</a:Action>
    <a:ReplyTo>
      <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
    </a:ReplyTo>
    <a:To s:mustUnderstand="1">https://xxxxx.contoso.com/adfs/services/trust/2005/usernamemixed</a:To>
    <o:Security s:mustUnderstand="1"
       xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <o:UsernameToken u:Id="uuid-7b105801-44ac-4da7-aa69-a87f9db37299-1">
          <o:Username>%(username)</o:Username>
          <o:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">%(userpass)</o:Password>
        </o:UsernameToken>
    </o:Security>
  </s:Header>
  <s:Body>
    <t:RequestSecurityToken xmlns:t="http://schemas.xmlsoap.org/ws/2005/02/trust">
      <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <a:EndpointReference>
          <a:Address>urn:federation:MicrosoftOnline</a:Address>
        </a:EndpointReference>
      </wsp:AppliesTo>
      <t:KeyType>http://schemas.xmlsoap.org/ws/2005/05/identity/NoProofKey</t:KeyType>
      <t:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Issue</t:RequestType>
      <t:TokenType>urn:oasis:names:tc:SAML:1.0:assertion</t:TokenType>
    </t:RequestSecurityToken>
  </s:Body>
</s:Envelope>

ここで、%(username), %(userpass)には、ユーザーアカウント及びパスワードを代入します。
また、上記xmlを送信する際、Requestヘッダーに下記を追加します。

 Content-Type:application/soap+xml; charset=utf-8

Responseのxmlから<t:RequestedSecurityToken>に囲まれる部分がSAML Security tokenです。
こちらのraw typeテキスト⁴⁾がBinary token取得のために必要です。
SAML Security tokenの例は、内容が長いのと見てもチンプンカンプンなので割愛します。

Binary tokenを取得するために、前段階で取得したSAML Security tokenをSOAPメッセージとして下記URLにPOST送信します。 ⁵⁾

https://login.microsoftonline.com/extSTS.srf

SOAPメッセージの例を下に示します。

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
 xmlns:a="http://www.w3.org/2005/08/addressing"
 xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue</a:Action>
    <a:ReplyTo>
      <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
    </a:ReplyTo>
    <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      %(samltoken)
    </o:Security>
  </s:Header>
  <s:Body>
    <t:RequestSecurityToken xmlns:t="http://schemas.xmlsoap.org/ws/2005/02/trust">
      <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <a:EndpointReference>
          <a:Address>%(siteurl)</a:Address>
        </a:EndpointReference>
      </wsp:AppliesTo>
      <t:KeyType>http://schemas.xmlsoap.org/ws/2005/05/identity/NoProofKey</t:KeyType>
      <t:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Issue</t:RequestType>
      <t:TokenType>urn:oasis:names:tc:SAML:1.0:assertion</t:TokenType>
    </t:RequestSecurityToken>
  </s:Body>
</s:Envelope>

ここで、%(samltoken)には、SAML Security tokenをraw typeで代入します。
続いて、%(siteurl)には、SharepointサイトURLを代入します。

また、上記xmlを送信する際、Requestヘッダーに下記を追加します。

 Content-Type:application/soap+xml; charset=utf-8

Http送信の結果、xmlが帰ってくるのですが、<wsse:BinarySecurityToken>に囲まれている長いテキストがBinary tokenです。
こちらのtokenはcookie取得のために必要です。

いよいよ最後の段階です。長い道のりでしたが、ここではcookieを取得する方法を見てみます。
下記のURLに前段階で取得したBinary tokenをPOST送信します。

https://xxxx.sharepoint.com/_forms/default.aspx?wa=wsignin1.0 

xxxxには、独自ドメイン（エイリアス）が入ります。
正常の場合は、HTTP code=302(FOUND)が帰ってきます。
そして、下記の２つのcookieがResponseヘッダーに含まれているのが確認できます。⁶⁾

Set-Cookie: rtFa=I4phG2qFs+pUekvF4a03qJ0Pt79SUAzM3bLl5CMkZbgmODJDRjhFQjQtRTEzQi; path=/; SameSite=None; secure; HttpOnly

Set-Cookie: FedAuth=77u/PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48U1A+VjEwLDBoLmZ; path=/; SameSite=None; secure; HttpOnly

こちらの取得したcookieを次のリクエストを送信する際、Cookieヘッダーに追加します。
以降のRESTサービスへのリクエストは、認証cookieさえあれば利用可能です。

• Step-by-Step SharePoint Online Authentiaction Process via HTTP Protocol
• How to send an SSO SAML assertion to Sharepoint Online to get FedAuth and rtFa cookies?
• Claim auth from ADFS