Microsoft Entra SCIM Provisioning

Configure Microsoft Entra ID to create, update, disable, and maintain Authenticx users through the Authenticx SCIM 2.0 API.

📘

Before you start

Collect the SCIM credentials and confirm your active Authenticx roles.

Step 1: Create or Open the Enterprise Application

1. Sign in to the Microsoft Entra admin center.
2. Go to Entra ID > Enterprise apps.
3. Create or open the enterprise application used for Authenticx.
4. If this is a new custom integration, create a non-gallery enterprise application named Authenticx.
5. Open the application, then select Provisioning.
6. Select New configuration if Entra shows that provisioning has no active configuration.

🚧

Use a test application first

For initial validation, a separate test enterprise application limits provisioning scope and role-mapping impact. For production, use the existing application that controls Authenticx access only if that follows your tenant standard.

Step 2: Configure SCIM Admin Credentials

1. In Provisioning, set the provisioning mode to Automatic.

2. Under Admin Credentials, choose OAuth2 Client Credentials Grant as the authentication method. Set How credentials are sent to Body (client_secret_post).

3. Enter the Authenticx SCIM connection details.

   Entra field	Authenticx value
   Tenant URL	https://<api-host>/scim/v2
   Token Endpoint	https://<api-host>/connect/token
   Client Identifier	Authenticx OAuth client ID
   Client Secret	Authenticx OAuth client secret
   Scope	acxapi

4. If Entra only exposes Tenant URL and Secret Token, use a long-lived bearer token only if Authenticx has explicitly issued one for this integration.

5. Select Test Connection.

6. Do not continue until the connection test succeeds.

7. Select Create or Save to persist the provisioning configuration.

Step 3: Add the Authenticx Extension Attributes

Entra does not read the Authenticx schema from the SCIM endpoint, so the Authenticx extension attributes must be added to the target attribute list by hand before they can be mapped.

1. Open Provisioning > Mappings.

2. Confirm there is a mapping for Provision Microsoft Entra ID Users, and open it.

3. Select Show advanced options > Edit attribute list for customappsso.

4. Add the attributes you plan to use:

   Name	Type	Multi-Value
   urn:authenticx:params:scim:schemas:extension:agent:2.0:User:enableAgentUser	Boolean	No

   Add urn:authenticx:params:scim:schemas:extension:agent:2.0:User:managerId (String) only if you will use it instead of the Enterprise manager.

5. Save the attribute list.

6. Confirm urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager is already in the list. Entra includes it by default. Authenticx supports only the Enterprise User manager attribute. See Manager Mapping.

7. Confirm the role target is under the core User object, not the Enterprise User extension.

❗

Roles must use SCIM core

Map roles to the SCIM core roles attribute. Do not create a custom field such as authenticxRole under the agent extension.

Step 4: Configure Standard User Attribute Mappings

Open Provisioning > Mappings > Provision Microsoft Entra ID Users.

Configure these recommended mappings:

Entra source attribute	SCIM target attribute	Notes
userPrincipalName or mail	userName	Use the value users and admins recognize as the Authenticx login identifier.
objectId	externalId	Stable Entra identifier controlled by the provisioning client.
givenName	name.givenName	Required to create an Authenticx user.
surname	name.familyName	Required to create an Authenticx user.
mail	emails[type eq "work"].value	Required to create an Authenticx user.
telephoneNumber or mobile	phoneNumbers[type eq "work"].value	Optional.
Entra attribute or expression containing an IANA timezone	timezone	Recommended when Entra should manage Authenticx user timezones. If omitted, Authenticx defaults to America/Indianapolis.
accountEnabled	active	Confirm this maps enabled users to true and disabled users to false.

Recommended constants:

Constant value	SCIM target attribute
true	emails[type eq "work"].primary
work	emails[type eq "work"].type
true	phoneNumbers[type eq "work"].primary
work	phoneNumbers[type eq "work"].type

Do not map displayName as an authoritative inbound value. Authenticx derives display name from name.givenName and name.familyName.

Entra's default mappings also include standard attributes Authenticx doesn't store, such as title, preferredLanguage, name.formatted, addresses, and the Enterprise User department and employeeNumber. Authenticx accepts and ignores them, so you can leave them in place or remove them.

Timezone Mapping

Microsoft Entra provisioning supports mapping Entra attributes and expressions to target SCIM attributes. To provision user time zones into Authenticx, add or confirm a mapping to the core SCIM target attribute:

Text

timezone

The source value must be an IANA timezone string, for example:

• America/New_York
• America/Chicago
• America/Denver
• America/Phoenix
• America/Los_Angeles
• America/Indianapolis
• Pacific/Honolulu
• UTC

Authenticx stores the mapped value as the user's TimeZone. If timezone is not mapped or not sent by Entra, Authenticx defaults newly created users and full SCIM PUT replacements to America/Indianapolis. PATCH operations preserve the existing timezone when the attribute is omitted. If a PATCH explicitly clears timezone, Authenticx reapplies the same default because users without a timezone cannot sign in.

Step 5: Configure Role Provisioning

Authenticx users hold exactly one active role. Entra can send SCIM roles as a multi-valued attribute, but Authenticx resolves it to one role.

1. In Authenticx, identify the active role names or role IDs that are allowed for this SCIM integration.

2. Maintain that role list in the Entra enterprise application governance process. Update it whenever roles are added, renamed, deactivated, or retired in Authenticx.

3. Decide how Entra will choose the role for each user:

   • Use an expression mapping for app role assignments. Do not map appRoleAssignments directly; the result must be one active Authenticx role name or ID.
   • Use an expression based on a directory attribute when groups represent Authenticx access tiers. Verify the output for each pilot user.
   • Use a constant only when every provisioned user should receive the same Authenticx role.

4. Map the selected role value to:

   Text

   roles[primary eq true].value

5. Do not add a separate mapping for:

   Text

   roles[primary eq true].primary

6. Test with one user before enabling a broader group.

If you use Entra app roles, follow Microsoft's SingleAppRoleAssignment guidance. It requires Sync only assigned users and groups; do not choose Sync all users and groups for that mapping. Verify the actual role value in both create and update provisioning logs.

Role value rules:

• The value must match an active Authenticx role name, case-insensitively, or a valid Authenticx role ID.
• If the roles attribute is omitted, Authenticx leaves the user's existing role unchanged.
• If roles is sent as an empty array, Authenticx removes the user's role.
• If multiple roles are sent, exactly one must be primary. The preferred Entra setup is to send one role value.

🚧

Known Entra behavior

Mapping multiple sub-attributes under the same filtered array element can produce a malformed PATCH even when the provisioning log appears successful. Map only roles[primary eq true].value; Authenticx applies the role as primary.

Step 6: Configure Agent-User Provisioning

Use this only for users who should have linked Authenticx agent-user records.

1. In the user mapping, add or confirm this target attribute:

   Text

   urn:authenticx:params:scim:schemas:extension:agent:2.0:User:enableAgentUser

2. Map the source value:

   • Use constant true if every assigned user should become an Authenticx agent user.
   • Use an Entra attribute or expression if only some users should become agent users.
   • Omit the mapping, or map false, for users who should only be standard Authenticx users.

3. Keep the Entra manager mapping so agent users get their manager automatically. See Manager Mapping.

4. Do not map agentId. Authenticx returns that value after the agent-user record is linked.

5. Test a single agent user with Provision on demand and confirm Authenticx returns an agentId.

📘

Recommended pattern

Create separate Entra groups for standard Authenticx users and agent users. Scope or map enableAgentUser from group or app assignment logic so agent-user creation is intentional.

Manager Mapping

Authenticx reads the agent-user's manager from the standard SCIM Enterprise User manager attribute, so the manager relationship already maintained in Entra flows through without Authenticx IDs being copied into Entra.

Entra source attribute	SCIM target attribute
manager	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager

Entra includes this mapping by default for custom SCIM applications. If it was removed, add it back with mapping type Direct.

How it works:

• manager is a reference attribute. Entra does not send the manager's Entra object ID; it looks up the manager's account that this enterprise application already provisioned to Authenticx and sends that account's Authenticx user ID.
• The manager must be assigned to the Authenticx enterprise application and provisioned before Entra can send them as a manager. Assign managers to the application along with their reports. If a manager is provisioned after a report, Entra sets the manager on a later provisioning cycle.
• A manager must be an active Authenticx user in the same organization. Managers do not need to be agent users themselves.
• An agent user is never kept on a disabled manager. When a manager is disabled in Authenticx, including through provisioning, they are removed as manager from their agent users. If Entra still sends a disabled manager, Authenticx clears the agent user's manager and applies the rest of the update.
• Authenticx stores the manager on the user's linked agent-user record. For users that are not agent users, Authenticx accepts and ignores the manager, so the mapping is safe to keep for all users.
• Clearing a user's manager in Entra clears it in Authenticx.
• If urn:authenticx:params:scim:schemas:extension:agent:2.0:User:managerId is also mapped, it takes precedence over manager. Map only one of the two.

Step 7: Review Hierarchy Access

Authenticx supports hierarchy assignments through its SCIM API, but a non-gallery Entra app cannot configure the required custom multi-value extension attributes. Leave hierarchyCodes and hierarchyIds unmapped. Existing Authenticx hierarchy access is preserved when these attributes are omitted. Contact Authenticx if Entra must manage hierarchy access for your organization. See Microsoft's custom attribute limitation.

Step 8: Define Provisioning Scope

Disable the Provision Microsoft Entra ID Groups object mapping under Provisioning > Mappings. Authenticx SCIM does not support /Groups; all group operations return 501. You can still assign an Entra group to the enterprise application to bring its member users into scope. Assign Authenticx roles through the user roles mapping.

1. Open the enterprise application's Users and groups page.
2. Assign one pilot user first.
3. Assign groups only after the pilot user succeeds.
4. In Provisioning > Settings, set Scope to the intended population:
   • Sync only assigned users and groups for controlled rollout.
   • Sync all users and groups only if your tenant has a tested scoping filter and role strategy that does not use Entra app-role expressions.
5. Confirm each in-scope user has:
   • First name.
   • Last name.
   • Email address.
   • A resolvable Authenticx role value.
   • enableAgentUser == true only when agent-user creation is intended.

Step 9: Test with Provision on Demand

1. Open Provisioning.
2. Select Provision on demand.
3. Select one test user.
4. Review the planned create or update action.
5. Run provisioning.
6. Open Provisioning logs and confirm:
   • The user was created or updated.
   • active has the expected value.
   • The role attribute was sent with the expected Authenticx role.
   • enableAgentUser was sent only when intended.
7. Validate the resulting user in Authenticx.

❗

Validate before automatic provisioning

Do not enable broad automatic provisioning until on-demand provisioning succeeds for at least one standard user and, if applicable, one agent user.

Step 10: Start Automatic Provisioning

1. Open Provisioning.
2. Set Provisioning Status to On.
3. Enter a notification email address for provisioning failures.
4. Save the configuration.
5. Monitor the initial cycle from the provisioning overview and provisioning logs.
6. Keep the pilot group small until create, update, disable, and role-change scenarios are verified.

Step 11: Validate the SCIM Endpoint Outside Entra

Use this only if you need to isolate Entra configuration from Authenticx API connectivity.

Request an access token:

Bash

curl -X POST "https://<api-host>/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<client-id>" \
  -d "client_secret=<client-secret>" \
  -d "scope=acxapi"

Call the SCIM service provider configuration:

Bash

curl "https://<api-host>/scim/v2/ServiceProviderConfig" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/scim+json"

Expected capabilities:

Capability	Expected value
patch.supported	true
filter.supported	true
sort.supported	true
bulk.supported	false
authenticationSchemes[0].type	oauth2