Tag: NWC

Note: This post was written in February 2020. Some screens and steps may have changed since then.

Introduction

With more organizations moving to the cloud, a common question that we see from Nintex developers is: “I used to use Query LDAP to retrieve my users from Active Directory. Now that my users are in Azure, how do I retrieve them?”

 Query LDAP is an out-of-the-box (OOB) action in Nintex Workflow for SharePoint on-premises. With minimal configuration, it allowed developers to grab users from an on-premises Active Directory (AD) group.

 The problem a lot of users face when they start using Nintex Workflow for Office 365 or Nintex Workflow Cloud (NWC), is that there’s no equivalent action to Query LDAP (at the time of writing this article).

 In this blog post we will learn how to leverage Microsoft Graph API to retrieve the members of an Azure AD group.

We will build our workflow using Nintex Workflow for Office 365. However, you can apply the same concepts you’ll learn today, if you’re building an NWC workflow.

Our Approach

 The end result of our workflow will be a collection of users’ principals, that you can use however you prefer. The collection will look as follows:

 ["JohannaL@M365x037951.OnMicrosoft.com","LeeG@M365x037951.OnMicrosoft.com","RaulR@M365x037951.OnMicrosoft.com","DeliaD@M365x037951.OnMicrosoft.com"] 

To get there, we’ll follow the steps below: 

• Azure AD:
  1. Get your Azure AD group’s ID
  2. Register a new Azure AD app
  3. Generate a new secret for the app
  4. Grant the app access to the Graph API
• Nintex Workflow:
  1. Use the Azure AD app ID and secret, and your tenant ID to get a bearer token
  2. Retrieve the access token from the bearer token
  3. Use the access token to call the Graph API and get the users from your Azure AD group
  4. The users will come back in a JSON object
  5. Parse the JSON object and generate a collection of user principals

Let’s get started

 In this tutorial, we will retrieve the members of an Azure AD group in a JSON object. From the JSON object we will retrieve the userPrincipleName property of each member. Once we have the members’ JSON object, it’s straightforward to grab any other user properties like display name, email, phone number etc.

 Our group name is “sg-Engineering” and it has the following four members:

Get your Azure AD group’s ID

1. Go to Azure AD: https://portal.azure.com/ -> Azure Active Directory
2. In the left navigation bar, click Groups
3. Click on your group’s name
4. Save the Object Id to a text editor.

5. This is your group ID.

Register a new app in Azure Active Directory and grant permissions

1. Go to Azure AD: https://portal.azure.com/ -> Azure Active Directory
2. Register a new app
   1. In the left navigation bar, click App registrations -> New registration

2. Fill-in the fields as follows:
   1. Name: give a name to your app
   2. Supported account types: select the option that best suits your requirements. For this tutorial, we’ll select “Accounts in this organizational directory only”
   3. Redirect URI: Web – http://localhost

4. Click Register at the bottom
5. Save the Application ID and Tenant ID to a text editor

3. Generate client secret
   1. Click Certificates & secrets -> New client secret

2. Fill-in the fields:
   1. Description: give a description to your client secret
   2. Expires: choose when you’d like the secret to expire

3. Click Add at the bottom
4. Save the Client Secret to a text editor

4. Grant your app permissions to Microsoft Graph
   1. Click API permissions -> Add a permission -> Microsoft Graph -> Application permissions

2. Select the following permissions:
   1. GroupMember -> GroupMember.Read.All
   2. Users -> User.Read.All
3. Click Add permissions at the bottom
4. You’ll need the Global Admin to click on Grant admin consent

5. You’ll need the Global Admin to click Yes for the confirmation pop-up
6. The permission’s Status should change from “Not granted” to “Granted”
7. Click Add a permission -> Azure Active Directory Graph (at the bottom)-> Delegated permissions
8. Select User -> User.Read
9. Click Add permissions at the bottom
10. You’ll need the Global Admin to click on Grant admin consent
11. You’ll need the Global Admin to click Yes for the confirmation pop-up
12. The permission’s Status should change from “Not granted” to “Granted”

Build the workflow

1. We’ll start by creating a new blank workflow
2. Then we’ll create the variables
   1. Click on Variables in the top bar, then add new variables as shown below:

3. Then we will set the variables to the values we saved from Azure AD:
   1. Add a Set Workflow Variable action and set the variables as follows:
      1. varTxtAppID:  Application ID you saved earlier
      2. varTxtTenantID: Tenant ID you saved earlier
      3. varTxtAppSecret: Client Secret you saved earlier
      4. varTxtGroupId: Group ID you saved earlier

4. Now we will get the bearer token
   1. Add a Web Request action
   2. Set the properties as follows:
      1. URL: https://login.microsoftonline.com/‍{Variable:varTxtTenantID}‍/oauth2/token
      2. Method: POST – content type: application/x-www-form-urlencoded
      3. Body: Content radio button – grant_type=client_credentials&client_id=‍{Variable:varTxtAppID}‍&client_secret=‍{Variable:varTxtAppSecret}&resource=https://graph.microsoft.com&scope=user.read
      4. Username: your username
      5. Password: your password
      6. Store response content in: varTxtBearerTokenJson
      7. Store http status code in: varIntgrResponseCode

Once this action runs, we will have retrieved the bearer token in a JSON format and saved it to our variable varTxtBearerTokenJson.  This is how the bearer token will look:

From the bearer token, we want to retrieve the access token.  The easiest way to do this, is to store the bearer token in a dictionary, then retrieve the value for the key “access_token”

5. Add a Set Workflow Variable action and set it as follows:
   1. varDctnryBearerTokenJson: varTxtBearerTokenJson

6. Add a Get An Item From A Dictionary action and set it as follows:
   1. Dictionary: varDctnryBearerTokenJson
   2. Item name or path: access_token
   3. Output: varTxtAccessToken

7. Log access token – to make sure we retrieved it successfully

Note: You will not see the full access token in Workflow History due to the character limit. You can Email it to yourself to see the full token.

8. Now, let’s call the Graph API and get the members
   1. Add a Web Request action
   2. Set the properties as follows:
      1. URL: https://graph.microsoft.com/v1.0/groups/‍{Variable:varTxtGroupId}‍/members
      2. Method: GET
         • Header name (key): Authorization
         • Header value: Bearer ‍{Variable:varTxtAccessToken}
      3. Username: your username
      4. Password: your password
      5. Store response content in: varTxtUsersJson
      6. Store http status code in: varIntgrResponseCode

Once this action runs, we will have retrieved the group members in a JSON format and saved the object to our variable varTxtUsersJson.  This is how the users’ JSON will look:

9. Now that we got the users, we need to extract the property userPrincipalName. We will retrieve it using Regex.
   1. Add a Regular Expression action
   2. Set the properties as follows:
      1. String: ‍{Variable:varTxtUsersJson}
      2. String operation: Extract
      3. Pattern: (?<=(userPrincipalName\”\:\”))[^”]+
         • Thanks to Tomasz Poszytek for providing the regex.
         • Note: https://regexr.com/ is a great tool to test your regex before using it in your workflow.
      4. Output: varCollUserPrincipalNames

10. Let’s confirm that we retrieved the users successfully
    1. Add a Send an Email action
    2. Set the properties as follows:
       1. To: your Email address
       2. Subject: Users
       3. Body:

          Response Code: {Variable:varIntgrResponseCode}

          Users Json: {Variable:varTxtUsersJson}‍

          Users Collection: {Variable:varCollUserPrincipalNames}

11. That’s it! Now run the workflow.
12. You should receive an Email with the following:
    1. Response Code of 200
    2. Your AD group members in a JSON format
    3. A collection of your AD group members’ user principal names

Conclusion

 Microsoft Graph API allows you to access tremendous amount of data in Microsoft 365.  In this tutorial we used the API to retrieve Azure AD group’s members. However, the API can be used for a lot more than that. The tricky part here was to get the access token.  Now that you learned how to get the token, check out the Graph API and see all the cool things you can do.

References

• Microsoft Graph API – Get access token without a user:
  https://docs.microsoft.com/en-us/graph/auth-v2-service
• Microsoft Graph API – List members end point:
  https://docs.microsoft.com/en-us/graph/api/group-list-members

Find this article and other interesting reads on DevFacto’s blog.