Following my previous post on Using OAuth 2.0 to access other cloud services from NWC, we are going to use the same principal but apply to Microsoft Graph API. Microsoft Graph exposes multiple APIs from Office 365 and other Microsoft cloud services through a single endpoint: https://graph.microsoft.com. That means we will be able to integrate to Office 365 Sharepoint, OneDrive, and other Azure and Office 365 related services from NWC with single Microsoft Graph API.
As you may be aware for now, the key challenge to connect to other cloud services will be more on the setup and getting the Access Token, which I have provided a sample on getting that up with Google OAuth 2.0 API, I will provide the steps to setup access to Microsoft Graph API later in this post.
Let us first take a look from the NWC end, a workflow we going to automate from Nintex Mobile submitting a new user request, the request gets submitted to NWC and triggers the call to Azure Active Directory API via the Microsoft Graph API, to create a new user in Azure Active Directory. From here, that should help us the understanding on all the possible scenarios we might have,
- Getting user details from Azure Active Directory or User profile from Sharepoint Online for CRM record update,
- A new user onboarding request handle by NWC to call Microsoft Graph API creating user(s) in Azure AD or assigning user the Office 365 licenses,
- Marketing event coordinator submits the attendant list in Excel file to OneDrive shared folder, it triggers the NWC workflow to read the metadata of the OneDrive file, determine if it is a file with new leads to be collected, it sends email to get the manager to review the file and for approval, once approve, the NWC workflow continues to read the excel file content and generate leads in CRM such as SalesForce or Microsoft Dynamic CRM, and so on.
Diagram below demonstrates the NWC Request for New User workflow I have created to show how that works, explanation of the actions provided in the table followed.
| Action No. | Action | Description | Configuration |
|---|---|---|---|
| 10 | Start Event – Nintex Mobile | This action defines the workflow to be triggered by a Nintex Mobile Form submission.For the demo, I have created four fields for the purpose: First Name, Last Name, Department, and Usage Location | Which adds a Nintex Mobile Form as shown: |
| 20 | Set a variable value | Assign the obtained “Access Token” to the accessToken variable.Note: Please refer to the later section of this write up on how to obtain the access token. | |
| 30 | Branch by stage | A two branches of workflow to handle a normal state with initial Access Token, and the second branch to get a new Access Token in case it expired.We’ve select for the workflow to start with Branch 1. | |
| 40 | Call a web service | We use the “Call a web service” action to make a Microsoft Graph API call. The configuration as shown pretty much explains itself. | |
| 50 | Query JSON | This is just the action to parse the returned content JSON for the error message if there is, and save the message to the errorCode variable | |
| 60 | Branch by condition | I am using the Branch by condition action again to check if the errorCode variable equals to the suspected text of “Access token has expired.” | |
| 70 | Change stage | If the answer is no, will set the next stage to exit the branch, | |
| 80 | Change stage | or else, we will set the stage to Branch 2 to execute refresh access token | |
| 90 | Call a web service | This is the action to call the microsoftonline login service to obtain a new/refreshed Access Token. | |
| 100 | Change stage | Once we got the new Access Token, the Change stage is set to run the Branch 1 to continue the Microsoft Graph API call for creating the new user in Azure Active Directory. |
Note: All the unnumbered actions are used for logging and troubleshooting purpose, you may ignore them.
Add Azure Active Directory App from Azure Portal
As of now, we understand that the OAuth 2.0 involves steps to obtain Credentials, and obtaining of the Access Token to be used in the API calls. In this section of write up, we will look at how to setup a service or daemon app in Azure portal. Unlike client apps, NWC workflows involves workflow actions without user intervention, the service or daemon app will be used to implement the OAuth 2.0 Client Credentials Grant Flow with its own credentials, its client ID and an application key, to authenticate when calling the Microsoft Graph instead of impersonating a user.
You may follow the steps from Microsoft Graph – Documentation – Register your application to register applications. Here are steps I followed creating the application I need for the NWC workflow:
1. Login to Azure Portal and navigate to App Registration to add/register a new application in Azure.
2. Fill up the application details, example as shown
3. Take note of the Application ID, which is the Client ID of the application. Select the Key link to create a key in the following step.
4. Create a key for the application by filling the Key Description, select a duration of the key. Take note of the Key’s value (i.e. will be generated after you clicked to Save) which will be used as the Client Secret for obtaining the Access Token.
Here is the screen shows the key with value after you hit the Save
5. The application is setup, we will need to grant it Required permissions to services we going to access via the application. Click the Add button to add Required permissions to the app.
6. Select services/applications you want to give the permissions to the application, or search for other applications with Service Principal name from the search box. I have selected Microsoft Graph as I am going to use Microsoft Graph API to query or update user object in the Azure Active Directory.
Depending on what API you will need for the Azure AD App to access, in my other example below, I have selected “Office 365 SharePoint Online (Microsoft.SharePoint)” for my test to trigger Nintex Workflow in Sharepoint Online.
Take note of the next screen as shown below, on the “Application permissions” selection, some of the application permissions “REQUIRES ADMIN” right, to which you will need to make sure using the right login for granting access to the resources at the later stage
With the above steps, we have got the Client ID, Client Secret, and we have granted permissions to the newly registered app access to Microsoft Graph API for actions we going to perform. We may proceed to obtain the Access Token to be used for the Microsoft Graph API calls.
Obtaining the Access Token
You may follow steps in Microsoft Graph – Documentation – Azure AD to obtain the required Access Token. Here are the steps I followed to obtain the Access Token.
1. Authorizing an app by submitting an HTTPS GET request using the following URL. I was doing this with an New Incognito Window of Chrome Browser, I find it quite safe to do it over the Incognito browser or you might not get the login and prompt to authorize app, this is due to my normal browser has all the login or cookies cached.
2. You should be getting Microsoft Online login page as shown. Once you login, you will need to accept the request to grant permission to the app. Please take note on what login you are going to use here, if the access to resources require an Admin rights, you will need to make sure you sign in with a user with Admin rights.
You will get below example after you have login, take note of my example here which says “You’re signed in as: kkg@ntxte07.com (admin)” – tells I have admin right to my SharePoint online.
3. Extract the code parameter value from the response URL, we will need to use it to acquire the initial OAuth 2.0 access and refresh tokens in the following steps. Take note to take the code=… portion only as the URL is ended with the session_state=…)
4. Obtain the access token using the following POST request:
POST https://login.microsoftonline.com/common/oauth2/token HTTP/1.1content-type : application/x-www-form-urlencoded content-length : 144This request requires a URL-encoded payload of the following format:
grant_type=authorization_code&redirect_uri=<uri>&client_id=<id>&client_secret=<secret_key>&code=<code>&resource=https%3A%2F%2Fgraph.microsoft.com%2FI was using the Advanced REST Client chrome extension for the purpose, you may use your own preferences for the purpose.
Take note for the above example, which is using the “&resource=https%3A%2F%2Fgraph.microsoft.com%2F” for the “Raw Payload“, you will need to specify different string for the &resource=<resource> depending what resource the app is meant to access. If the resource is Sharepoint Online, the example of the &resource=<resource> will be (e.g. &resource=https%3A%2F%2Fntxte07.sharepoint.com@225f091c-3a64-4a82-96be-2cced10088d4) the text after the @ mark is the Site Realm, you can find it by this URL to your sharepoint site https://<tenant>.sharepoint.com/_layouts/15/appprincipals.aspx, it is shown as e.g. i:0i.t|ms.sp.int|ba179145-f946-42c6-8aeb-90d6957af1fe@225f091c-3a64-4a82-96be-2cced10088d4 under the “App Identifier” column).
5. You should get a 200 OK response with response body containing the Access Token, Refresh Token, and others. We will need to supply the Access Token to any ensuing HTTP requests to access Microsoft Graph resources, or the Refresh Token for obtaining new Access Token when it expired.
Here is the example of the response screen of the “Advanced REST Client” with 200 response code, you will need to scroll down to see the JSON content which consists of the “Access Token” and “Refresh Token”
