Introduction

The BMS integration with Azure Active Directory enables contacts and users to be automatically created and synced based on the users that are defined in one or more Active Directory tenants. Primary integration is with Azure AD, but it can be used with on-premises Active Directory via Azure AD Connect. Additionally, Active Directory records will propagate to IT Glue if that integration is enabled.

Azure AD to BMS Mapping Overview

• Mapping of users from Active Directory to BMS is based on Security Group. If a user belongs to more than one Security Group, the order value determines which record has precedence. The lowest order value has precedence. If two groups have the same order value, the oldest group has precedence. 
• BMS will match Active Directory records to existing records based on email address. Where the email address in the AD record is found in BMS, those records will be merged. Where the email address is not found, a new record will be created in BMS. The record identifier for contacts created locally in BMS is not changed. Therefore, no linkages to tickets or other record types are affected. 
• After initial sync, any updates to records in Active Directory will automatically be pushed to BMS. It takes up to three minutes for changes in Active Directory to be synced to BMS. 
• Any changes to synced record in BMS will persist until the record is changed in Active Directory, at which point the local changes will be overwritten. 
• Deleted records in Active Directory will be deactivated in BMS, but not deleted.
• The table below indicates the field mapping between Active Directory and BMS. When any field in the AD user record is updated, whether mapped or not, AD sends a notification to BMS to update the record. However, only the fields listed below are consumed.

Azure AD Setup 

Kaseya BMS accesses the user records in your Azure AD tenant via the Microsoft Graph API. In order to do this, BMS must be authenticated and authorized by the Microsoft Identity Platform using the OAuth 2.0 standard.

Tips

• Your Active directory is always the source of truth. If you have a user user@mymsp.com as part of PSA's HR > Employees, and if your AD has this mapped as a client portal user, AD will sync existing employee as a client portal user in PSA.
• The user will be archived from HR and a new entry for the client portal will be created in CRM. The archived user will have user_Archived in their username and user@mymsp.com_Archived in the email address.
• As both these user types are part of HR, one of them will have to be archived and the sync archives the one in employees as the mapping rules set is for the client portal. 
• The system cannot have two different logins for one user. This will trigger an archive on the user part of the employee. PSA then creates another user and makes it a client portal user.
• If this was accidental, this has to be fixed in the AD. Make any false change to the user, like edit in the last name, job title, etc. so that the AD can push this change to PSA in real-time.  
• If the archived user had relational data, like tickets or invoices, the user cannot be renamed or deleted from the database.

For Azure child tenants, the setup will work if the parent tenant has access to the child tenants, where the admin can add users from child Tenants to the Users and Groups Permissions of the Enterprise Application on his parent tenant. 

Step 1: BMS Registration 

In this part of the setup, you will register BMS with your Azure AD tenant. For background, see the this section of the Microsoft Identity Platform documentation.

1. Navigate to your Azure AD tenant. 
2. Note your tenant domain name, you will this need later. ()

   The domain name is found as Current directory in your Microsoft directory subscription details. If you do not have a fully qualified domain name and are using the Microsoft sub-domain it would be yoursubdomain.onmicrosoft.com. Refer How to Find My Azure AD Tenant Name

3. Under Manage, click App Registration. 
4. Click +New Registration.
5. Name the application, e.g., Kaseya BMS.
6. Under Supported Account Types, make BMS multi-tenant. You can select either option beginning with Accounts in any organizational directory...
7. Enter the following Redirect URI :  https://<server-base-url>/OAuth/IntegrationCallback.aspx
   
   1. US server: https://bms.kaseya.com/OAuth/IntegrationCallback.aspx
   2. UK server: https://bmsemea.kaseya.com/OAuth/IntegrationCallback.aspx
   3. APAC server: https://bmsapac.kaseya.com/OAuth/IntegrationCallback.aspx
   4. Vorex: https://www.vorexlogin.com/OAuth/IntegrationCallback.aspx
8. On the Application Overview page, note the Application ID.

Step 2: BMS Permissions

In this part of the setup, you will grant BMS permissions to access the Microsoft Graph API as the signed in BMS user. For background, see this section of the Microsoft Identity Platform documentation. 

1. Navigate to App Registrations, and select your app, e.g., Kaseya BMS.
2. Under Manage, select API Permissions. 
3. Under Configured Permissions, select Add a Permission.
4. From the right side panel, select Microsoft Graph API. 
5. Select Delegated Permissions. For background on permission types, see this section of the Microsoft Identity Platform documentation. 
6. Select the following permissions, and then click Add Permissions.
   • Directory.Read.All 
   • Group.Read.All 
   • User.Read 
   • User.Read.All 
7. Click Grant Admin Consent…, and accept. For background on this button, see this section of the Azure AD documentation.

Step 3: BMS Credentials 

BMS needs its own credentials in order to be able to authenticate itself to the Microsoft Identity Platform. In this part of the setup, you will generate a client ID and secret key for BMS. For background, see this section of the Microsoft Identity Platform documentation. 

1. Begin from the last screen of the previous section. 
2. Under Manage, click Certificates & Secrets.
3. Click +New Client Secret.
4. Complete the form that pops up. 
5. Copy the secret key to a notepad for use in the next section. This section gets hashed out once saved. Do not skip copying the values.
   • The data in the Value column should be copied.

Step 4: BMS Setup 

Employee Defaults 

In this part of the setup, you will set the mapping rules for employee records. Every employee record in BMS has certain mandatory fields. If this field is not set in the Active Directory record you must decide what value the field should default to. 

1. Navigate to Admin > My Company > Auth & Provision.
2. At the bottom of the page, select the Azure AD Sync radio button.
3. Complete the Employee Defaults section.
4. Click Save. 

 Azure AD Connection 

In this part of the setup, you will plug in details of your Azure AD configuration into BMS. From Azure, you will need the following: 

• Tenant Domain Name 
• Application ID for BMS 
• Client Secret for BMS 

1. Click Add under the Azure AD Connections tab.
2. Enter the Tenant Domain Name, Application ID, and Application Key from your Azure AD configuration.
   • The directory name is your tenant name or the ID, both of them work for this initial connection. Mapping rules however need only the ID. 
   • Application ID 
   • Application Key (BMS) = Secret Value 
3. Click on Azure Connect and authenticate using OAuth. 
   • If you see the permission required window, Check the Consent on behalf of your organization box and Accept. 

The Azure AD Sync system will auto-reconnect after certain amount of failures after a period of 120 seconds.

Mapping Rules 

In this part of the setup, you will specify the groups you want to sync between BMS and Azure AD. From Azure, you will need: 

• Tenant Domain Name 
• Group Object ID 

1. In Azure, navigate to your Active Directory tenant, and under Manage, click Groups.
2. Copy the Group Object ID for the groups you want to sync to BMS.
3. In BMS, click Add under the Mapping Rules tab.
4. Complete the pop-up form, and click Save.
5. Go to the Azure AD Connections tab and click Sync.
6. You can now navigate to CRM > Contacts or HR > Employees to view synced records.