Find the symptom that matches what you're seeing, then follow the fix. For issues not covered here, contact Authenticx support with the relevant Entra provisioning log entries.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
401 Unauthorized | Invalid OAuth client, secret, scope, token endpoint, or organization scope. | Verify the Authenticx credentials, token endpoint, and acxapi scope. |
400 Bad Request on create | Required properties are missing. | Confirm userName, name.givenName, name.familyName, and email mapping. |
400 naming a hierarchy code or ID as unknown or inactive | A sent entry does not match an active Authenticx hierarchy. A suffix other than :View, :Edit, or :Manage is read as part of the code. | Correct the entry in the Entra source attribute, or reactivate the hierarchy in Authenticx. |
400 saying the integration assigns hierarchies by code or by ID | Entra sent the other hierarchy attribute. | Map the attribute the message names. |
| Hierarchy changes have no effect and users show no hierarchies | Hierarchy provisioning is not enabled for the integration. | Ask Authenticx to enable it, by code or by ID. |
| Hierarchy access level stays at View | The entry was sent without a level suffix, or the suffix is misspelled. | Send CODE:Edit or CODE:Manage. |
hierarchyCodes or hierarchyIds cannot be selected as a target attribute | The attribute was not added to the customappsso attribute list. | Add it as a multi-value String attribute. See Configuration Guide: Step 3. |
| Role not applied | Role value does not match an active Authenticx role. | Check the role register and confirm the value is an active role name or ID in the same Authenticx organization. |
| Multiple-role error | Entra sent multiple roles without exactly one primary role. | Configure Entra to send one role value to roles[primary eq true].value. |
| Entra log says role succeeded but Authenticx role did not change | Entra may have produced a malformed filtered-array PATCH payload. | Remove mappings to roles[primary eq true].primary and keep only roles[primary eq true].value. |
SchemaInvalid for roles[...] under Enterprise User | Role target was created under the wrong schema object. | Map roles under the core User object. |
invalidPath for authenticxRole under the agent extension | The agent extension was used for role assignment. | Map roles to SCIM core roles[primary eq true].value; use the agent extension only for agent-linking fields. |
| Agent-user manager not set | The manager is not assigned to the enterprise application, has not been provisioned yet, or is disabled in Authenticx. | Assign the manager to the application, provision them, and confirm they are active in Authenticx. Entra sets the manager on a later cycle. |
400 mentioning "did not match an active user" on a manager change | The manager is not provisioned to Authenticx or belongs to another Authenticx organization. | Provision the manager, or update the user's manager in Entra. |
| Agent-user manager cleared | The manager was disabled in Authenticx. An agent user is never kept on a disabled manager. | Assign an active manager in Entra. |
500 saying the user could not be synchronized to the tenant database | The user update was saved, but a follow-up write (tenant user, agent link, or hierarchy assignments) failed. | Entra retries failed exports on later cycles, and each retry re-applies every part of the change. If it keeps failing, use the user ID and the server error log to investigate. |
| Agent-user not created | enableAgentUser was missing, false, or mapped to the wrong target. | Map urn:authenticx:params:scim:schemas:extension:agent:2.0:User:enableAgentUser to boolean true for intended agent users. |
| User disabled unexpectedly | accountEnabled or scope-removal behavior is wrong. | Confirm accountEnabled maps to active as expected and review whether the user was removed from app assignment scope. |
| Timezone not updated | timezone is not mapped or the source value is empty. | Map an Entra attribute or expression containing an IANA timezone to the SCIM core timezone target attribute. |
| User has the default timezone unexpectedly | Entra did not send timezone, or the mapped source value was empty. | Map an Entra attribute or expression containing an IANA timezone to the SCIM core timezone target attribute. |
Group operations return 501 Not Implemented | Entra attempted to provision SCIM Group objects, which Authenticx does not support. | Disable Provision Microsoft Entra ID Groups under Provisioning > Mappings. Groups may still be assigned to the enterprise application to scope their member users. |
References
- Microsoft Entra SCIM provisioning guidance: https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups
- Microsoft Entra app provisioning overview: https://learn.microsoft.com/en-us/entra/identity/app-provisioning/user-provisioning
- Microsoft Entra attribute mapping customization: https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes
- SCIM core schema, RFC 7643: https://www.rfc-editor.org/info/rfc7643/
- SCIM protocol, RFC 7644: https://datatracker.ietf.org/doc/rfc7644
- Microsoft Entra expression reference (
Split): https://learn.microsoft.com/en-us/entra/identity/app-provisioning/functions-for-customizing-application-data - Authenticx SCIM behavior: Attribute Reference and Configuration Guide