Operations using REST in SharePoint Online – Authorization

How to retrieve X-RequestDigest header to authorize yourself in SharePoint Online? This is the knowledge I’d like to share with you.

SharePoint Online is exposing the public REST API that hypothetically enables users to perform all necessary actions using HTTP requests. In fact, the official documentation on MSDN does not cover as many actions as I needed, so I had to do additional research several times to get things done.

Introduction

Today I’m going to talk about building an integration layer with SharePoint Online using C#.

For documentation regarding list operations you can refer to: https://msdn.microsoft.com/en-us/library/office/dn292552.aspx

When it comes to executing requests, the biggest issue here is authorization. In the documentation you can see that every HTTP request contains authentication header, for example:

blog_artur1

Moreover, if you want to execute a POST request there is also a X-RequestDigest header that needs to be included:

blog_artur2

I sought more information in the MSDN documentation and I found this article: https://msdn.microsoft.com/en-us/library/office/jj164022.aspx

The headers are explained in the table on the bottom but this explanation does not apply to my case.

When it comes to authorization header I couldn’t use Microsoft Access Control Service (ACS) as it requires to provide “client secret” which I didn’t have (as I needed to perform actions on the whole SharePoint site, not on a single SharePoint application).

As for the X- RequestDigest header I found information that I can retrieve the value by making a request to the Contextinfo endpoint, but no further details were provided.

After a successful research on my own I found out that instead of authorization header there are two cookies that need to be included in every request: FedAuth and rtFa. How to retrieve them and how to retrieve X-RequestDigest header to authorize yourself in SharePoint Online? This is the knowledge I’d like to share with you.

Prerequisites:

  1. SharePoint Online website
  2. Username and password to Microsoft account with permissions to the website above
  3. Visual Studio and .NET 4.5 libraries

I created a wrapper library. The source code is available on my public Github profile: https://github.com/icandoit-net/PublicRepo/tree/master/SpOnlineWrapper. As it grew bigger I had to split responsibilities according to the Single Responsibility Principle. First I’ll quickly describe the project structure.

blog_artur3

Client – this is the main class in the library. It has two methods exposed: GET and POST. It initializes the authorization handler and then executes the request.

Authorization handler – this class is responsible for the retrieval of FedAuth and rtFa cookies and X-RequestDigest header. It initializes and executes the logic included in two other handlers: AuthRequestsHandler and XmlHandler.

AuthRequestsHandler – this class is responsible for executing the actual requests needed for authorization and returning a successful response

XmlHandler – this class is responsible for creating SAML body request and handling SOAP response.

HandledHttpWebResponse – this is a structure used in handling HTTP responses. I created it as by default, in case of 400 or 500 response, the default .NET class HttpWebRequest throws an exception

SamplTemplate.xml – this is a SAML template sent in the request body as a first step to retrieve authorization cookies. It is used as a library resource.

The rest of it are some helpers, tools etc.

Authorization cookies

To retrieve FedAuth and rtFa cookies we need to follow this procedure:

blog_artur4

  1. Assign the SAML template to a string variable. This method retrieves the template from the resources and puts username {0}, password {1} and BaseUrl {2} to the SharePoint site to it.
    blog_artur5
  2. Once we have this template, we post it as a body to a Microsoft Login service using HTTP POST request: https://login.microsoftonline.com/extSTS.srf. As a response from this service we get a SAML response with a security token included. The response looks like this (click to enlarge):blog_artur6
  3. Then we need to parse the response and retrieve the actual security token.
  4. The final step is to use this token as a request body to SignIn service to receive authorization cookies by executing a HTTP POST request. The SignIn service is exposed at: { base URL } + /_forms/default.aspx?wa=wsignin1.0″. You just have to make sure to include two headers in this request: Content-Type: “application/x-www-form-urlencoded”, and User-Agent: “Mozilla/5.0 (Windows NT 10.0; WOW64; rv:50.0) Gecko/20100101 Firefox/50.0”.
  5. In response you should retrieve the FedAuth and rtFa cookies which are then returned and used in every further request.

X-RequestDigest header

As I mentioned above, to perform HTTP POST requests to your SharePoint Online besides authorization cookies you need to include the X-RequestDigest header. To retrieve this header you need follow this procedure:

blog_artur7

  1. You need to send a HTTP POST request to ContextInfo endpoint with authorization cookies included, previously retrieved as shown above. This endpoint can be found at { your site URL } + “/_api/contextinfo”.
  2. After a successful request you get a SOAP response that needs to be parsed. The result is is a DigestValue that needs to be used as a value of the X-RequestDigest header.

That’s it, you’re now authorized. In the next post I will show you how to use my wrapper to execute a simple request to your SharePoint Online REST API.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s