Nintex Workflow – Get Users from Azure Active Directory Group

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 developers 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 in a cloud environment (as of February 2020).

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 objectFrom the JSON object we will retrieve the userPrincipleName property of each memberOnce 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: 

Azure AD Group 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 Azure Active Directory Group ID
  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. In the left navigation bar, click App registrations -> New registration  Registering a new app in Azure Active Directory
    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://localhostRegister in app
      4. Click Register at the bottom
      5. Save the Application ID and Tenant ID to a text editorSave App ID and Tenant ID
  3. Generate client secret
    1. Click Certificates & secrets -> New client secretNew Client Secret Azure AD Nintex
    1. Fill-in the fields:
      1. Description: give a description to your client secret
      2. Expires: choose when you’d like the secret to expireAzure AD Secret
      3. Click Add at the bottom
      4. Save the Client Secret to a text editorGrant app permissions to Microsoft Graph
  1. Grant your app permissions to Microsoft Graph
    1. Click API permissions -> Add a permission -> Microsoft Graph -> Application permissions Grant app permissions to Microsoft Graph
  1. Select the following permissions:
    1. GroupMember -> GroupMember.Read.All
    2. Users -> User.Read.All
  2. Click Add permissions at the bottom
  3. You’ll need the Global Admin to click on Grant admin consent Grant admin consent
  1. You’ll need the Global Admin to click Yes for the confirmation pop-up
  2. The permission’s Status should change from “Not granted” to “Granted”
  3. Click Add a permission -> Azure Active Directory Graph (at the bottom)->Delegated permissions
  4. Select User -> User.Read
  5. Click Add permissions at the bottom
  6. You’ll need the Global Admin to click on Grant admin consent
  7. You’ll need the Global Admin to click Yes for the confirmation pop-up
  8. The permission’s Status should change from “Not granted” to “Granted”Permissions Granted

Build the workflow

  1. We’ll start by creating a new blank workflow
  1. 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:Variables
      1. varTxtAppIDApplication ID you saved earlier
      2. varTxtTenantID: Tenant ID you saved earlier
      3. varTxtAppSecret: Client Secret you saved earlier
      4. varTxtGroupId: Group ID you saved earlierSet Workflow Variables
  2. 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: varIntgrResponseCodeGet Bearer Token

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:

Bearer Token

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”

  1. Add a Set Workflow Variable action and set it as follows:
    1. varDctnryBearerTokenJson: varTxtBearerTokenJsonSet Bearer Token Json
  1. 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
  2. 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.Log Access Token
  1. 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: varIntgrResponseCodeGet Users Json

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:

Retrieved Users Json

  1. 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\”\:\”))[^”]+
      4. Output: varCollUserPrincipalNamesRegular Expression Json
  1. 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}Send Email
  1. That’s it! Now run the workflow.
  2. 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

Received Email

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 know 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.

Microsoft Graph API – List members end point.

 

A version of this article also appears on Wisam’s blog Consultant Diary.

 

User Adoption Matters – How to Succeed with Your Office 365 Rollout 

We all know that technology is evolving fast. In fact, new technology has never been released as frequently as it is now, and this couldn’t be more true for Office 365 and SharePoint Online. Since Microsoft came out with Office 365 in 2011, many organizations moved to the cloud platform recognizing the benefits for their business and their employees. In the time since, Microsoft released many updates and many additional applications to improve the usability of its cloud platform.

But for every light, there must be a shadow. While Microsoft works tirelessly to continue improving its Office 365 platform, organizations often struggle to keep up with Microsoft’s pace. A prominent example is the fast update-cycle of Office 365, which can cause issues when organizations introduce new technology to their employees and plan accompanying activities like user adoption and change management. For some organizations, planning and executing user adoption campaigns can take some time, and while the user adoption team is still working on the campaigns, newer features may already be added by Microsoft.

For most organizations, the step towards the cloud (Office 365 and SharePoint Online) is a significant step not only for the organization, but the entire staff as well. As a consultant, I realize this every time I assist organizations with migrating from file-shares to SharePoint Online. Quite often, organizations manage this transformation by augmenting a SharePoint Online rollout with user training. Unfortunately, activities that are proven to drive user adoption, such as internal user adoption campaigns and proper change management, sometimes take the backseat – much to the detriment of the staff. In this article, I’ll discuss how including them in your Office 365 or SharePoint Online rollout can drastically increase the user adoption rate.

Why Office 365 User Adoption Matters?

First, let’s have a look at why proper and tailored user adoption activities matter to every organization implementing Office 365 or SharePoint Online. They:

  • Protect organizational ROI. Rolling out a new technology not only takes effort, but also costs money. Most enterprises justify the project spend with a projected ROI (Return on invest). Because technological investment should generally lead to lowered operational costs and increased efficiency, it is in the vital interest of all organizations to ensure that new technology is used by the entire staff as expected.
  • Benefit the Employees. Modern technology should not only provide benefits to the organization, but also improve the daily work of employees. Unfortunately, this is where the problems begin. Not all employees embrace changes to their daily routines, even at a promise of easing the workload. While tech-savvy ones are eager to try out the new tools and updates, others may remain reluctant or hesitant to change. This is where user adoption campaigns really matter. Organizations can run them to ensure that the new technology is used by the entire staff as expected by the organization – without making employees feel imposed!

The way towards organization-wide user adoption can differ between organizations. When talking to executives and stakeholders about user adoption and change management, I often realize that many organizations think they provided proper user adoption activities by offering tailored training sessions and emailing corporate announcements regarding the new technology. But in most cases, that is far too little to ensure that the new tool is used as expected. User adoption is much more than just training and announcements. It is a long-term activity (or an internal project – if you want to put it that way), which requires extensive planning.

Build a Office 365 User Adoption Team

It all starts with establishing a user adoption team as any user adoption campaign needs to be handled like an internal project. Here is a high-level list of roles within a user-adoption team, which should be adjusted based on your corporate culture:

  • Adoption Team Lead: Responsible for managing the user-adoption team, planning tasks and scheduling meetings.
  • Moderator(s): Responsible for planning and performing user-adoption campaigns. In most cases, it makes sense to involve Power Users or Key Users. I recommend involving professional moderators or at least employees who are used to public speaking (or have stage experience).
  • Communicator(s): Responsible for all communication around the user-adoption activities. I recommend a professional communicator as the style of communication needs to be engaging, enthralling and carefully tailored to the target audience.
  • Technical Expert(s): Responsible for technical support, knowledge transfer and measurement of the identified success factors (as explained later). Often, Office 365 admins take over this role.
  • Trainer(s): Responsible for delivering accompanying training sessions.
  • Executive(s) and Stakeholder(s): Part of the team to highlight the importance of user adoption and to ensure that organizational interests are considered.
  • Corporate Governance Committee: Although the Governance Committee does not need to take over an active role, keeping them up to date on planning and the current state allows them to chime in if there are any corporate policies which need to be considered.

Establish Goals

If we look at the user adoption team, it becomes clear that a user adoption campaign isn’t a one-time activity like training. Rather, it’s an ongoing process, that strives to accomplish several goals:

  • Introduce a new technology to employees in a way which is tailored to their skill set and technical abilities.
  • Provide individual examples on how to use the introduced technology based on roles and responsibilities.
  • Focus on the benefits that employees can achieve by using the new technology, in other words: show how this new technology can be used to meet individual goals.
  • Explain how the technology fits corporate strategy.

Out of all these, the most important one is certainly focusing on benefits that matter to employees, as it is likely that not all employees will embrace changes to their daily routines. From an organizational standpoint, user adoption activities need to ensure that new technology is used as planned. From the user’s perspective, new technology will affect the daily business and most employees are primarily interested in “what is in it for me,” rather than what are the benefits the organization is hoping to achieve. Basically, this discrepancy is the reason, why user-adoption campaigns are crucial.

So, What Can You Do to Drive Office 365 User Adoption?

Here are some proven tactics:

  • Schedule events to introduce the new technology to all employees. These events should offer a high-level overview of the solution that explains the intended use of the technology and its place within existing applications and procedures.
  • Schedule meetings with individual departments to showcase how employees of particular departments will benefit from using the new technology. Since requirements vary between departments, user adoption activities should be designed to address needs specific to different roles.
  • Use gamification. Create a buzz around your technology and get your employees involved early on. You can try panel games, quizzes or digital scavenger-hunts to draw the attention to the new technology. The most important thing is to be creative and engaging. Based on my long-standing experience, gamification works wonders if done properly.
  • Perform surveys throughout the course of the user adoption campaign to get a sense of how your employees are using the new technology and gauge if the campaign is working.
  • Identify success factors and proper measurements. For example, if you run a user adoption campaign for a OneDrive for Business roll-out, a success factor could be a 50% increase of the data stored to OneDrive for Business accounts within three (3) months of implementation.
  • Offer individual training for employees struggling with using the introduced technology.
  • Schedule recurring monitoring that continues even after the user-adoption campaign has ended. It is important to continue measuring how the introduced technology is used during the coming months.
  • Work with the corporate help desk to understand inquiries and tickets related to the introduced technology. Although an increased number of inquiries is common, too many inquiries are an indicator that the user adoption campaign isn’t working well or isn’t meeting your audience’s needs or expectations.

Finally, when it comes to user adoption, there is no one-fits-all approach. Organizations are diverse, as are their employees. A proper user adoption campaign needs to be tailored to the corporate culture, the skill sets of employees and most importantly, the expected benefits for individual users. Proper user adoption campaign is crucial for rolling out any new technology. Training is just an accompanying activity rather than a replacement for user adoption and change management. For that reason, the cost of a tailored user adoption campaign needs to be added to the costs of the new technology and the corporate rollout. However, when a user adoption campaign is planned and executed properly, these additional costs will pay off soon helping secure a timely ROI.

Additional Resources: