API Reference

Configuration Guide

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

📘

Before you start

Collect the SCIM credentials and confirm your active Authenticx roles. Ask Authenticx to enable hierarchy provisioning for this integration if Entra will manage hierarchy access.

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. In Admin Credentials, enter the Authenticx SCIM connection details.

    Entra fieldAuthenticx value
    Tenant URLhttps://<api-host>/scim/v2
    Token Endpointhttps://<api-host>/connect/token
    Client IdentifierAuthenticx OAuth client ID
    Client SecretAuthenticx OAuth client secret
    Scopeacxapi

  3. 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.

  4. Select Test Connection.

  5. Do not continue until the connection test succeeds.

  6. 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:

    NameTypeMulti-Value
    urn:authenticx:params:scim:schemas:extension:agent:2.0:User:enableAgentUserBooleanNo
    urn:authenticx:params:scim:schemas:extension:hierarchy:2.0:User:hierarchyCodes or …:hierarchyIds, whichever Authenticx enabledStringYes

    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 attributeSCIM target attributeNotes
userPrincipalName or mailuserNameUse the value users and admins recognize as the Authenticx login identifier.
objectIdexternalIdStable Entra identifier controlled by the provisioning client.
givenNamename.givenNameRequired to create an Authenticx user.
surnamename.familyNameRequired to create an Authenticx user.
mailemails[type eq "work"].valueRequired to create an Authenticx user.
telephoneNumber or mobilephoneNumbers[type eq "work"].valueOptional.
Entra attribute or expression containing an IANA timezonetimezoneRecommended when Entra should manage Authenticx user timezones. If omitted, Authenticx defaults to America/Indianapolis.
accountEnabledactiveConfirm this maps enabled users to true and disabled users to false.

Recommended constants:

Constant valueSCIM target attribute
trueemails[type eq "work"].primary
workemails[type eq "work"].type
truephoneNumbers[type eq "work"].primary
workphoneNumbers[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:

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 app role assignment when the enterprise application has app roles that match Authenticx roles.
    • Use group-based assignment when groups represent Authenticx access tiers.
    • Use a 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.

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:

    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 attributeSCIM target attribute
managerurn: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: Configure Hierarchy Provisioning

Use this only if Entra should manage which Authenticx hierarchies users can access.

  1. Ask Authenticx to enable hierarchy provisioning for this integration, by code or by ID. The choice sets the target attribute: hierarchyCodes for codes, hierarchyIds for IDs.

  2. Choose an Entra source that holds each user's codes or IDs as one comma-separated value, for example a directory extension attribute or extensionAttribute1-extensionAttribute15. Write each entry alone for View, or followed by :Edit or :Manage:

    SVC-1001,SVC-2002:Edit,REGION-EAST:Manage

  3. In the user mapping, add a mapping with mapping type Expression:

    Split([extensionAttribute1], ",")

    Target attribute: urn:authenticx:params:scim:schemas:extension:hierarchy:2.0:User:hierarchyCodes, or …:hierarchyIds for IDs.

  4. Test one user with Provision on demand and confirm the user has the expected hierarchies and levels in Authenticx.

How it works:

  • An unknown or inactive code or ID rejects the whole update with 400, except an update that disables the user: that always disables them, and its hierarchy and manager changes are skipped if they can't be applied. If two entries reach the same hierarchy, the higher access level wins.
  • Entra sends only the entries that changed, so Authenticx adds or removes just those. Changing SVC-1001 to SVC-1001:Edit changes that hierarchy's level and leaves other hierarchy access alone.
  • On the hierarchies an entry reaches, Entra is the authority. Removing an entry in Entra removes the user's access to those hierarchies, including access granted directly in Authenticx.
  • Authenticx returns the attribute on every user it reports, including filter queries, in the form you send: each entry once, sorted, with no suffix for View. Send Edit and Manage with that casing and IDs in lowercase so Entra sees no difference.
  • A hierarchy is reported at the highest level the user holds on every media type. Access granted in Authenticx on only some media types isn't reported at the higher level.
  • Users without the mapping keep whatever hierarchy access Authenticx already has for them.

Step 8: Define Provisioning Scope

  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.
  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.
    • hierarchyCodes or hierarchyIds, if mapped, carried the expected entries and levels.
  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:

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:

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

Expected capabilities:

CapabilityExpected value
patch.supportedtrue
filter.supportedtrue
sort.supportedtrue
bulk.supportedfalse
authenticationSchemes[0].typeoauth2

Updated 19 days ago

Did this page help you?

Updated 19 days ago

Did this page help you?