SharePoint Online (O365) OAuth Authentication | Authorizing REST API calls against SharePoint Online Site | Get Access token from SharePoint Online | Set up OAuth for SharePoint Online Office 365

- March 27, 2015

Here is my most awaited post on how to set up OAuth for SharePoint Online so that we can authorize REST API calls to the SharePoint site to retrieve data and manipulate the site data.

The steps going to be easy and I will demonstrate along with screenshots and examples with the Google PostMan RESTClient.

I have explained the steps below which follows the OAuth 2.0 protocol. All the steps are straight forward, but constructing the URLs are little tricky!

Below are the detailed steps:

1. Register an app in SharePoint

· Navigate to https://your_site_name.com/_layouts/15/appregnew.aspx

· Click Generate for Client Id and Client Secret.

· Give a name for the app, fill in the app domain (ex: www.google.com, www.salesforce.com). Enter the Redirect URL, important here is when entering redirect url, it should be https and this is the url, to which the site redirects once you authorize your app and get auth.code (which will be explained later).

· Click Create.

· (Imp!) Note down the Client Id, Client Secret and redirect_uri.

Fill in the details:

2. Get the Realm of your site.

Realm is a constant GUID for a site. Save this realm for future use. Follow below steps to get the realm:

· Download Google Postmanpackaged app.

· Install and launch it.

· Make a Get request as shown in the screenshot:

GET https://your_site.sharepoint.com/_vti_bin/client.svc

Authorization: Bearer

· Get the Bearer realm component from the response header and save it.

3. Get the Authorization code from Azure Access Control Service

Construct the authorization url as follows:

https://your_site.sharepoint.com/_layouts/15/OAuthAuthorize.aspx?client_id=client_GUID&scope=app_permissions_list&response_type=code&redirect_uri=redirect_uri

As the example show, we need to send OAuth client Id and redirect URI to the SharePoint site as query string parameters. The following is an example of the GET request with sample query string values. Line breaks have been added for clarity. The actual target URL is a single line.

https://your_site.sharepoint.com
/_layouts/oauthauthorize.aspx
    ?client_id= d1a20424-c89d-4195-a29e-cf5796d90dd6
    &scope=Web.Read
    &response_type=code
    &redirect_uri=https%3A%2F%2Flocalhost%2F

Where:

· Client id is the client Id which we have got while registering the app in step. 1 above.

· Scope which describes the Scope and the Right to be granted for the app.

This parameter is a space-delimited set of permission scope and right requests. (ex: we can also have scope=Web.Read List.Write)

Scope URI	Scope Alias	Available Rights
http://sharepoint/content/sitecollection	Site	Read, Write, Manage
http://sharepoint/content/sitecollection/web	Web	Read, Write, Manage
http://sharepoint/content/sitecollection/web/list	List	Read, Write, Manage
http://sharepoint/content/tenant	All Sites	Read, Write, Manage

The table above describes the Scope URI, Scope Alias and the Right. The values listed in the Scope Alias column are shorthand versions of their counterparts in the Scope URI column. For more info on this please refer Understand permission scope aliases and the use of the OAuthAuthorize.aspx page.

· response_type =code (in order to get the auth.code).

· redirect_uri redirect url. Must be same as the redirect url given in step. 1. Note that this url is encoded.

Now the full url will be as follows:

https://your_site.sharepoint.com/_layouts/oauthauthorize.aspx?client_id=d1a20424-c89d-4195-a29e-cf5796d90dd6&scope=Web.Read&response_type=code&redirect_uri=https%3A%2F%2Flocalhost%2F

Now, navigate to this url from your browser, login to the site if you have not logged in already.

Opens a consent page prompts the user to grant (or deny) the app the permissions that the app requests. In this case, the user would be granting the app read access to the current Site (Web).

Once you grant the permission (by clicking trust), SharePoint Online site asks ACS to create a short-lived (approximately 5 minutes) authorization code unique to this combination of user and app. ACS sends the authorization code to the SharePoint site.

SharePoint Online site redirects the browser back to the redirect URI that was specified when the app was registered in step.1. It also includes the authorization code as a query string. The redirect URL is structured like the following:

https://redirect_url/?code=<authcode>

Extract query string value code from above url and it will be used in next step. This is the authorization code and it lasts for approx. 5 minutes!

4. Get the access token and refresh token:

What..? Yes! We are in final step to get the access token. In this step I will demonstrate how to get access token and refresh token from Google Postman.

Construct the below post request:

https://accounts.accesscontrol.windows.net/<site_realm>/tokens/OAuth/2

Post parameters:

grant_type=authorization_code

&client_id=<client_id>@<site_realm>

&client_secret=<client_secret>

&code=<auth_code>

&redirect_uri=<redirect_url>

&resource=< audience principal ID>/<site_host>@<site_realm>

As the above structure show, we need to send OAuth client Id, client secret, auth code, redirect URI and resource to the SharePoint site as post body. The following is an example of the POST request with sample values. Line breaks have been added for clarity.

Also observe that I have encoded all the values.

https://accounts.accesscontrol.windows.net/d2076ad6-6179-41cb-b792-24716a55ea90/tokens/OAuth/2

Post parameters:

grant_type=authorization_code

&client_id=d1axxxx-xxxx-xxxx-xxxx-cf5796d90dd6%40d2076ad6-xxxx-xxxx-xxxx-24716a55ea90

&client_secret=RoYzG%2FAmf%2BaRrfNsdfdgLFsdfsxvMSHrj51BK4dUDqdB3%2BO4%3D

&code=<paste the long auth.code from previous step here>

&redirect_uri=https%3A%2F%2Flocalhost%2F

&resource=00000003-0000-0ff1-ce00-000000000000%2Fyour_site_name.sharepoint.com%40d2076ad6-6179-41cb-b792-24716a55ea90

Where:

· Grant_type authorization_code (in order to get access token and refresh token).

· client_id <client id from step1>@<site realm from step2>.

· client_secret <client secret code from step1>.

· Code <auth.code from previous step).

· redirect_uri <redirect url from step1>

· resource <audience principal ID>/<sharepoint domain>@<site realm>.

audience principal ID is a permanent security principal ID for SharePoint

Google Postman demonstration:

Open Google Postman and press Alt+n for a new request. Note that it is a POST request.

Follow my screenshot below. Fill the post parameters similar to the example above, replace the value accordingly. Also keep in mind that the auth.code lasts for only 5 minutes. After 5 minutes, you can generate the fresh auth.code by following the step 3 again! Please save the access token and refresh token safely.

Fill in the values:

Response:

5. Get access token if it is expired by using refresh token:

Last but not the least, once you have access code, you can make use of powerful SharePoint 2013 REST APIs. But access code has a validity of 12 hours. So after 12 hours access code will get expired and you will need to get a new access token again!

Don’t panic! J You don’t need to follow all the steps againJ. You can make use of the refresh token and get a fresh access token again.

Here is how you get a new access token using refresh token:

This step is almost similar to step 4, except 2 differences. Here the difference is that we use:

· grant_type as refresh_token and

· refresh_token instead of code in step4 and use the refresh token which we have saved in step4.

https://accounts.accesscontrol.windows.net/<site_realm>/tokens/OAuth/2

Post parameters:

grant_type= refresh_token

&client_id=<client_id>@<site_realm>

&client_secret=<client_secret>

&refresh_token =<refresh_token_from_step_4>

&redirect_uri=<redirect_url>