Microsoft Integration

Introduction

This integration enables the flow of data from Microsoft directly in to IT Glue. Tenants, Users and Mailbox information will sync automatically, staying accurate and up to date.

Benefits of this integration include:

  • Managing the options of your Microsoft asset including manual syncing and comparing data between IT Glue and Microsoft
  • Jump from IT Glue to a User List in the Tenant Portal when you click Manage on a synced Contact
  • Viewing logs related to your Microsoft integration in the Sync Logs

At any time, you can come back to the Active Integrations screen (Admin > Integrations) to make changes to the integration.

The field mappings are set up automatically when you follow the instructions below. For more information, refer to our Microsoft Field Mapping topic.

IMPORTANT  As of January 5th 2024 we're now supporting GDAP, please follow the below steps to ensure your integration is working correctly.

Prerequisites

  • Manager or Administrator access to IT Glue
  • One available data source
  • Microsoft Cloud Partner certified to offer delegated administration
  • Delegated admin permissions to each of your clients' Microsoft tenants through your own Microsoft admin portal, rather than direct logins to their admin portals.

  • Granular Delegated admin permissions (GDAP) relationship with Microsoft Entra roles to each of your clients' Microsoft tenants through your own Microsoft admin portal. (Not applicable to single tenants).

You will need to turn off a feature in Microsoft that conceals users, groups, and site names. If you do not turn off this feature then the integration will not be able to see mailbox usage. To prevent this issue, action the following steps in the Microsoft 365 Admin Center.

  1. In the Microsoft 365 Admin Center, navigate to Settings > Org Settings > Services.
  2. Select Reports.
  3. Clear Display concealed user, group, and site namesin all reports, and click Save.

Please note that the Microsoft integration supports direct logins to client admin portals, but integrating in this way requires an additional data source and following the steps in this article for each client you wish to integrate.

IMPORTANT  Warning. Before you start this integration, thoroughly review your existing contacts in IT Glue and ensure they follow the matching logic below. If existing contacts do not match exactly to this logic, the integration will create unwanted duplicates.



IT Glue Asset IT Glue Field Microsoft Field
 Contacts Email 
  1. Attempt match on any alias of the Microsoft user.
  2. Attempt match on the username value (e.g. the @onmicrosoft.com domain).
  3. Attempt match on combination of First Name + Last Name.

Configuring GDAP

The following are the three important steps to be done in the Microsoft Portal to set up GDAP.

  1. Create a Service account user for GDAP.

  2. Create a new Security Group and assign the service account user to the group.

    NOTE  In the Partner Portal, it is required to assign this security group to each GDAP relationship for all the tenants.

  3. Configure the applications with proper permissions.

    NOTE  As of January 5th, 2024 both Delegated and Application permissions are required to be added.

Create a service account user for GDAP

IMPORTANT  The procedure in this section is required only for Granular Delegated Admin Permissions tenants and not relevant for Delegated Admin Permissions.

Microsoft’s GDAP provides an approach of having the least privilege for access controls. To integrate this approach with IT Glue, do the following steps:

  1. Log in to your Microsoft Account
    Sign_in_to_your_account.png

  2. In the left-hand sidebar, click Users > Create New User.

  3. Select the group as AdminAgents.

  4. Assign the role as Global Administrator.

    The service account user is now created for the GDAP IT Glue integration.

    NOTE  MFA must be enabled for this service account.

Create a new Security Group

Create a new Security Group and add the service account user to the group for the GDAP IT Glue integration.

  1. Navigate to Groups and click New Group to create a new group.

  2. Click No members selected under the Members section and add the service user to the group.

  3. Click Create to create the security group. The created group is displayed in the list of groups.

    NOTE  From the Microsoft admin portal, assign this Security group to the GDAP relationship which includes the service account created in the previous section.

    IMPORTANT  In the Partner Center, you need to ensure that this security group created is assigned to each GDAP relationship and has at least one of the following permissions:

    • Global Admin

    • Privilege Role Admin

    • Cloud Application Admin

    If you assign any permission other than Global Admin (Privilege Role Admin or Cloud Application Admin), then following permissions are required to be assigned.

    • Global Reader

    • Intune administrator

    • Insights Business Leader

Configure Application

  1. In the left-hand sidebar, click Applications > App registrations.

  2. Click + New registration.
    Company_-_Azure_Active_Directory_admin_center22.png
  3. Complete the following actions in the Register an application screen.
    1. Name - Enter an application name that will be displayed to users of the app.
    2. Supported account types - Select the Accounts in any organizational directory and personal Microsoft accountsoption to map to Azure AD only multi-tenant.
    3. Redirect URI (optional) - If desired, select Web in the drop-down menu and enter a URL for the app.
      Register_an_application_-_Azure_Active_Directory_admin_center.png
  4. Click the Register button at the bottom of the screen to access the newly created application.

    NOTE  Redirect URL is required for users setting up GDAP.

    NA: https://subdomain.itglue.com/microsofts

    EU: https://subdomain.eu.itglue.com/microsofts

    AU: https://subdomain.auitglue.com/microsofts

Get Application ID and Tenant ID 

  1. In the left-hand column, click Azure Active Directory > App registrations and then All applications. Click on your newly configured application in the list.
    Company_-_Azure_Active_Directory_admin_center33.png
  2. Click the Copy to clipboard icon beside the Application ID and Directory ID (Tenant ID) and paste them into IT Glue. Refer to the Integrating Microsoft with IT Glue section in this KB article.
    Screen_Shot_2020-12-09_at_12_12_35_PM.png

Generate secret key

  1. In the left-hand column, click Certificate & secrets and then + New client secret. An Add a client secret screen will appear.
    IT_Glue_Integration_2020_-_Azure_Active_Directory_admin_center44.png
  2. Add a description for your client secret, select 24 months under Expires and then Add.
    Screen_Shot_2022-02-01_at_12_42_53_PM.png
  3. In the Value column, click the Copy to clipboard icon beside the secret key and paste it in to IT Glue. Refer to the Integrating Microsoft with IT Glue section in this KB article.
    IT_Glue_Integration_2020_-_Azure_Active_Directory_admin_center55.png

    NOTE  After you save the configuration changes, the right-hand column will contain the client secret value. Be sure to copy the value for use in your client application code as it will not be accessible once you leave the page.

Add Permissions

You will need to add API access to complete the application. The APIs you need are Windows Azure Active Directory, which is automatically added when you create the application, and Microsoft Graph.

IMPORTANT  On June 30th 2022, we will be deprecating support for the Azure Active Directory Graph API. Please update your API permissions using the "App Registrations" page in Azure to reflect the information provided here.

  1. Click API permissions in the left-hand menu.
    IT_Glue_Integration_2020_-_Azure_Active_Directory_admin_center66_1.png

    IMPORTANT  You will see that Microsoft Graph has already assigned a default User.Read. permission. Click this permission and then Remove permission. Click Yes, remove to delete this permission.
    IT_Glue_Integration_2020_-_Azure_Active_Directory_admin_center77.png

  2. Once the default permission is removed, click the + Add a permission button.
    IT_Glue_Integration_2020_-_Azure_Active_Directory_admin_center66_2.png
  3. In the Request API permissions screen, click the Microsoft Graph button.
    Request_API_permissions_-_Azure_Active_Directory_admin_center111.png
    • Click Application permissions and complete the following actions for each of the subsections:
      1. Directory - Check the box beside Directory.ReadWrite.All.
      2. Reports - Check the box beside Reports.Read.All
      3. User - Check the box beside User.Read.All

      Request_API_permissions_-_Azure_Active_Directory_admin_center222.png
      Audit_Log.png
      DeviceManagement.png
      Directory.png

      Reports.png

      User.png

      NOTE  If you have configured this integration prior to May 25, 2022, review your API permissions to ensure they are up to date with this article.

      The following are the list of API permissions required for the integration:

      • AuditLog.Read.All
      • DeviceManagementManagedDevices.Read.All
      • Directory.Read.All
      • Directory.ReadWrite.All
      • Reports.Read.All
      • User.Read.All

        IMPORTANT  ReadWrite access to directory data is required to add the created Azure application to the AdminAgents security group. Without this permission, this can only be done directly with Microsofts API or PowerShell. As of Sep 2018, the Microsoft 365 UI only supports adding new users to groups and not the applications.

        IMPORTANT  Ensure that you add the corresponding delegated admin permission type as well for all application permission type as shown below.

        NOTE  In addition to these permissions, Microsoft Partner Center permission should also be added. (This can be found under APIs my organization uses).

  4. Save the changes by clicking Add permissions at the bottom of the screen.
  5. In the API permissions main screen, click the Grant admin consent for Company button.
    Screen_Shot_2022-01-31_at_4.50.05_PM.png
  6. In the confirmation pop-up, click Yes.
    IT_Glue_Integration_2020_-_Azure_Active_Directory_admin_center777.png

Once consent is granted, you will see a confirmation banner at the top of the screen and that all permissions in the Status column reflect the same.

IMPORTANT  To recap, please ensure that you select the Directory.ReadWrite.All permission for Microsoft Graph (step 4).

IMPORTANT  If you're updating your permissions for your existing Microsoft integration please follow the below steps on the IT Glue side:

  1. Go to the existing adapter in IT Glue under integrations > Edit Credentials.

  2. In the edit page, click on the Update button.

  3. You will be redirected to the Microsoft Login page, where you’ll login with the service account credentials (which you created in the section Create a service account user for GDAP).

  4. After logging into Microsoft, approve the permissions and then you’ll be redirected to IT Glue with a success message.

  5. The sync will return to an active state.

Integrating Microsoft with IT Glue

  1. In IT Glue, navigate to Admin > Integration and click the + New button. Then, click on the Microsoft button.

    Enter the information you copied from the Get Application ID & Tenant ID and Generate secret key sections of this KB article and click Connect.

  2. You will be redirected to the Microsoft login page, where you need to enter the service account credentials (which you created in the section Create a service account user for GDAP).

    NOTE  Once you login, you will be prompted to authorize the permissions and accept the permissions.

  3. After you enter your Microsoft login information in IT Glue, you'll be taken to the Sync your data Microsoft screen. Select the data you want to sync. By default, recommended options are listed first. Your options may look different than in the screenshot above.

NOTE  As a best practice, we recommend that you only select the user subscriptions that you actively manage. If you would like to see licenses, ensure the Licenses checkbox under Other is selected.

  1. Select the Enhance Contacts with Azure Active Directory checkbox under Azure Active Directory Sync to further enhance your IT Glue contacts with Azure information. This feature pulls in fields for Status, Last Logon, and Last Password Change.

NOTE  

  • This is a Network Glue only field. Your account must have the Network Glue add-on in order to use.
  • In order to obtain all available Azure AD fields, the Microsoft Graph (Read all audit log data) permission must be enabled in the Azure Active Directory application.
  • The Last Logon field will only appear when the user has logged on in the past 30 days.

  1. Click the Save and continue button. The sync will be automatically queued in the Active Integrations main screen.
  2. By default, newly queued syncs are scheduled to take place one hour later. Use the manual sync option to prioritize the sync to start sooner. Click Actions and then Start Manual Sync.

  3. From the Active Integrations screen, you can see the overall sync status. When the sync is complete, the Status column changes from Syncing... to OK.

NOTE  If you have a Microsoft Partner Network account with access to multiple tenants, disconnecting an Microsoft integration will not remove Admin privileges from your configured application. Remove these Admin privileges yourself or delete the configured application if no longer needed.

View synced contacts

IT Glue discovers tenants and users and tries to match them to your data in your account based on the following logic:

Rule Matches On
Organization Tenant name
Contact email address Username + "@" domain

If no organization can be matched automatically, suggestions will be made based on name similarity. If no suggestions can be made, you will have the option to create a new organization.

Tip! If you have two-way sync enabled in Kaseya BMS or Vorex PSA, all contacts created with your Microsoft integration can be automatically pushed to your PSA. For two-way sync instructions, review our Enable two-way sync topic or one of the applicable topics below:

  1. From Admin > Integrations, click on Actions and then Matching.

  2. Start with the Unmatched filter to review unmatched organizations.

  3. If you're happy with any suggested search, click Accept Suggestion to accept it, or, you can search for and choose a different organization using the Match To column. You can also choose to ignore organizations, which means they won't count as unmatched items in subsequent syncs.

    IMPORTANT  Warning. If you don't see an organization, click Actions > Create Organization to create (import) it. Make sure there is nothing to match first, so that you don't create a duplicate organization.

  4. Review all your unmatched organizations until they are all unmatched.
  5. If you change your mind about any of the matches, click Actions, choose Change Match, and then manually search for and choose a different organization.

    NOTE  Contact matching behaves slightly differently to standard matching logic. If no match can be made based on the criteria listed in the Prerequisites of this KB article, a new duplicate contact will be created without further user input.

  6. Once all organizations have been matched, you will need to start a new manual sync. Navigate to Account > Integration > Actions > Start Manual Sync. This second manual sync will sync all contacts and organizations in to IT Glue now that you've matched your organizations.
  7. When the sync is complete, click on any matched tenant to take you to the relevant organization. Then, click Contacts from the sidebar.

  8. Click on any contact that has corresponding data Microsoft and you will be able to see the additional data overlay as shown below.
  9. Continue onto the Office 365 License Integration topic.

Co-Pilot Smart Relate

Co-Pilot Smart Relate, the AI engine of IT Glue, automatically links related documentation, saving you the hassle. Through the Microsoft 365 integration, Co-Pilot automatically relates the Intune device (stored as an IT Glue Configuration) with the assigned Microsoft 365 user (IT Glue Contact).

Configuring Microsoft Entra ID Password Rotation

Configuring the password rotation to Microsoft Entra ID consists of the following two parts:

  • Assigning the necessary permissions

  • Assigning the necessary roles

NOTE  This is required for both the main tenant (the tenant within which the application was created and used for integration with IT Glue) and for other tenants.

IMPORTANT  The main tenant should always be the MSPs tenant that has the GDAP/DAP relationship with its downstream clients (side tenants).

Connecting the rotation for the main tenant

To rotate passwords in the Microsoft Entra ID, you need to add the following permissions for the tenant.

  • User.ManageIdentities.All

  • User.EnableDisableAccount.All

  • User.ReadWrite.All

  • Directory.ReadWrite.All

  • Directory.AccessAsUser.All

A list of these permissions is needed to perform a user update, and is listed by Microsoft in the documentation at the following link

https://learn.microsoft.com/en-us/graph/api/user-update?view=graph-rest-1.0&tabs=http

Assigning API permissions

  1. Open page https://entra.microsoft.com/#home.

  2. Expand the Application section in the menu on the left and click App registration.

  3. In the main window with a list of all applications, select by name the one that is used for Microsoft integration in IT Glue.

  4. Click API permission. A list of all permissions which the application already has is displayed. To add new permission, click + Add a permission.

  5. Select Microsoft Graph, and add all the permissions listed at the beginning and click Add permissions. The window from step 6 will open again.

  6. With newly added permissions, now you need to click on the button Grant Admin consent for <Tenant name>.

Now, all the necessary permissions for updating passwords will be added.

Adding roles

The application must have at least the User Administrator role to update passwords for regular users. The following are the roles that can be assigned:

  • User Administrator - to rotate only ordinary users (users who do not have a single role containing "Administrator" in the name)

  • Global Administrator - to rotate all admins including the global admin

To assign such a role to the application, the client will need to follow the link.

https://entra.microsoft.com/#view/Microsoft_AAD_IAM/RolesManagementMenuBlade/~/AllRoles?Microsoft_AAD_IAM_legacyAADRedirect=true

  1. Open page https://entra.microsoft.com/#home

  2. Click Show more in the menu on the left.

  3. Expand Roles & admins from the sections and click on the sub-section Roles & admins.

  4. Search for User Administrator role and click on it.

  5. Click Add Assignments.

  6. Enter the name of the application that is used for Microsoft integration in IT Glue and click Add.

NOTE  You may need to enter "Enter justification" where you need to enter the reasons why this role is given to the application, for example 'to allow it glue to rotate passwords inside the Entra'

To rotate administrator passwords, you need to add the Global Administrator role by repeating all the steps. But only in step 4 select Global Administrator role instead of User Administrator.

After completing these steps, the Microsoft integration in IT glue will have permissions and a role to rotate the passwords of ordinary users in the main tenant.

Connect among multi-tenants

To connect among multi-tenants, you have the following two connection options:

  • When several tenants are connected through the Microsoft admin center

  • When several tenants are available in Entra

When several tenants are connected through the Microsoft admin center:

  1. Open page https://admin.microsoft.com/Adminportal/Home#/homepage

  2. Choose All tenants in the menu on the left

  3. Select the tenant in which you want to enable rotation

  4. Click Show All in the menu on the left.

  5. If you have Admin Center section in the left menu,

    1. Click Endpoint Manager.

    2. Go through authentication in the window that appears - as a result, the Azure Intune window will open.

    3. Select the Tenant Administration section in the menu on the left.

    4. Choose Microsoft Entra Privileged Identity Management.

    5. Select Microsoft Entra roles.

    6. Select Roles in the Manage section.

    7. Repeat steps 4 to 6 from the main tenant section for each role (User Administrator and Global Administrator if you want to rotate admin users' passwords)

    8. In the added role window, the Assignment Licenses tab and in the list click on the uid of the integration.

      IMPORTANT  DO NOT click on the name, specifically on the uid

  6. If the Admin Center section does not appear, and if this tenant is not needed in the rotation, skip it and if needed to connect, complete the following steps:

    1. Expand the Billing section and select Licenses.

    2. In the list of licenses that opens, check whether there is a connected Microsoft 365 E5 Developer license (at least Microsoft 365 E5 Developer (without Windows and Audio Conferencing) or Microsoft Entra ID Governance or Microsoft Entra ID P2 - if at least one of them is available, go to step 6.6.

      NOTE  If you have a direct access to multi-tenants, you do not need any P1 or P2 Microsoft licenses.

    3. If there are no licenses from the previous point - select one of them from the list of all licensees. Go through all the steps to purchase it.

    4. After the purchase, select the Licenses subsection again and assign a new license to the selected user (any user from this tenant)

    5. Follow the direct link to go to Azure Intune - https://endpoint.microsoft.com/domain.com?ref=AdminCenter where instead of domain.com indicate the tenant's domain (Example: ITGlue.onmicrosoft.com)

    6. Go through the authentication in the window that appears which opens the Azure Intune window.

    7. Repeat steps 5.3-5.10 from point a) of this section (when there is an admin center) for each role.

When several tenants are available in Entra:

Adding permissions and roles follow the same scenario as for the main tenant, only with the few initial steps:

  1. Open page https://entra.microsoft.com/#home.

  2. Open section Identity > Overview in the menu on the left.

  3. Select Manage Tenants from the menu at the top.

  4. Select the desired tenant. The Entra window for the selected tenant will open, for which you need to repeat all the steps from the main tenant section (all steps starting from step 2) and then do all steps starting from step 2.

To synchronize the rotation between Entra and AD on instances where after rotating a password in one place, it is synchronized to another, the client must configure Microsoft Connect.

Link to all "Microsoft Connect" documentation -

whatis-azure-ad-connect-v2

Link with an example of setting up password synchronization -

tutorial-password-hash-sync

Link explaining how synchronization works -

how-to-connect-password-hash-synchronization

Add permissions and roles to multi-tenants in ‘onmicrosoft’ domain

Some clients might experience issues in getting the password rotation information for multi-tenants if they have ‘onmicrosoft’ domain. In such cases, to add permission and roles to each tenant, do the following steps:

To add permissions to multi-tenants in ‘onmicrosoft’ domain:

  1. For each tenant, create the following link:https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<app-id>

    where <tenant-id> is the ID for tenant for which you possibly wish to grant permission to rotate users' passwords and, <app-id> is the application ID for the integration.

  2. Login to your administrator account.

  3. Grant permissions to the tenant.

  4. Repeat steps 1 to 3 for each tenant for which you want to grant access for password rotation.

To add roles to multi-tenants:

  1. Login to Entra by accessing https://entra.microsoft.com/

  2. Click on the right corner on user icon or directory name:

  3. Click Switch Directory from the dropdown menu.

  4. Click Switch for the chosen client.

    If you could not find the tenant for which you want to add roles, then you will be available to find it from the Microsoft admin center:

    1. Login to https://admin.microsoft.com/

    2. Choose All tenants in the menu on the left.

    3. Select the tenant in which you want to add role.

  5. If you have Admin Center section in the left menu, Click Endpoint Manager.

    If not you need to create the URL https://endpoint.microsoft.com/<tenant-domain>?ref=AdminCenter where <tenant domain> is the full domain name of your tenant.

  6. In the Azure Intune window, click Tenant Administration.

  7. Click on Microsoft Entra Privileged Identity Management.

  8. Click on Microsoft Entra Roles.

  9. Click Roles.

  10. Type the role name as Global Administrator in search field and click on the role name in the list.

    NOTE  If you do not want to add the Global Administrator role and need to rotate only non-admin users in the tenant enter User Administrator role.


  11. Click Add Assignments.

  12. Click No member selected.

  13. In the Search field, type your integration name and click on the integration that appears in the list.

  14. Click on the Add button and provide your justification for adding the role for the integration (this is necessary as the other administrators can view the reason and would not delete it) and click Assign.

Add Global Admin roles to tenants using PowerShell

When configuring the Microsoft Integration to be able to rotate Entra ID passwords, there are some cases where you may not be able to add global admin roles to your tenants if you have not purchased P1 or P2 licenses. To address this issue, you can add global admin roles to tenants in Microsoft with the help of PowerShell.

  1. Install Azure AD PowerShell Module.Install the Azure Active Directory PowerShell module using the guide available on this link, if you haven't already.
    https://learn.microsoft.com/en-us/powershell/azure/active-directory/install-adv2?view=azureadps-2.0.

  2. Connect to Azure AD using the PowerShell. Connect to each tenant individually, run in PowerShell next command:
    Connect-AzureAD
    You will be prompted to enter your Global Admin credentials for each tenant.

  3. Find the Enterprise Application:
    Identify the Enterprise Application (service principal) that represents your integration in each tenant and run in the PowerShell next commands
    $appId = "<ApplicationId>" # Replace with the Application (Client) ID of your Enterprise Application. It can be found in Entra.

    1. Open the enterprise application.

    2. Find your application in the list and click on it. You will see the application ID as shown on the screenshot below:

      $enterpriseApp = Get-AzureADServicePrincipal -Filter "AppId eq '$appId'"

  4. Find Role ID:
    Run in PowerShell next commands:
    $roleName = "Global Administrator"
    $role = Get-AzureADDirectoryRole | Where-Object
    {$_.DisplayName -eq $roleName}

    If you want to assign a User Administrator Role, then run in PowerShell next commands:
    $roleName = "User Administrator"
    $role = Get-AzureADDirectoryRole | Where-Object
    {$_.DisplayName -eq $roleName}

  5. Assign role:
    Once you identify the service principal, you can assign the Global Admin role to it using PowerShell.
    Add-AzureADDirectoryRoleMember -ObjectId $role.ObjectId -RefObjectId $enterpriseApp.ObjectId
    '$role.ObjectId' is the Object ID of the Global Admin role in the tenant which you retrieved in point 3 (usually 62e90394-69f5-4237-9190-012177145e10 for Global Admin but it can be different).
    $enterpriseApp.ObjectId retrieves the Object ID of the service principal representing your integration.

  6. Repeat the steps for each tenant:
    Disconnect from the current tenant (if needed) and connect to the next tenant using Connect-AzureAD, then repeat step 3-5 for each tenant.
    To reconnect to a new tenant, use the following command:
    Connect-AzureAD -TenantId "tenantId"
    'tenantId' is the ID for the multi-tenant to which you want to add role. To find it you can go to link:
    https://endpoint.microsoft.com/<tenant-domain>?ref=AdminCenter

    NOTE  <tenant-domain> is the full domain of your tenant.

    On this page, click on the settings icon in the top right corner (near the notification icon). In the list you can see the Directory ID of your tenant. This is the 'tenantId'.