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

===== on-premise環境のSharepoint連携との違いについて =====
以前の投稿(([[study:java:sharepoint|Java consuming SharePoint REST API]]))でon-premise環境のSharepointサービスと連携する方法を紹介しました。\\
Sharepoint online連携においてon-premise環境と大きい違いは以下の2点です。\\
  - 認証方式
  - SSL接続(TLS)
まず、認証方式ですがon-premiseと同じくユーザー認証((Add-in認証方式もありますが、認証に使うクライアントシークレットの有効期限がある為、ユーザー認証を選択しました。))を使いますが、認証スキムが異なります。\\
on-premise環境ではNTLM認証を使いましたが、cloud環境ではSAML認証を使います。また認証cookieも利用します。\\
SSL接続については、POC段階ではツール((curl, firefoxのRESTClient, POSTMAN等のツールがあります。))が対応しているため、意識する必要はありませんが、実装段階ではTLSのバージョン、Cipher Suite(暗号スイート）等を確認する必要が出てくるかも知れません。
===== POCの概要 =====
POCの流れを下記に示します。
  - %%UserRealm%%確認
  - SAML Security Token取得
  - Binary Token取得
  - Sharepointサイトcookie取得
Sharepointサイトのcookieが取得できれば、RESTサービスの利用はon-premise環境の手順と同じです。\\
つまりForm Digest valueを取得して、%%Endpoint%%にHttpリクエストを送信することです。

===== POC段階1 =====
%%UserRealm%%を確認する理由は、ADFS(Active Directory Federal Service)環境かどうかの確認と、ADFS環境の場合STS(Security Token Service)のURLを調べるためです。\\
調べるために、下記URLをGET送信します。
<code>
https://login.microsoftonline.com/getuserrealm.srf?login=%(UserAccount)&xml=1
</code>
ここで、%%%(UserAccount)%%に利用アカウント（XXX.onmicrosoft.com若しくは独自ドメインのアカウント）を代入します。\\
ADFSを利用している場合のResponse例を下に示します。
<code xml>
<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>
</code>
ここで、%%<IsFederatedNS>%%項目を見れば、ADFS環境かどうかが分かります。\\
上記の例ではtrueですので、ADFS環境になります。\\
また、%%<STSAuthURL>%%項目のURLがSAML Security tokenを取得するために必要なURLになります。
===== POC段階2 =====
SAML Security tokenを取得するために、前段階で取得した%%STSAuthURL%%宛にSOAPメッセージをPOST送信します。
SOAPメッセージ例を下に示します。
<code xml>
<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>
</code>
ここで、%(username), %(userpass)には、ユーザーアカウント及びパスワードを代入します。\\
また、上記xmlを送信する際、Requestヘッダーに下記を追加します。
<code>
 Content-Type:application/soap+xml; charset=utf-8
</code>
Responseのxmlから%%<t:RequestedSecurityToken>%%に囲まれる部分がSAML Security tokenです。\\
こちらのraw typeテキスト((Pretty typeではエラーになります。))がBinary token取得のために必要です。\\
SAML Security tokenの例は、内容が長いのと見てもチンプンカンプンなのでLOL割愛します。

===== POC段階3 =====
Binary tokenを取得するために、前段階で取得したSAML Security tokenをSOAPメッセージとして下記URLにPOST送信します。
((ここからは外部にアクセスするため、会社等のProxy環境にある場合は、Proxy認証が必要になります。))
<code>
https://login.microsoftonline.com/extSTS.srf
</code>
SOAPメッセージの例を下に示します。
<code xml>
<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>

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

また、上記xmlを送信する際、Requestヘッダーに下記を追加します。
<code>
 Content-Type:application/soap+xml; charset=utf-8
</code>

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

===== POC段階4 =====
いよいよ最後の段階です。長い道のりでしたが、ここではcookieを取得する方法を見てみます。\\
下記のURLに前段階で取得したBinary tokenをPOST送信します。
<code>
https://xxxx.sharepoint.com/_forms/default.aspx?wa=wsignin1.0 
</code>
xxxxには、独自ドメイン（エイリアス）が入ります。\\
正常の場合は、HTTP code=302(FOUND)が帰ってきます。\\
そして、下記の２つのcookieがResponseヘッダーに含まれているのが確認できます。((内容が長いため、一部分をカットしました。))
<code>
Set-Cookie: rtFa=I4phG2qFs+pUekvF4a03qJ0Pt79SUAzM3bLl5CMkZbgmODJDRjhFQjQtRTEzQi; path=/; SameSite=None; secure; HttpOnly
</code>
<code>
Set-Cookie: FedAuth=77u/PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48U1A+VjEwLDBoLmZ; path=/; SameSite=None; secure; HttpOnly
</code>
こちらの取得したcookieを次のリクエストを送信する際、Cookieヘッダーに追加します。\\
以降のRESTサービスへのリクエストは、認証cookieさえあれば利用可能です。
===== Reference =====
  * [[http://www.sharepoint-insight.com/2016/03/21/step-by-step-sharepoint-online-authentiaction-process-via-http-protocol/|Step-by-Step SharePoint Online Authentiaction Process via HTTP Protocol]]
  * [[https://sharepoint.stackexchange.com/questions/235083/how-to-send-an-sso-saml-assertion-to-sharepoint-online-to-get-fedauth-and-rtfa-c|How to send an SSO SAML assertion to Sharepoint Online to get FedAuth and rtFa cookies?]]
  * [[https://stackoverflow.com/questions/11295953/claim-auth-from-adfs|Claim auth from ADFS]]

~~DISCUSSION~~