The PSA 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.

· 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. Where the email address in the AD record is found in PSA, those records will be merged. Where the email address is not found, a new record will be created in PSA. The record identifier for contacts created locally in PSA 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 PSA. It takes up to 3 minutes for changes in Active Directory to be synced to PSA.

· Any changes to synced record in PSA will persist until the record is changed in Active Directory, at which point the local changes will be overwritten.

· Records 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 any 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.

Field Mapping Table

Note: When you enable AD Sync, username in PSA will be without the @domainname

Pulseway PSA accesses the user records in your Azure AD 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.

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

In this part of the setup, you will register PSA with your Azure AD tenant. For background, see 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.

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 either option beginning with Accounts in any organizational directory.

7. Enter the Redirect URL in the following format: https://<server-base-url>/OAuth/IntegrationCallback.aspx
For your Pulseway domain: https://psa.pulseway.com/OAuth/IntegrationCallback.aspx

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

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 Azure AD documentation.

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

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 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 PSA. From Azure, you will need the following:

· Tenant Domain Name

· Application ID for PSA

· Client Secret for PSA
​

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 (PSA) = 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.

Mapping Rules

Warning: 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 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 PSA.

3. In PSA, 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.