How to access the SPO REST API using implicit authentication flow

Overview

When SPO became popular as an enterprise content repository, there are many use cases which need to access SPO from various situations. One of use cases is to access SPO content from a custom web application. As SPA (Single Page Application) became as a main stream for web application development, we are talking about how to leverage OAuth 2.0 implicit grant flow to allow a SPA web application to access SPO resources via SPO REST API.

This article will focus on the protocol. We will explain the authentication flow using simple browser and PostMan so that the readers can understand the how it works behind the scene. The actual authentication flow can be implemented using whatever languages you want.

Azure AD Setup

First we need to create a Azure AD App to provide authentication. Once we passed the authentication, we also need to rely on this Azure AD App to acquire a access token to access SPO REST API. Let’s look at how to create a Azure AD App

• Login to Azure Active Directory from your tenant.
• Go to “App registration” → “New registration”. Fill in the following content to create an AAD App

“Name”: a display name for your AAD App.

“Supported account types”: choose whether you want to use single tenant or multitenant.

“Redirect URI”: for our walk through, we used “https://app.getpostman.com/oauth2/callback" because this URL will basically be used as a redirect URL which AAD will append token at the end of redirect URL. For your SPA, it will be your SPA application view URL where you need to process query string

• Once the AAD App is created, go to “Overview” tab to check the Client Id which we will use to request access token later

• Go to “Authentication” tab under the AAD App and check “Access token” and “ID token” options in “Implicit grant” section. In order to make SPA application to get access token to call SPO REST API, we need to check at least “Access Token” option which enables the implicit flow for your AAD App. Click “Save” button to save the changes.

• You can go to “Manifest” tab to check “oauth2AllowImplicitFlow” has been set to “True”.

• Go to “API permissions” to add SharePoint permissions

Click “Add a permission” to bring up “Request API permissions” panel.

Select “SharePoint” and select “Delegated permissions”. The Implicit grant flow authenticates a user. The permission is associated with the login user context which needs to be “Delegated permissions”.

Select “AllSites”->”AllSites.Read” permission.

Click “Add permission” to include this permission.

Once you add permissions, it depends on the permissions which you include. Sometime, you might need Admin consent the permissions. For our case, the “AllSite.Read” permission requires admin consent. For permissions which don’t need admin to consent, each user will be able to consent after login. As tenant admin, you need to click “Grant admin consent for Contoso” button to grant permissions for our case. After consent permissions, you will see “Granted for Contoso” at the end of each permissions. Now the AAD App should be ok to use.

Authentication Flow

We need to use the following URL to authenticate a user and get access token.

• Open up a browser and pass the following URL. For reading purpose, I used the multiple lines. For detail explanation of each paramater, please reference to Microsoft identity platform and Implicit grant flow

“client_id”: the AAD App we just created.

“response_type”: we used “token” because we want to get access token. You can pass “id_token” to get a ID Token for user’s information.

“redirect_uri”: the redirect URL which AAD login will redirect back. AAD also checks if this redirect URL is registered at AAD App.

“scope”: we use “https://[spotenantname].sharepoint.com/.default" to get all permission scopes which configured at “API Permissions” tab at above steps.

“response_mode”: this needs to be “fragment” which means the token information will be appended at the end of redirect URL after “#” sign. This will help you to parse the token information for a SPA application.

“state” and “nonce”: these can be your custom information which will return back after login process.

https://login.microsoftonline.com/m365x725618.onmicrosoft.com/oauth2/v2.0/authorize
?client_id=851f40f4-c054–4039-a7d7-f5f1ff336feb
&response_type=token
&redirect_uri=https://app.getpostman.com/oauth2/callback
&scope=https://[spotenantname].sharepoint.com/.default
&response_mode=fragment
&state=12345
&nonce=678910

• Once you complete the login process, you will see the AAD login redirect to an empty page with the following URL.

“https://app.getpostman.com/oauth2/callback#": the redirect URL you registered for your AAD App and also sent as parameter. Keep in mind that a “#” is added at the end to allow a SPA application to parse.

“access_token”: the access token which the AAD return back. You need to parse the URL to get access token.

“token_type”: this indicates it’s a “Bearer” token

“expires_in”: how many seconds this token will be expired. Default it’s 3599 seconds.

“scope”: the permission scope for your access token.

“state”: the state which you passed for your request.

“session_state”: the session state for this request.

https://app.getpostman.com/oauth2/callback#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d…&token_type=Bearer
&expires_in=3599
&scope=https%3a%2f%2fm365x725618.sharepoint.com%2fAllSites.Read+https%3a%2f%2fm365x725618.sharepoint.com%2fUser.Read+https%3a%2f%2fm365x725618.sharepoint.com%2f.default
&state=12345
&session_state=1025916c-33b4–4b03-a8c5–0aa3c0961fb9

Now you should be able to use the access token retrieved from redirect URL to access SPO REST API.

You might wonder what happens when the token is expired. Based on the AAD OAuth 2.0 implicit grant flow, there is no refresh token returned back. The access token will be expired after short period of time. Your SPA application needs to handle when a token is expired. When you use that access token to access SPO REST API, if you get 401 error , you can open up a hidden iframe to access the above URL with prompt=none to silently request a token.