Skip to main content
All CollectionsPulseway PSAGeneral
Microsoft Entra ID integration
Microsoft Entra ID integration
O
Written by Oliver Anthony
Updated over 5 months ago

Azure AD is now Microsoft Entra ID. Microsoft has renamed Azure AD as Microsoft Entra ID. However, this does not lead to a disruption in your deployment, configuration or integration. They will continue to function as they did previously.

The PSA integration with Microsoft Entra ID 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 Microsoft Entra ID, but it can be used with on-premise Active Directory via Microsoft Entra Connect. Additionally, Active Directory records will propagate to IT Glue if that integration is enabled.
​

Microsoft Entra ID to PSA Mapping Overview

  • Mapping of users from Active Directory to PSA 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.

  • PSA will match Active Directory records to existing records based on email address. If the email address in the AD record is found in PSA, that record will be merged. If the email address is not found, a new record will be created in PSA. The record identifier for contacts created locally in PSA does not change. 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 PSA. It takes up to three minutes for changes in Active Directory to be synced with PSA.

  • Any changes to a synced record in PSA 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 PSA, but not deleted.

  • The table below indicates the field mapping between Active Directory and PSA. When a field in the AD user record is updated, whether mapped or not, AD sends a notification to PSA to update the record. However, only the fields listed below are consumed.
    ​fields listed below are consumed.
    ​

NOTE : When you enable AD sync, username in PSA will be without the @domainname.

Microsoft Entra ID Setup

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

IMPORTANT Please review the tips below before you proceed with your actions. The Microsoft Entra ID integration works only with P1 and P0 licenses. It does not work with the free version.

Tips

  • Your Active Directory is always the source of truth. If you have a user user@mymsp.com as part of PSA 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 are 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 editing 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 Microsoft Entra 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 the parent tenant.

Step 1: PSA Registration

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

  1. Navigate to your Microsoft Entra tenant.

  2. Note your tenant domain name. You will need this 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 Microsoft Entra Tenant Name

3. Under Manage, click App Registration.

4. Click +New Registration.

5. Name the application, e.g., Pulseway PSA.

6. Under Supported Account Types, make PSA multi-tenant. You can select 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://psa.pulseway.com/OAuth/IntegrationCallback.aspx

8. On the Application Overview page, note the Application ID.

Step 2: PSA Permissions

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

  1. Navigate to App Registrations, and select your app, e.g., Pulseway PSA.

  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 Microsoft Entra ID documentation.

Step 3: PSA Credentials

PSA needs its own credentials in order to authenticate itself with the Microsoft Identity Platform. In this part of the setup, you will generate a client ID and secret key for PSA. 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: PSA Setup

Employee Defaults

In this part of the setup, you will set the mapping rules for employee records. Every employee record in PSA 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 Microsoft Entra ID Sync radio button.

  3. Complete the Employee Defaults section.

  4. Click Save.

Microsoft Entra Connection

In this part of the setup, you will plug in details of your Microsoft Entra ID configuration into PSA. From Microsoft Entra, you will need the following:

  1. Click Add under the Microsoft Entra Connections tab.

  2. Enter the Tenant Domain Name, Application ID, and Application Key from your Microsoft Entra ID 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 (PSA) = Secret Value

3. Click Microsoft Entra Connect and authenticate using OAuth.

  • If you see the permission required window, check the Consent on behalf of your organization box and Accept.

The Microsoft Entra ID sync system will auto-reconnect after certain amount of failures after a period of 120 seconds.

Mapping Rules

ALERT: Once mapping rules are set and sync is initiated, PSA users will be associated with the new security group coming from the AD. Existing user access will be overridden with what is specified in the AD. Mapping rules should be set correctly as this controls the login access and module permissions for the synced users. Any synced user with no rules would have no access to PSA. The root user is exempted from access revoke when this happens.

In this part of the setup, you will specify the groups you want to sync between PSA and Microsoft Entra ID. From Microsoft Entra, you will need:

  • Tenant Domain Name

  • Group Object ID

  1. In Microsoft Entra, navigate to your Active Directory tenant, and under Manage, click Groups.

  2. Copy the Group Object ID for the groups you want to sync with PSA.

  3. In PSA, click Add under the Mapping Rules tab.

  4. Complete the pop-up form, and click Save.

  5. Go to the Microsoft Entra Connections tab and click Sync.

  6. You can now navigate to CRM > Contacts or HR > Employees to view synced records.

Did this answer your question?