Use this guide to find the cause of a provisioning problem. Each section points to a longer article.

Quick checks

  1. Token: click Test Connection. If it fails or says "not authorized", see OAuth Token Expired or Not Authorized Error: How to Fix.
  2. Mappings: userPrincipalName is mapped to userName. The externalId mapping is kept.
  3. One user: run Provision on demand for one user and read the result.
  4. Logs: open the Provisioning logs for the exact error (see How to Read Provisioning Logs and Find the Cause of an Error).
  5. Source data: check the value exists in Microsoft Entra ID.

1. Authorization failures (401, 403, "not authorized")

The OAuth token is expired, or the app was installed by a user who is not an Account Admin (or a user with admin privileges), or by an Occasional Agent. The token is valid for 365 days. The only way to get a new token is to uninstall and reinstall the app in Freshservice (Admin > Apps), then paste the new token in Enterprise applications > Freshservice Provisioning > Provisioning > Secret Token, click Test Connection and save. A 404 error on the endpoint after a Freshservice URL change is fixed the same way.

2. Attribute mapping failures

  • Make sure userPrincipalName is mapped to userName.
  • Custom fields must be added by hand with the name urn:ietf:params:scim:schemas:extension:freshservice:2.0:User:<field_name>. Get the exact name from Freshservice Admin > Apps > Azure Active Directory provisioning (SCIM) > Settings (case-sensitive, no angle brackets). Built-in names: Location is _location, secondary email is _secondaryEmail.
  • The field must exist in Freshservice first, and the type must match. Microsoft Entra ID always sends employee_id as a string, so that Freshservice field must be a text field.

See Mapping Custom Fields from Microsoft Entra ID to Freshservice and Mapping Errors: Find the Fix by Error Message.

3. Duplicate users and user matching

  • userPrincipalName must be mapped to userName, and userName must be the only matching attribute.
  • Keep the externalId mapping.
  • Do not remove the app in Microsoft Entra ID or unassign and reassign users. Use Provision on demand.
  • Delete duplicate users in Freshservice by hand.

See Duplicate Users After an Email Change: How to Fix and Duplicate Value and 409 Conflict Errors: How to Fix.

4. Manager not syncing

Add the attribute urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager with type Reference and reference object urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. Provision managers before their direct reports. See Fixing the Reporting Manager Mapping in Microsoft Entra ID.

5. Invalid values

  • Dropdown values must match the Freshservice list exactly, including capital letters.
  • Text longer than the field limit can be shortened with Left([attribute], 50).
  • Mandatory Freshservice fields need a value for every user.
  • Dates must be YYYY-MM-DD (see Date Fields: Limits When Syncing from Microsoft Entra ID).

See Invalid Field Values: Dropdown, Mandatory Field and Data Type Errors.

6. Users not in scope

Check Users and groups, the scope setting and the scope filters. See Sync All Users or Only Assigned Users and Not Effectively Entitled or Not Assigned.

7. Updates not arriving

Microsoft Entra ID sends the whole user, and Freshservice updates only fields that changed. RedundantExport is not an error. To force an update, make a small change to the user and run Provision on demand. See RedundantExport in Microsoft Entra ID: What It Means.

8. Deactivation

SCIM deactivates users and never deletes them. To stop deactivations, delete the active mapping. See How Deactivation Works, and How to Stop It.

9. Several tenants

Use the same endpoint URL and OAuth token in each tenant. See Using More Than One Microsoft Entra ID Tenant with One Freshservice Account.

Need help?

For complex problems or help reading logs, contact support at support@effy.co.in. Tell us your Freshservice URL and attach the mapping screenshot and the extended logs. Never send the OAuth token.