Loading ...

Setup Guide: Entra ID SCIM Provisioning | Axero Documentation

Home » axero documentation » Wiki » Documentation » Login » Single Sign-On (SSO) » Entra ID » Setup Guide: Entra ID SCIM Provisioning
Axero Documentation  Wiki
Public Space
Activity Stream Content
Version 26

Setup Guide: Entra ID SCIM Provisioning

0 
 /5
0 (0votes)

This guide explains how to configure automated user provisioning between Microsoft Entra ID (formerly Azure Active Directory) and Axero using SCIM (System for Cross-domain Identity Management). This setup automates creating, updating, and deactivating user accounts for your intranet.

For SSO without automatic provisioning, see the Setup Guide: Entra ID SAML SSO.

Do you need SCIM? No. SCIM is optional, and SAML SSO on its own is a complete setup. With SSO alone, accounts are created the first time someone signs in, their profile is refreshed at every sign-in, and access is already controlled, because a person who loses their Entra ID account or their group assignment can no longer sign in. Role mapping runs through the SAML claims either way, and no content is lost either way.

What SCIM adds is one thing: it deactivates the Axero account of someone who leaves, instead of leaving you to do it by hand. If departures are rare, or you already have a process for them, SSO alone is enough. If you want departures handled automatically, continue with this guide.

Overview

Preparation

Before you start, ensure you have:

  • Global Administrator or User Administrator role in your Microsoft Entra ID tenant
  • Site Administrator access to your Axero site
  • Completed the following prerequisite steps from the Setup Guide: Entra ID SAML SSO:
    • Step 1: Created and configured your Entra ID enterprise application
    • Step 2: Configured SAML SSO settings in Axero
    • Step 3: Successfully tested SSO functionality
  • Completed the System Properties listed in the Setup Guide: Entra ID SAML SSO. Those settings govern sign-in. Provisioning over SCIM does not read them, so nothing extra is needed here.

Important: SCIM provisioning requires a working SSO configuration. Users provisioned via SCIM will authenticate using SSO credentials.

Step 1: Enable SCIM Provisioning

  1. Sign in to the Microsoft Entra admin center with an account that has at least User Administrator or Global Administrator role.
  2. Browse to Entra ID > Enterprise apps and select your Axero SSO application from the list.
  3. In the left-hand menu, select Provisioning.
  4. Select New configuration.
  5. In the Tenant URL field, enter your Axero site's URL followed by /api/scim/v2 (for example, https://your-axero-site.com/api/scim/v2).
    The Provisioning settings in Entra, with the Tenant URL field holding the Axero SCIM endpoint address
  6. Open a new browser tab and sign in to your Axero site with Site Administrator credentials.
  7. Navigate to Control Panel > System > Single Sign On.
  8. Expand the SCIM User Provisioning section and copy the Bearer token.
    The SCIM User Provisioning section in Axero, showing the generated Bearer token
  9. Return to the Microsoft Entra admin center tab and paste the token into the Secret Token field.
    The Entra Provisioning screen with the token pasted into the Secret Token field
  10. Select Test connection to verify SCIM endpoint connectivity.
    The Test connection control on the Entra Provisioning screen
  11. Once the connection test is successful, select Create.
    The Create button, shown once the connection test has passed
Important: Store the Bearer token securely and treat it as a sensitive credential. This token provides complete access to your Axero SCIM endpoint for user provisioning operations.

Step 2: Configure User Attribute Mappings

  1. Return to the Provisioning page and select Mappings.
  2. Select Provision Microsoft Entra ID Users.
  3. Locate the externalId customappsso Attribute and select Edit to the right.
  4. Set the Source attribute to objectId and click OK to confirm the changes. This ensures proper user matching between Entra ID and Axero.
  5. Locate the userName customappsso Attribute and select Edit to the right.
  6. Change the Source attribute to mail and click OK. This allows usernames and email addresses to be updated via SCIM when changes occur.
  7. Select Save to apply all modifications and confirm by selecting Yes.
Technical Note: The objectId to externalId mapping is critical for proper user lifecycle management. This ensures that Entra ID can correctly identify and update existing users in Axero during subsequent provisioning operations.

Step 3: Test the Integration

Important: Always test SCIM provisioning with a non-production user account before enabling automatic provisioning for your organization.

3.1 Test User Creation

  1. Assign a test user to the application:
    • In the Microsoft Entra admin center, navigate to your Axero enterprise application
    • Select Users and groups from the left navigation
    • Select Add user/group
    • Under Users, select None Selected
    • Search for and select a test user account, then select Select
    • Select Assign to complete the assignment
  2. Test on-demand provisioning:
    • Navigate to Provisioning and select Provision on demand
    • Search for and select the test user you just assigned
    • Select Provision to initiate the provisioning process
    • Review the provisioning results to ensure successful user creation
  3. Verify user creation in Axero:
    • Sign in to your Axero site as a Site Administrator
    • Navigate to Control Panel > People > Manage People
    • Search for the test user to confirm the account was created
    • Verify that user attributes (name, email) are populated correctly

3.2 Test Attribute Updates

  1. Update user attributes in Entra ID:
    • In the Microsoft Entra admin center, navigate to Identity > Users > All users
    • Select the test user and choose Edit properties
    • Update the user's first name, last name, or job title
    • Select Save to apply the changes
  2. Sync the changes:
    • Return to your Axero enterprise application in Entra ID
    • Navigate to Provisioning and select Provision on demand
    • Select the same test user and choose Provision
    • Verify the provisioning results show successful attribute updates
  3. Verify updates in Axero:
    • In Axero, navigate to the test user's profile
    • Confirm that the updated attributes are reflected correctly

3.3 Test User Deactivation

⚠️ Matching people who already have an Axero account
Entra ID looks for an existing Axero account before it creates one. It searches on the value you mapped to userName in Step 2, and Axero matches that against the Axero username, either the whole value or the part before the @ sign. When it matches, Entra ID takes over that existing account on the first cycle and manages it from then on, including deactivation. Nobody has to be re-created.

If someone is not picked up, their Axero username is in a different format from the value Entra ID is sending. Correct the Axero username, or change the source attribute behind the userName mapping so the two agree. Removing and re-adding their assignment does not help on its own.
  1. Remove user assignment:
    • In the Microsoft Entra admin center, navigate to your Axero enterprise application
    • Select Users and groups
    • Find the test user and select Remove assignment
    • Confirm the removal
  2. Test deactivation:
    • Navigate to Provisioning and select Provision on demand
    • Search for the test user (they may still appear in the list)
    • Select Provision to process the deactivation
  3. Verify deactivation in Axero:
    • In Axero, navigate to Control Panel > People > Manage People
    • Verify that the test user's account has been moved to the Deactivated People tab

3.4 Review Provisioning Logs

  1. Access provisioning logs:
    • In the Microsoft Entra admin center, navigate to Entra ID > Monitoring & health > Provisioning logs
    • Filter the logs by your Axero application if needed
  2. Review log entries:
    • Examine the provisioning activities for your test user
    • Verify that all operations (create, update, delete) completed successfully
    • Note any warnings or errors for troubleshooting

Step 4: Assign Users and Groups

4.1 Configure User and Group Assignments

  1. In the Microsoft Entra admin center, navigate to Entra ID > Enterprise apps and select your Axero application.
  2. Select Users and groups from the left navigation.
  3. Select Add user/group to begin the assignment process.
  4. In the Add Assignment pane:
    • Select Users and groups to choose specific users or groups for provisioning
    • Search for and select the appropriate users or groups from your directory
    • Click Select to confirm your choices
  5. Select Assign to complete the assignment process.
Important: Only users and groups explicitly assigned to the application will be provisioned to Axero. Users not assigned to the application will not be created or synchronized, even if they exist in your Entra ID directory.

4.2 Verify Assignment Configuration

  1. Review the assigned users and groups to ensure all intended users are included.
  2. Consider using groups for easier management of large user populations.
  3. Verify that test users from Step 3 are properly assigned if you plan to continue testing.

Step 5: Start Provisioning

5.1 Enable Automatic Provisioning

Turn group provisioning off before you start. Under the provisioning Mappings, open Provision Microsoft Entra ID Groups and set Enabled to No. Axero's SCIM endpoint provisions users only and has no group endpoint, so every group request fails. Entra ID responds by quarantining the connector, after which it stops retrying on the normal schedule and falls back to roughly once a day, which stalls user provisioning as well. The group mapping is enabled by default, so this is a step to take rather than a default to rely on.

If provisioning is already quarantined, set the group mapping to No, then use Restart provisioning to clear the quarantine.
  1. Navigate back to the Provisioning section of your Axero application.
  2. Select Start provisioning to begin the automatic synchronization process.
    The Entra provisioning overview with the Start provisioning button
  3. Monitor the initial provisioning cycle by checking the Current cycle status on the provisioning page.
Provisioning Schedule: Microsoft Entra ID automatically synchronizes user profiles approximately every 40 minutes after the initial cycle. For immediate provisioning of specific users, use the Provision on demand feature.

5.2 Monitor Initial Provisioning

  1. Allow 10-15 minutes for the initial provisioning cycle to complete.
  2. Review the Provisioning logs to verify successful user creation and attribute synchronization.
  3. Address any provisioning errors before proceeding to full deployment.

Optional: Add Custom Attributes

Before you open Data Mapping: on the SCIM tab, the custom attribute Property Name fields are read-only, showing a no-entry cursor, until the SCIMCustomAttributesEnabled system property is set to True. That step is section 6.3 below, at the end of this walkthrough. If you go to Data Mapping first, the locked fields look like a fault rather than a missing prerequisite, so set the property before you start.

SCIM provisioning supports both standard and custom user attributes. The following properties are typically defined in Entra ID by default and only need to be mapped to profile fields in Axero.

Entra ID Property Name Axero User Field Description
name.givenName First name User's first name
name.familyName Last name User's last name
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department Department Department. An enterprise extension attribute rather than a core one, so it carries the qualified name shown
title Job title Job title
addresses[type eq "work"].streetAddress Address 1 Street address
addresses[type eq "work"].locality City City or locality
addresses[type eq "work"].region State State or region
addresses[type eq "work"].country Country Country
addresses[type eq "work"].postalCode Postal code ZIP or postal code
Limitations: SCIM does not carry profile pictures, because Entra ID does not put photos in what it sends. To sync profile pictures, configure User Syncing. Manager relationships do sync over SCIM. Confirm manager is present in the Entra ID attribute mappings, since it is not always there by default, and keep the matching manager row on the Data Mapping tab, which Axero provides. The person named as the manager needs their own Axero account before the link can be made.
Warning: the manager must arrive in the enterprise schema, or every sync clears Reports to. Axero reads the manager only from urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. If your provider sends it somewhere else, inside a custom schema for example, Axero sees no manager at all, and because a Data Mapping row named manager exists it writes an empty value instead of leaving the field alone. The result is that Reports to is wiped on every provisioning cycle, with no error to explain it.

There are two ways out. Move the manager into the enterprise schema, which is what Entra ID does by default, or rename the Data Mapping row to something else, such as ManagerEmail, and send a plain email address to it. Do not leave a row named manager in place while the manager arrives by any other route.
Prerequisites: Custom attribute configuration requires advanced SCIM knowledge and should only be performed by experienced administrators. Test all custom attributes thoroughly before deploying them in production.

6.1 Configure Custom Attributes in Entra ID

Data Mapping Worksheet

Plan your SCIM attribute mapping with our Data Mapping Worksheet. This template includes pre-configured examples and Axero field mappings.

Quick Start: Click File → Make a copy to create your own editable version of the worksheet.

  1. In your Axero enterprise application, navigate to Provisioning.
  2. Select Attribute mapping from the menu.
  3. Select Provision Microsoft Entra ID Users.
  4. Select Show advanced options at the bottom of the page.
  5. Select Edit attribute list for customappsso(or your specific application name).
  6. At the bottom of the attribute list, add new custom attributes. Give each one a Name that starts with urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:, then the attribute name. Axero reads that prefix and strips it, so the Data Mapping row in Step 6.3 uses the short name on its own.
    An Entra attribute mapping showing the namespace prefix on a custom attribute name
    Example custom attribute configuration:
    Name Type Description
    urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:hireDate DateTime Employee hire date
    urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber String Employee ID number. This one is the exception in this table: Axero reads it as employeeNumber from the standard enterprise extension, not from the Microsoft Entra extension, and it fills the built-in employee number field directly rather than needing a custom profile field. Sending it as employeeId under the Entra extension lands nowhere unless you have separately created a matching custom field
    urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:businessPhone String Business phone number
    urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mobilePhone String Mobile phone number
    Why this particular schema name: Axero recognizes this one on both account creation and later updates, without any further configuration. A name entered on its own, with no prefix, reaches Axero on updates but not when the account is first created, which looks like an attribute that fills in eventually but is missing on day one. A schema name of your own has the mirror-image problem: setting the SCIMCustomAttributesURNSchema system property to it covers account creation, but not later updates. Use the name above unless you have a reason not to, and confirm it end to end with the Provision on demand test in step 6.4 before you rely on it.
  7. Select Save and confirm by selecting Yes.

6.2 Create Attribute Mappings

  1. Select Add New Mapping to create mappings for each custom attribute:
    • Mapping type: Select Direct
    • Source attribute: Choose the corresponding Entra ID attribute (e.g., employeeHireDate, telephoneNumber, mobile)
    • Target attribute: enter the attribute in its full namespaced form, for example urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:hireDate. The bare name on its own, hireDate, puts the attribute at the top level of what Entra sends, where Axero cannot reach it when the account is first created. The field then saves as empty. It usually looks like it worked anyway, because a later edit, a Provision on demand, or the next cycle fills the value in, so the mistake only shows on brand new accounts. Note that the Axero-side Property Name in section 6.3 stays the bare hireDate; Axero strips the prefix before matching, so the two sides look different on purpose
    • Match objects using this attribute: Select No
    • Apply this mapping: Select Always
    • Select OK to save the mapping
      The Edit Attribute panel in Entra, with the OK button that saves the mapping
  2. Repeat for all custom attributes you want to synchronize.
  3. Select Save and confirm by selecting Yes.

6.3 Configure Custom Attributes in Axero

⚠️ Email Address Mapping
Do NOT add the mail attribute to SCIM data mappings in Axero. Email addresses are automatically updated through the SSO authentication process and the userName mapping configured in Step 2. Adding a separate mail attribute mapping will create conflicts and may cause provisioning quarantines that prevent user synchronization.
  1. In Axero, navigate to Control Panel > System > System Properties.
  2. Type "scim" in the filter search bar.
  3. Locate the SCIMCustomAttributesEnabled system property and select Edit.
  4. Set the Value to True to enable custom attribute support.
  5. Select Save to apply the changes.
  6. Navigate to Control Panel > System > Single Sign On.
  7. Select the Data Mapping tab and choose SCIM.
  8. Select Add to create new attribute mappings.
    The Entra attribute mapping list with the Add new mapping link
  9. Configure the mapping to match your Entra ID custom attributes:
    Property Name Axero Field
    hireDate Hire date
    employeeId Employee ID (custom field)
    businessPhone Phone
    mobilePhone Mobile (custom field)
    Before you map: the Axero Field list only offers profile fields your site already has. Hire date and Phone come with every site. Employee ID and Mobile do not, so create them first under Control Panel > People > User Profiles, or map to a field you already have.
  10. Remove any unused mappings to avoid conflicts.
  11. Select Update to save the configuration.

6.4 Test the Configuration

  1. The system property and the mappings take effect as soon as you save them, so there is nothing further to apply.
  2. Return to the Entra ID Provisioning page and use Provision on demand to test the new custom attribute mappings.
  3. Verify that custom attributes are populated correctly in user profiles within Axero.
  4. If a value still does not appear and the mapping is correct on both sides, restart the site from Control Panel > System > Advanced System Utilities and test again. A restart takes one to two minutes and is not normally needed.

Troubleshooting

Common Issues and Solutions

💡 Quick Reference: SCIM Limitations
Before troubleshooting, remember these key SCIM behaviors that often cause confusion:
  • Email conflicts: Never add mail attribute to SCIM mappings; it's handled automatically
  • Pre-existing users: These are matched on username and taken over automatically; a miss means the usernames do not agree
  • Cleared fields: Empty values in Entra ID don't automatically clear fields in Axero
  • Connection Test Failures:
    • Verify the SCIM endpoint URL format: https://your-axero-site.com/api/scim/v2
    • Confirm the Bearer token is copied correctly without extra spaces
    • Check that your Axero site is accessible from the internet
    • Ensure SSL certificate is valid and trusted
  • User Creation Failures:
    • Check the provisioning log entry for the failure. SCIM account creation does not depend on the SAML sign-in properties, so the cause is usually a missing required attribute or a username that breaks the site username rules
    • Check that required user attributes (email, first name, last name) are populated in Entra ID
    • Ensure username length settings in Axero accommodate your Entra ID usernames
    • Review provisioning logs for specific error messages
  • Attribute Update Issues:
    • Confirm the attribute is mapped on both sides, in the Entra ID attribute mappings and on the Axero Data Mapping tab
    • Verify attribute mappings are configured correctly
    • Check that the objectId to externalId mapping is properly configured
    • Empty/Cleared Field Values: Entra ID does not send null or empty values via SCIM. If a field was cleared in Entra ID, Axero may retain the old value. To resolve this:
      • Option 1: Set a placeholder value (like "N/A" or "-") in the Entra ID field to force an update
      • Option 2: Manually clear the field value in Axero's user profile
      • Option 3: Wait for the daily sync or user login if the attribute is also mapped on the "Azure Active Directory" SAML data mapping page
  • User Deactivation Problems:
    • Deactivation only reaches accounts Entra ID has matched. Confirm the person appears in the provisioning logs as matched rather than skipped
    • If they were never matched, their Axero username does not agree with the value mapped to userName
    • Check provisioning logs to confirm deactivation requests are being processed

Accessing Diagnostic Information

  • Entra ID Provisioning Logs: Navigate to Entra ID > Monitoring & health > Provisioning logs
  • Entra ID Sign-in Logs: Navigate to Entra ID > Monitoring & health > Sign-in logs
Support: If you encounter persistent issues, contact Axero Support with relevant error messages and provisioning log details.

Additional Considerations

Security Best Practices

  • Token Management: Treat SCIM Bearer tokens as highly sensitive credentials. Store them securely and rotate them regularly.
  • Network Security: Ensure your Axero site uses HTTPS with a valid SSL certificate for all SCIM communications.
  • Access Control: Use Entra ID's "Assignment required" setting to control which users can be provisioned to Axero.
  • Monitoring: Regularly review provisioning logs to detect and respond to any unauthorized access attempts.

Operational Considerations

  • Sync Frequency: Microsoft Entra ID automatically synchronizes user profiles approximately every 40 minutes after the initial cycle, though timing may vary based on system load and tenant size.
  • Bulk Operations: For large-scale user provisioning, consider using staged rollouts to monitor system performance.
  • Backup Strategy: Maintain regular backups of your Axero user data before implementing SCIM provisioning.
  • Change Management: Document all SCIM configuration changes and test them in a non-production environment first.

What Happens When Someone Leaves

  • Going out of scope deactivates the account. When Entra ID stops assigning somebody to the application, it sends the account through as inactive, and Axero deactivates it. The person can no longer sign in, and their content stays where it is under their name.
  • A delete request removes the account instead. If your provisioning setup is configured to send a delete rather than mark the account inactive, Axero removes the account and hands its content to another account rather than leaving it in place. Which account receives it is set by the SCIMDeleteUserAssignUserID system property; setting it to -1 assigns the content to the Anonymous user. Check this setting before you turn provisioning on, because the two outcomes are not the same and only the first one is reversible.

Integration Limitations

  • Profile Pictures: Entra ID cannot send photos through provisioning, so no SCIM configuration will carry them. Use User Syncing instead.
  • Manager Relationships: These sync over SCIM once manager is mapped on the Entra ID side, which is not always the case by default. Check the attribute mappings and add it if it is missing. The manager also needs their own Axero account, so a manager who is not in scope for provisioning will not be linked.
  • Group Memberships: the Axero SCIM endpoint implements the User resource only. There is no group endpoint to write to, so group provisioning cannot be made to work with more configuration. It must be switched off, and leaving it on is actively harmful: see the group provisioning warning in Step 5. Manage Axero space membership with Personas built on profile field values, or assign it in Axero.
  • Custom Fields: Complex custom field mappings may require Enhanced Support assistance.

Troubleshooting Resources

Support and Feedback

If you get stuck, open a support case and include any error messages, provisioning log details, screenshots from both Entra ID and Axero.

Wiki Index

Pages