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 19

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 for SAML SSO.

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 SSO Setup Guide:
    • Step 1: Created and configured your Entra ID enterprise application
    • Step 2: Configured SAML SSO settings in Axero
    • Step 3: Successfully tested SSO functionality
  • Confirmed the following Axero System Properties are configured:
    • Navigate to Control Panel > System > System Properties
    • SAMLAutoUserCreation = True
    • SAMLAutoUserUpdate = True

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).
  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.
  9. Return to the Microsoft Entra admin center tab and paste the token into the Secret Token field.
  10. Select Test connection to verify SCIM endpoint connectivity.
  11. Once the connection test is successful, select Create.
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 > Users > Manage Users
    • 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

⚠️ SCIM User Management Limitation
Only SCIM-provisioned users can be managed through SCIM. If users were manually created or imported into Axero before SCIM was enabled, their records are not SCIM-managed and will not respond to SCIM updates, deactivations, or attribute changes.

Solution for existing users: To make existing users SCIM-manageable, they must be re-provisioned through the SCIM process. This typically involves temporarily removing their assignment in Entra ID, then reassigning them to trigger fresh provisioning.
  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 > Users > Manage Users
    • 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

  1. Navigate back to the Provisioning section of your Axero application.
  2. Select Start provisioning to begin the automatic synchronization process.
  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

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
givenName First name User's first name
familyName Last name User's last name
department Department Department
title Occupation Job title
streetAddress Address 1 Street address
locality City City or locality
region State State or region
country Country Country
postalCode Postal Code ZIP or postal code
Limitations: Profile pictures and managers cannot be synchronized using SCIM. To sync profile pictures and manager relationships, you must configure User Syncing.
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

Streamline your SCIM attribute mapping process 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.

    Example custom attribute configuration:
    Name Type Description
    hireDate DateTime Employee hire date
    employeeId String Employee ID number
    businessPhone String Business phone number
    mobilePhone String Mobile phone number
  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: Select the custom attribute you created (e.g., hireDate, businessPhone, mobilePhone)
    • Match objects using this attribute: Select No
    • Apply this mapping: Select Always
    • Select OK to save 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.
  9. Configure the mapping to match your Entra ID custom attributes:
    Property Name Axero Field
    hireDate Hire date
    employeeId Employee ID
    businessPhone Phone
    mobilePhone Mobile
  10. Remove any unused mappings to avoid conflicts.
  11. Select Update to save the configuration.

6.4 Apply Configuration Changes

  1. Navigate to Control Panel > System > Advanced System Utilities.
  2. Select Restart Site to apply the custom attribute configuration.
  3. Wait for the site restart to complete (typically 1-2 minutes).
  4. Return to the Entra ID Provisioning page and use Provision on demand to test the new custom attribute mappings.
  5. Verify that custom attributes are populated correctly in user profiles within Axero.

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: Manually created users need re-provisioning to become SCIM-managed
  • 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:
    • Verify that SAMLAutoUserCreation is set to True in Axero System Properties
    • 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 that SAMLAutoUserUpdate is set to True in Axero System Properties
    • 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:
    • Only SCIM-provisioned users can be deactivated via SCIM
    • Manually created users in Axero are not affected by SCIM deactivation operations
    • 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.

Integration Limitations

  • Profile Pictures: SCIM cannot synchronize profile pictures. Use User Syncing for this functionality.
  • Manager Relationships: Manager hierarchies require User Syncing configuration.
  • Group Memberships: SCIM provisioning focuses on user accounts. Group provisioning may require additional configuration.
  • Custom Fields: Complex custom field mappings may require Enhanced Support assistance.

Troubleshooting Resources

Support and Feedback

Need further assistance? Submit a support ticket to our technical support team for personalized help. To expedite the troubleshooting process, please include relevant error messages, screenshots from both Entra ID and Axero, and provisioning log details.

We value your feedback! If you have suggestions for improving this documentation, please let us know when submitting a support case.

Wiki Index

Pages