Setting Up Microsoft Entra ID User Provisioning with SCIM
Engage can connect with Microsoft Entra ID using the System for Cross-domain Identity Management (SCIM) standard. This allows authorised organisations to provision and maintain Engage employee users from Microsoft Entra ID.
Before you begin
- Contact Engage Support before beginning the configuration. SCIM must first be activated for your Engage company.
- You will require appropriate administration access in both Engage and Microsoft Entra ID.
- The SCIM token is a long-lived secret credential. Store it securely and never include it in screenshots, support-ticket descriptions or ordinary email.
- Confirm that the employee, branch and department codes used in Microsoft Entra ID match the corresponding records in Engage.
Quick steps
- Ask Engage Support to activate SCIM for your company.
- Generate the SCIM secret token from the company record in Engage.
- Create a non-gallery enterprise application in Microsoft Entra ID.
- Configure automatic provisioning using the Engage tenant URL and secret token.
- Apply the required attribute mappings.
- Test provisioning and review the SCIM logs in Engage.
Generate the Engage SCIM token
- In Engage, go to Customer Admin > Organisation > Companies.
- Open the relevant company.
- Select the SCIM User Provisioning tab.
- Select Generate Token.
The Engage tenant URL is:
https://portal.engagesolutions.app/scim
Copy the generated token directly into the secure Microsoft Entra ID provisioning configuration. Do not save it in an unsecured document or send it through ordinary email.
Configure Microsoft Entra ID
- In Microsoft Entra ID, go to Enterprise applications.
- Create a new application.
- Enter a suitable application name and select Integrate any other application you don't find in the gallery (Non-gallery).
- Open Provisioning and select Get started.
- Set the provisioning mode to Automatic.
- Enter the Engage tenant URL and the secret token generated in Engage.
- Configure the attribute mappings shown below.
Attribute mappings
The following mappings are supported. Your configuration may use the enterprise or custom employee-number schema shown for Employee ID.
| Engage field | Microsoft Entra ID attribute |
|---|---|
| Employee ID | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumberor urn:ietf:params:scim:schemas:extension:custom:2.0:User:employeeNumberPrimary matching field: set Matching precedence to 1 and remove matching precedence from other attributes. |
| Role and Job Title | title |
| First Name | name.givenName |
| Last Name | name.familyName |
| Preferred Name | name.formatted |
username | |
| Street Address | addresses[type eq "work"].streetAddress |
| City | addresses[type eq "work"].locality |
| State | addresses[type eq "work"].region |
| Postcode | addresses[type eq "work"].postalCode |
| Country | addresses[type eq "work"].country |
| Work Mobile | phoneNumbers[type eq "work"].value |
| Personal Mobile | phoneNumbers[type eq "mobile"].value |
| Joining Date | startDate |
| Branch ID | addresses[type eq "work"].formattedUse the branch code from Engage. |
| Department | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:departmentUse the department code from Engage. |
| Cost Centre | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter |
| Delivery Centre | deliverycenterId |
| Manager | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager |
| Employment Type | EmployeeType |
| Status | active |
Reviewing SCIM activity
Once provisioning is operating, authorised users can review the SCIM activity logs at:
https://portal.engagesolutions.app/employee/scim_logs
Engage retains SCIM GET requests for seven days. POST, PATCH and DELETE requests are retained for one month.
Troubleshooting
- Confirm that the Employee ID mapping is the primary matching field.
- Check that branch and department values use the corresponding Engage codes.
- Review the SCIM logs for the affected employee and request type.
- If the secret token may have been exposed, contact Engage Support so that access can be reviewed.
Need help? Contact support@engagesolutions.co.nz. Your email will create a support ticket that the Engage team can track and follow through.
