SCIM Provisioning with Azure Entra ID

Introduction

If you use Microsoft's Azure Entra ID to manage your employee's accounts across your organization, you can set up PerformYard to automatically provision employees with Entra. Please keep in mind that you must be an Admin or Billing Admin and have the ability to set up new provisioning connections in Azure Entra ID in order to correctly set up this integration

Note: When configuring your Entra ID system and considering how it will provision users in PerformYard, please be aware that Entra ID cannot send null fields to PerformYard. This would mean that if an employee data field was to have its value removed in the source system, Entra ID would not sync that removal to PerformYard. 

For example, if an employee synced to PerformYard via Entra ID was to have their manager removed in Entra ID, that manager would still be assigned to the employee in PerformYard since Entra cannot send PerformYard the now empty Manager field.

Data Managed by Entra ID

The following data about an employee is managed by Entra ID and will subsequently be locked from being managed by other systems or in the PerformYard interface:

  • First Name
  • Last Name
  • Email
  • Job Title
  • Nickname
  • Manager
  • Employee Status

Handling Unique Behavior for Entra ID and PerformYard

Microsoft Entra ID operates differently from PerformYard, particularly in how and when it updates data such as an employee's manager, changes to deactivated employees, and the transmission of updates to PerformYard when employee data is modified. To ensure Entra ID remains the authoritative source for employee information, it's important to be aware of situations where Entra ID may handle data in ways that are not ideal for PerformYard.

Please refer to our Entra ID Troubleshooting document for details on how to handle those scenarios and possible remedies to ensure your data in PerformYard is as active as possible.

Interaction with other Integrations

Please note that our Entra integration can coexist with your SFTP or manual actions like CSV uploads. However, there is a risk of account de-syncing or employee information becoming out of sync if attempts are made to sync employee data from both systems at the same time. It is recommended that Entra be used as the system of record for creating or removing employees and managing the data mentioned above, but other update options like CSV uploads or SFTP uploads only be used to change employee attributes that are not managed by SCIM.

Using the PerformYard API to update employee information can also conflict with SCIM identity management. If you attempt to change employee information that is already managed by SCIM, you will receive an error message indicating that the field is locked by your identity management system.

In a similar manner, using our CSV upload or SFTP to manage employee information will not update employees managed by your SCIM identity management system.

Configuring PerformYard

Customers need two things to communicate with Azure Entra ID:

  1. The base URL of our SCIM API
  2. A bearer token for authentication

To create these two items, you will first need to find and select the SCIM setup option in your Administration page.

Then, select Add SCIM Integration to be taken to the following screen that gives you both the base URL of the SCIM API and a token, which will be copied and pasted into the appropriate area in your Entra ID provisioning setup screen.

Keep this ID available for the next step in setting up your integration.

Configuring Azure Entra ID

In order to connect PerformYard to your Entra ID provisioning system, you first need to add PerformYard as a custom, non-gallery application.

  1. Sign in to the Microsoft Entra admin center
  2. Browse to Identity > Applications > Enterprise applications
  3. Select New Application
  4. Select Create Your Own Application, Type a unique name for the application, choose integrate any other application you don't find in the gallery, and click Create. You should be taken to the application management screen at this point. If you weren't, you can go back the the Enterprise Applications tab and choose your application from the list
  5. Click on the Provisioning tab in the left panel
  6. Click the Provisioning tab under the Manage section. You'll want to update your Admin Credentials with the SCIM base URL from PerformYard and the SCIM token you've created. Click on Test Connection after you enter those values to confirm the credentials are correct.
  7. After successfully testing your connection, save your Provisioning settings.
  8. Under the Mappings section that now appears beneath the Admin Credentials section, click on the Provision Azure Active Directory Users option.
  9. Ensure the User Provisioning is enabled and Target Object Actions are set for Create, Update, and Delete. Click to Save.
  10. Back on the Properties tab. Ensure that the "Assignment Required?" field is set to "Yes". This is recommended as it's a more intentional approach to provisioning rather than syncing all users.
  11. Toggle the Provisioning Status to On and click Save. The Scope option of the Provisioning settings can be used to determine if only users specifically assigned to the PerformYard application should be created, or if all users in the Entra platform should be created in PerformYard. It is recommended to at least start with the "Sync only assigned users and groups" option to validate that the integration is working as intended.
  12. Click on the Users and Groups tab under the Manager section to add/remove users. Any user added here will be synced regularly according to your company's Entra provisioning schedule.
  13. After a user is synced and added to PerformYard, their First Name, Last Name, Email, and Status as an active user will then be managed via Entra ID.

Aligning Optional Fields to PerformYard from Entra ID

Some fields are not required to provision or update a new user, but are still available to use as attributes for a user in PerformYard that would be managed by Entra ID. At the moment, the following fields can also be managed by Entra ID for your PerformYard users:

  • Nickname - Corresponds to the nickName field in the SCIM framework
  • Job Title - Corresponds to the title field in the SCIM framework

Additional Information

  • Users created via provisioning with Entra are automatically assigned a role of Employee and will be in the Not Invited/Not Signed In State.
  • Please keep in mind that, if a user is removed from the PerformYard app user provisioning list in Entra, that user will subsequently be deactivated in PerformYard during the next sync with Entra. If a user is mistakenly removed from PerformYard via Entra, simply re-enable the user in Entra for the PerformYard app and that user should subsequently be re-enabled after Entra syncs with PerformYard.

Additional References