Using OAuth2 security with Umajin

In this document we will use OAuth2 in conjunction with Microsoft Graph to authenticate and access sharepoint resources hosted on Microsoft Azure. This is accomplished by using Umajin’s JavaScript extensibility to add an OAuth2 mechanism to your Umajin project. The first step is to create a new JS file that will be placed in your project /scripts/ directory. This overview assumes you have already gone through Umajin’s tutorials and training on custom JavaScript components & actions. You can download the JavaScript file shown in this guide here: oauth2.js

Before we get started with the coding the first step to using Oauth2 and Microsoft Graph is to register a new application with MS Graph. You can do this by going to https://developer.microsoft.com/en-us/graph/ and then selecting “Quick Start” from the top navigation bar.

Phase 1 > Provision resources


You will then see the above screen to select a platform that you are building for, now even though we are building native apps for either iOS, Android, OS-X, Windows or All of the above we are going to select php.

On the next screen click the “Get an app ID and secret” button

Next Sign in with your Microsoft Credentials

Now copy and save your application secret and then click the “Got it, take me back to the quick start” button

Once returned to the quick start page copy your application ID. If you would like to change the name of your application from “My PHP App” to something else click the “Manage your app in the Application Registration Portal” link .

In the Application portal you can change the name of your App to something else. With our App Secret and our App ID we have everything we need to start coding our oauth2 script.

Phase 2 > Develop our JavaScript connectors

Now we will declare two global variables to store our App ID and secret and use the ID and secret that was just assigned to our application.

Next we declare a global variable to store our global web view object that is used for authorization. Web view will be used in our app to display the Microsoft login screen for authentication and to get an authorization code from Microsoft Graph. This authorization code is then used to get an access token.

Next we declare two variables to hold our tokens.

The following global variables specify the URL’s for Authorization, token request and the scopes our application is requesting access to. Please note offline_access is required in the scope to get a refresh_token. Other items such as Sites.ReadWrite.All gives us access to SharePoint site resources. For a list of all items that can be requested in the scope see this documentation: https://developer.microsoft.com/en-us/graph/docs/concepts/permissions_reference

Now we will create a custom action to start the oauth2 process. You will notice that we pass a web_view object to the custom action. This web_view component is used to display the Microsoft login screen. This function also checks to see if we already have a token and if so skips the login process.

We also create a custom action to clear our tokens. This is usefully especially if you want to create a signout option and don’t want cookies with tokens left behind.

Next we create an action that will be used to monitor the web_view component to extract the returned authorization code from the Microsoft login. This function calls two other functions that we will need to create. getParameterByName(url) will pull apart a URL and find a querystring param and getToken(code) will request the access_token and refresh_token using the authorization_code retrieved.

getParameterByName(url) which is called in the previous function is used to pull apart a URL and find a querystring param.

getToken(code) which is also called in the webviewMonitor(url) function will request the access_token and refresh_token using the authorization_code that was retrieved.

getToken(code) uses an http post request to get the token, this request requires two additional functions to be called in the event of a successful response and a failure response. In getTokenSuccess(resultBody, headers) we then save our access and refresh tokens. getTokenFail(message, status, body) will just be used to print the error response to the console.

Now that we can successfully get an oauth2 token lets do something useful with it. This will be very basic example showing how to retrieve a list of SharePoint lists from the root of a site. First we will create a couple of global variables. sharePoint_JSON will hold our returned JSON data and feed_list_global will hold our feed list component that is used to display the returned data.

Next we create a new custom action to get our lists. You can see below that in the header for our request we include the access token that we retrieved in the previous steps.

The above function uses an http get request with headers and requires two functions for a successful and a failure response. In the successful response we iterate through the returned JSON data and extract only the lists that are not flagged as hidden. We then use the names and ids of each item to build a custom JSON packet to pass to our feed list. The failure response will just print the error to the console.

Lastly we create a custom feed for our feed list component in our app to bind to.

Phase 3 > Design and build

That’s all the coding that is required now lets use our new functions in our application. Once you have built the connectors and feeds required this really enables your users and designers as they will be able to use these feeds and actions – and ensure they follow the policy and security you have embedded in the JavaScript.

You can deploy these as part of a project template or a plugin, but for this demo the JavaScript file needs to be manually placed in the scripts dir of your project. Once you create a new project add a new webview component, this will display our Microsoft login screen.

Next add our custom oAuth2 Start and set webview focus actions to the On Page Load event for our page.

Then select our web view component and add our custom oAuth2 web view Complete action to the On Error event.

Now create a second page to hold our sharepoint data feed list and add a feed list component to it.

Set the Data bindings of your new feed list to connect to the new custom feed we created.

After setting the data bindings you can create a master to control the layout of the data. Here I have created a simple one that will just display the name of the list item.

With the data bindings and master set now we can set up our mappings and map the list name to our “text 1” object.

The last step is to add our custom get SharePoint Root Lists action to the On Page Load event for the page containing our feed list.

Now let’s run our application! Here is our OAuth2 login screen.

And here is our list of sharePoint lists.