Configuration Guide

Complete these steps in order. Do not skip ahead — each step depends on the previous one succeeding.

📘

Before you start

Collect your SCIM credentials and confirm your Authenticx role list before beginning. See Overview & Prerequisites for the full checklist.

---

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 for Authenticx. If new, create a non-gallery application named Authenticx.
4. Open the application and select Provisioning.
5. Select New configuration if no active provisioning configuration exists.

🚧

Use a test application first

For initial validation, configure a separate test enterprise application. This limits provisioning scope and role-mapping impact until you have verified the end-to-end flow.

---

Step 2: Configure SCIM Admin Credentials

1. In Provisioning, set the provisioning mode to Automatic.
2. In Admin Credentials, enter the following:

Entra Field	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

3. If Entra only exposes Tenant URL and Secret Token (older UI), use a long-lived bearer token only if Authenticx has explicitly issued one for this integration.
4. Select Test Connection and do not continue until it succeeds.
5. Select Create or Save.

---

Step 3: Review the Authenticx SCIM Schema

1. Open Provisioning > Mappings.
2. Confirm a mapping exists for Provision Microsoft Entra ID Users.
3. If Entra has imported the SCIM schema, confirm the Authenticx agent extension appears as urn:authenticx:params:scim:schemas:extension:agent:2.0:User.
4. Confirm the role target is under the core User object, not the Enterprise User extension.

❗

Roles must use SCIM core

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

---

Step 4: Configure Standard User Attribute Mappings

Open Provisioning > Mappings > Provision Microsoft Entra ID Users and configure:

Entra Source	SCIM Target	Notes
userPrincipalName or mail	userName	Use the value recognized as the Authenticx login identifier.
objectId	externalId	Stable Entra identifier.
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.
accountEnabled	active	Confirm enabled maps to true and disabled to false.

Also add these constant mappings:

Constant	SCIM Target
true	emails[type eq "work"].primary
work	emails[type eq "work"].type
true	phoneNumbers[type eq "work"].primary
work	phoneNumbers[type eq "work"].type

For the full field reference, see Attribute Reference.

---

Step 5: Configure Role Provisioning

1. In Authenticx, identify the active role names or role IDs for this SCIM integration.
2. Maintain the role list in your Entra governance process. Update it whenever roles are added, renamed, deactivated, or retired in Authenticx.
3. Decide how Entra will produce the role value for each user:
   • App role assignment — when the enterprise application has app roles matching Authenticx roles.
   • Group-based assignment — when groups represent Authenticx access tiers.
   • Constant — only when every provisioned user should receive the same Authenticx role.
4. Map the selected role value to: roles[primary eq true].value
5. Do not add a separate mapping for roles[primary eq true].primary.
6. Test with one user before enabling a broader group.

🚧

Known Entra behavior

When Entra maps multiple sub-attributes under the same filtered array element, it can produce a malformed PATCH payload even when the provisioning log appears successful. Map only roles[primary eq true].value — do not add a mapping for roles[primary eq true].primary.

---

Step 6: Configure Agent-User Provisioning

Skip this step if none of your provisioned users need linked Authenticx agent-user records.

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

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

2. Map the source value:
   • Constant true — every assigned user becomes an Authenticx agent user.
   • An Entra attribute or expression — only some users become agent users.
   • Omit the mapping or map false — for standard Authenticx users only.
3. Do not map agentId. Authenticx returns that value after the agent-user record is linked.
4. 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 Authenticx agent users. Scope or map enableAgentUser from group or app assignment logic so agent-user creation is always intentional.

---

Step 7: Define Provisioning Scope

1. Open the enterprise application's Users and groups page and assign one pilot user first. Add groups only after the pilot user succeeds.
2. In Provisioning > Settings, set scope:
   • Sync only assigned users and groups — for a controlled rollout.
   • Sync all users and groups — only after a tested scoping filter and role strategy are in place.
3. Confirm each in-scope user has: first name, last name, email address, a resolvable Authenticx role value, and enableAgentUser == true only when agent-user creation is intended.

---

Step 8: Test with Provision on Demand

1. Open Provisioning > Provision on demand.
2. Select one test user and review the planned create or update action.
3. Run provisioning.
4. 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.
5. Validate the resulting user in Authenticx.

❗

Do not skip this step

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

---

Step 9: 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 end to end.

---

Step 10: Validate the SCIM Endpoint Outside Entra

Use this only when 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 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