Microsoft Graph API from NWC

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: That means we will be able to integrate to Office 365 SharepointOneDrive, 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.ActionDescriptionConfiguration
10Start Event – Nintex MobileThis 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 LocationWhich adds a Nintex Mobile Form as shown:
20Set a variable valueAssign 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.
30Branch by stageA 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.
40Call a web serviceWe use the “Call a web service” action to make a Microsoft Graph API call. The configuration as shown pretty much explains itself.
50Query JSONThis 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
60Branch by conditionI am using the Branch by condition action again to check if the errorCode variable equals to the suspected text of “Access token has expired.”
70Change stageIf the answer is no, will set the next stage to exit the branch, 
80Change stageor else, we will set the stage to Branch 2 to execute refresh access token
90Call a web serviceThis is the action to call the microsoftonline login service to obtain a new/refreshed Access Token.
100Change stageOnce 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: (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 HTTP/1.1content-type : application/x-www-form-urlencoded content-length : 144

This request requires a URL-encoded payload of the following format:


I 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 “&” 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. & the text after the @ mark is the Site Realm, you can find it by this URL to your sharepoint site https://<tenant>, it is shown as e.g. i:0i.t||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”

Using OAuth 2.0 to access other cloud services from NWC

Automating business processes on a cloud environment such as Nintex Workflow Cloud (a.k.a NWC) rely heavily on its “connectors” the workflow platform is offering. This could be a connection for an event trigger, reading or writing to an environment that is external to the NWC. In the event if the connector has not yet made available, one could still connect to external environment such as GoogleFacebookMicrosoft, etc. via the “call a web service” workflow action. For any platform on a cloud environment to connect to other cloud services, gaining authentication and access to other cloud services becoming critical before one service could communicate to the others. This is where the OAuth becoming common open standard for authorization among the cloud services.

This post provides a step by step sample configuration on how to get the NWC access the REST API of google drive using the OAuth 2.0 authentication.

Before we get into the required setup, let us take a look at a sample endpoint of the Google Drive API, we will look at one fairly straight forward endpoint to start – drive.files. The REST API call might look like the following, though you’ll need to specify your own access token:

GET /drive/v2/files HTTP/1.1Authorization: Bearer ya29.Ci9_A_SXTtG9QpxFS2gqKqHbAhX3QI68AHhTTl4vboNz_hItW2YYzy53FrdoRfBGGQHost:‍‍‍

The Oauth “access_token” to be provided following the “Authentication: Bearer” in this call is the required to gain access to the resources. (Note: A complete OAuth 2.0 steps include Obtain OAuth 2.0 credentials, Obtain access token, sending of access token to API, and refresh access token if necessary could be referenced from Google’s Oauth 2.0 Overview)

As access token to an application has limited life time, the automated process will need to verify if an access token has expired, and will need to refresh the access token with the Refresh Token obtained. Here is how the actual request might look like to exchange or refresh for an Access Token:

HOST /oauth2/v4/token HTTP/1.1Host: www.googleapis.comContent-Type: application/x-www-form-urlencodedclient_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}&grant_type=refresh_token‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Calling Drive API from NWC

The diagram below is a sample NWC workflow I’ve created to call the Google Drive API, I will explain each of the workflow action and its configuration in the following table:

Sample NWC Workflow - OAuth 2.0
Action NumberAction NameDescriptionSample Configuration
10Set a variable valueCreate and set the variable to the Access Token (please follow following sections on how to obtain Access Token and Refresh Token). This variable will be used and included in the API call later.
20Branch by stageDefining two branches, one for the normal API call, the other to Refresh Token in case it expired.
30Call a web serviceCalling the Google Drive API endpoint, in this example, I am calling the /drive/v2/files endpoint to my folderID.Request Headers to be included here is the Authorization with format shown:Authorization: Bearer <Access Token>The Response Content will have below error if the Access Token has expired:
 “error”: {
    “errors”: [
      “domain”: “global”,
      “reason”: “authError”,
      “message”: “Invalid Credentials”,
      “locationType”: “header”,
      “location”: “Authorization”
    “code”: 401,
    “message”: “Invalid Credentials”
40Query JSONIn my example, I am using Query JSON to parse or return the “message” of the suspected returned JSON content, which should be the “Invalid Credentials” value from the sample JSON content returned in the workflow action before this.
50Branch by conditionThe “Branch by condition” action to verify if the returned Response Content has the access related error(s). I should be checking against the Error code instead of the Error Message, unfortunately there is a bug the time this workflow is being tested, if I check against the $.error.code with the “equals” operator against value 401.
80Call a web serviceWhen “Refresh Token” branch is called, we will need to Refresh the Access Token using the Refresh Token obtained in previous steps.Please refer to the Using a refresh token section of the Using OAuth 2.0 for Web Server Applications guide for more details on the Refresh Token API.
90Query JSONParse the returned JSON with Query JSON action and assigned the refreshed Token to the variable to be used by the API Call.

Obtain OAuth 2.0 credentials from the Google API Console

1. Select Create project link from the Project Menu

2. Give your project a Project Name and fill up other details as necessary

3. On the Credentials page, create an Oauth client ID credential.
4. Fill in the requested information on the Configure consent screen page, and click Save to return to the Credential screen.

5. Select an Application type (i.e. Other in my example), and provide any additional information if required.
6. Click Create
7. The result of this process will be a Credential with Client ID and Client Secret as shown.

Obtain an access token from the Google Authorization Server

  1. One of the options to get the Access Token is via the OAuth2 Playground at this link, where we will obtain the access token and refresh token.
  2. Click the gear icon in the upper right corner and check the box labelled Use your own OAuth credentials (if it isn’t already checked).
  3. Enter the OAuth2 client ID and OAuth2 client secret obtained in previous step.

4. In the section labelled Step 1- Select & authorize APIs, select APIs you would like to access from NWC (i.e. I have selected in my case).

5. You will be prompted to grant access and authorization

6. In the tab labelled Step 2 – Exchange authorization code for tokens. Click Exchange authorization code for tokens.

7. This will get you the Refresh token and Access Token.

8. Copy the Refresh token and Access Token, which we## will need it in the API call in NWC workflow.