You can configure SCIM provisioning between Microsoft Entra ID and Haiilo to import your users and groups from Microsoft. 

Prerequisites

Before you begin, make sure you have:

• A reachable SCIM base URL https://your_haiilo_domain/api/scim/v2. Example: https://example.haiilo.app/api/scim/v2.
• "Manage user directories" permission in your Haiilo platform.
• "Application Administrator" or equivalent permissions in Microsoft Entra ID.

1. Start setting up a SCIM user directory on Haiilo

You need "Manage user directories" permission on Haiilo to set up a user directory.

1. Go to Administration > User directories.
2. Select Create user directory to add a new user directory.
3. Enter a name.
4. Choose a type: SCIM.
5. Activate the directory.
6. In the API Clients tab, select Create to create an API client pair.
7. Copy and save the Client ID and Client Secret for later use. The client secret is generated only after saving and is only visible once.
8. Select Save to save the user directory. 

2. Create an enterprise application on Entra ID

You need to be an "Application Administrator" or have equivalent permissions in Microsoft Entra ID to set up SCIM.

1. Log in to the Microsoft Azure Platform.
2. Go to Enterprise applications > New application.
3. Select Create your own application.
4. Enter a name for this application, e.g., Haiilo SCIM app.
5. Select Integrate any other application you don't find in the gallery (Non-gallery).

6. Select Create to create the application.

   

3. Configure a provisioning connection on Entra ID

1. In your newly created Enterprise Application, go to Provisioning > Provisioning.
2. Set Provisioning Mode to Automatic.
3. Under Admin Credentials, set the Authentication Method to OAuth2 Client Credentials Grant.
4. Fill in the connection details:
   • Tenant URL: Your SCIM base URL https://your_haiilo_domain/api/scim/v2. Example: https://example.haiilo.app/api/scim/v2.
   • Token Endpoint: Your OAuth token endpoint https://your_haiilo_domain/api/oauth/token. Example: https://example.haiilo.app/api/oauth/token.
   • Client Identifier: The Client ID you copied from your SCIM user directory setup in Haiilo.
   • Client Secret: The Client Secret you copied from your SCIM user directory setup in Haiilo.
5. Select Test Connection.
6. If successful, select Save.

4. Assign users and groups on Entra ID

1. In your Enterprise Application, go to Users and groups.
2. Select Add user/group 
3. Assign the users and/or groups you want Entra ID to provision into Haiilo.

5. Configure attribute mappings on Entra ID

This section applies only if you want to synchronize custom user profile fields, like location or city, into Haiilo.

1. Go to Provisioning > Attribute Mappings
2. Select Provision Microsoft Entra ID Users (User mappings).
3. Check the option for Show advanced options at the bottom.
4. Click Edit attribute list for <your app>.
5. Add custom target attributes. For example, profileField_location or profileField_city.
6. Save changes to the attribute list.
7. Back in Attribute Mappings, select Add New Mapping.
8. Define the following:
   • Source attribute: Select a Microsoft Entra field, e.g., city.
   • Target attribute: Select a custom attribute you added above, e.g., profileField_city.
9. Select OK > Save to save your mappings.

6. Start provisioning on Entra ID

1. Go to your Enterprise Application Overview or the Provisioning page.
2. Set provisioning status to ON or select Start provisioning.

Entra ID will perform an initial sync, then run regular incremental updates. Provisioning is asynchronous and eventually consistent. It is not real-time.

Want to test before activation? Use Provision on demand in Entra ID to test a specific user's or group's configuration and outbound behavior immediately.

Reference: How provisioning works on Entra ID

Microsoft Entra ID provisions identities in cycles:

1. Initial cycle: First full synchronization.
2. Incremental cycles: Ongoing updates for changes (assignments, attribute changes, group changes, status changes).

Provisioning is eventually consistent. Changes are not always immediate and may arrive across different cycles.

Provisioning scope and deprovisioning behavior

To ensure expected deprovisioning behavior, verify your provisioning scope in Entra ID:

• Sync only assigned users and groups: Recommended if unassignment should trigger deprovisioning behavior.
• Sync all users and groups: Unassignment from the application may not trigger removal or deactivation, depending on scope and effective assignment state. 

Important deprovisioning note: If a user is removed directly but still assigned through another synced group, Entra ID may keep the user in scope and will not deprovision the user in Haiilo.

Timing expectations

• Incremental cycles commonly run in the ~20-40 minute range in practice. 
• Actual timing depends on:
  • Tenant load
  • Provisioning scope size
  • API throttling
  • Retry behavior
  • Service health / quarantine state
• In some scenarios, full propagation can take longer (including rare delays up to 24 hours).

PATCH and update behavior

• Attribute changes may be sent as SCIM PATCH.
• PATCH updates can occur in the same cycle or a later cycle, depending on when Entra ID evaluates changes and resolves references/matching.
• Order and timing of related updates are not guaranteed.

Group and membership notes

Entra ID provisions effective memberships, but delivery timing or order is not guaranteed. A user may not appear in all expected groups immediately due to:

• Group is not in the provisioning scope.
• There are nested or dynamic group behavior limitations.
• There are attribute mapping or filtering exclusions.
• There are provisioning delays or retry / error conditions.

Known edge cases and limitations

• Ensure a user is not assigned multiple application roles unless explicitly required. If multiple roles are assigned, the role outcome may be non-deterministic for downstream apps.
• Entra ID provisioning does not send null values for cleared attributes in all scenarios.
  • Example observed behavior: If a profile field is left empty in Entra ID, that empty value may not be sent to Haiilo.
• Default value if null (optional): The value that is passed to the target system if the source attribute is null. This value is only provisioned when a user is created. The Default value when null isn't provisioned when updating an existing user. 
  • For example, add a default value for job title, when creating a user, with the expression: Switch(IsPresent([jobTitle]), "DefaultValue", "True", [jobTitle]). 
  • For more information about expressions, see Reference for writing expressions for attribute mappings in Microsoft Entra ID.

Troubleshooting

If a user or group is not synchronized as expected:

1. Check Microsoft Entra Provisioning Logs first (for the affected object).
2. Confirm whether Entra ID:
   • Evaluated the object
   • Sent an outbound request
   • Received success/error from Haiilo
3. If no outbound event is shown, the root cause is typically Entra-side configuration (scope, mapping, assignment path, or provisioning state). Check your configuration.

Please contact our Support team for assistance only after trying the steps above. 

Use Provision on demand in Entra ID for the specific user or group to test configuration and outbound behavior immediately.

Best practices for successful provisioning

• Configure SCIM provisioning on the Enterprise Application and validate assignment paths.
• Keep attribute mappings explicit and reviewed.
• Use Sync only assigned users and groups when assignment-driven lifecycle control is required.
• Monitor provisioning logs regularly for skipped objects and retries.
• Treat provisioning as asynchronous and eventually consistent, not real-time.