SCIM-based User Synchronization with Fortanix DSM

1.0 Introduction

This document explains how to configure automatic user provisioning and de-provisioning using the System for Cross-domain Identity Management (SCIM) protocol, which standardizes user identity management across different systems, such as Microsoft Entra ID identity provider (IdP) and a service provider Fortanix-Data-Security-Manager (DSM).

It also describes the following:

• How users are provisioned, synchronized, and managed using the SCIM standard in Fortanix DSM.

• How to add a SCIM application (app) in Microsoft Entra ID.

• How to set up SCIM in a Fortanix DSM account.

• How to configure provisioning options in the Entra ID app.

• How to set up user provisioning attribute mappings.

• How to provision and synchronize roles.

• How to manage user roles in Microsoft Entra ID.

NOTE

Currently, only Microsoft Entra ID (IdP) has been verified for this integration.

2.0 SCIM Overview

SCIM (RFC 7643 / 7644) is an open standard that provides a standardized REST API for managing user identities across systems. It enables automated provisioning, de-provisioning, and synchronization of identity data between identity providers and service providers.

As organizations adopt more Software as a Service (SaaS) and cloud-based applications, managing user identities across multiple systems becomes complicated and time-consuming. SCIM simplifies this process by providing a consistent, automated framework for user lifecycle management. It improves security, reduces administrative overhead, and improves the user experience.

The following are the benefits of using SCIM:

• Automated user life-cycle management

• Centralized user identity control

• Faster onboarding and offboarding

• Improved security (reduced manual effort, fewer errors, faster deprovisioning)

• Enhanced auditability and compliance

3.0 Architecture

The following diagram explains how the SCIM integration enables communication between Microsoft Entra ID and Fortanix DSM for user provisioning and de-provisioning:

3.1 Key Components

The following are the key components:

• Identity Provider (IdP): The IdP (Microsoft Entra ID) is responsible for user lifecycle management, including provisioning, updating, and de-provisioning of users.

• SCIM Client: The SCIM client within the IdP is responsible for the provisioning and de-provisioning logic. It communicates with Fortanix DSM by sending REST API requests to the Fortanix DSM SCIM endpoints.

• Fortanix DSM: The Fortanix DSM is the service provider that exposes SCIM endpoints for user management. This can be a SaaS or an on-premises Fortanix DSM instance.

• SCIM Endpoints: The SCIM user endpoints implement the logic for creating, updating, and deleting users within the Fortanix DSM account, in compliance with the SCIM standard.

• Fortanix DSM Account: A DSM account includes the following components:

  • Groups

  • List of users associated with the account

  • SCIM configuration, including the authentication API key

  • Security objects and applications

  • Other configurations and resources

• Admin App: Used by administrators to generate API keys, configure SCIM connections, and verify user synchronization between the IdP and Fortanix DSM.

3.2 Workflow

This section explains how SCIM handles user provisioning and de-provisioning between Microsoft Entra ID and Fortanix DSM.

• Step 1: User Management in Microsoft Entra ID

  • Administrators perform user management operations such as create, update, or delete in Microsoft Entra ID. These changes trigger provisioning actions that are processed by the SCIM client.

• Step 2: SCIM Client Setup

  • The administrator configures the SCIM client in Entra ID using an API key obtained from the Fortanix DSM Admin App to securely authenticate SCIM requests.

• Step 3: SCIM API Communication

  • The SCIM client sends HTTPS API requests to Fortanix DSM to synchronize user data:

    • POST User → Creates a new user in Fortanix DSM.

    • PATCH User → Updates user attributes.

    • GET Users → Retrieves user information for verification.

    • DELETE User → De-provisions or removes users.

• Step 4: Provisioning and De-Provisioning in Fortanix DSM

  • Fortanix DSM receives the SCIM API requests and performs corresponding actions:

    • New users are provisioned and assigned to the correct account.

    • Updated user information is synchronized with the appropriate account.

    • Deleted users are de-provisioned or disabled in Fortanix DSM.

    For more information, refer to Section 4.0: SCIM in Fortanix DSM.

4.0 SCIM in Fortanix DSM

The SCIM implementation in Fortanix DSM (both on-premises and SaaS) enables automatic user management within a specific Fortanix DSM account using SCIM-compatible API endpoints. The current functionality includes:

• User provisioning, with optional automatic assignment of account roles

• User de-provisioning

This functionality is additive to the existing user-account behavior and does not alter any other system behavior related to user accounts.

4.1 User Provisioning

User provisioning is initiated once the Admin App is created in Fortanix DSM and configured in Microsoft Entra ID with the API Key for SCIM authentication. This API Key allows Microsoft Entra ID to securely communicate with Fortanix DSM SCIM endpoints to perform user creation and updates based on Microsoft Entra ID directory changes.

For more information on creating the Admin App, refer to Section 5.3: Set up an Admin App in Fortanix DSM.

During the integration, SCIM performs the following functions:

• Automatically creates new users in Fortanix DSM corresponding to users assigned to the Microsoft Entra ID app.

• Synchronizes user roles such as Account Administrator, Account Member, Account Auditor, or any custom roles in Fortanix DSM based on the role assignments in Microsoft Entra ID. For more information on assigning roles to users in the Microsoft Entra ID app, refer to Section 5.6: Role Provisioning and Synchronization.

During user provisioning:

• If the same user is assigned multiple system-defined roles (For example, Account Administrator, Account Auditor, or Account Member), user provisioning will fail.

  For example, if userA is added as both Account Administrator and Account Member in the Entra ID app, an error will occur, and userA will not be provisioned.

• If the same user is assigned multiple custom roles, user provisioning succeeds. For more information on assigning roles in Microsoft Entra ID, refer to Section 5.6: Role Provisioning and Synchronization.

  • If the same user is assigned multiple exclusive custom roles, user provisioning will fail. For more information on custom roles properties, refer to the User's Guide: Custom Role.

• SCIM detects existing Fortanix DSM users and skips re-provisioning to prevent duplication.

• When new users are added to Microsoft Entra ID, SCIM provisions only those users in the Entra ID app who are not already present in Fortanix DSM.

NOTE

• Microsoft Entra ID runs SCIM provisioning cycles automatically every 40 minutes. Therefore, any user or role changes in Entra ID can take up to 40 minutes to reflect in Fortanix DSM.

• SCIM does not differentiate between verified and unverified Fortanix DSM users. Users provisioned through Microsoft Entra ID appear in Fortanix DSM immediately but remain inactive until they complete their Fortanix DSM verification process.

• If a user’s role changes in Microsoft Entra ID, SCIM updates Fortanix DSM in the next cycle. SCIM automatically overrides any Fortanix DSM-side role changes, maintaining Microsoft Entra ID as the source of truth for user permissions.

4.2 User De-provisioning

This section describes how user de-provisioning is handled in the Microsoft Entra ID and Fortanix DSM integration through SCIM.

Refer to the following details on how de-provisioning occurs in Microsoft Entra ID and its impact on Fortanix DSM:

• If a user is removed from the Microsoft Entra ID app, the user will be disabled in the Fortanix DSM account. To restore access, the user must be re-added to the Entra ID app, after which they will be provisioned again in Fortanix DSM during the next synchronization cycle.

• If the user is deleted (moved to a soft-deleted state) in Microsoft Entra ID, the user will be removed from the Microsoft Entra ID app and disabled in the associated Fortanix DSM account. For information on how to remove the user access from the Microsoft Entra ID app, refer to Manage users and groups assignment to an application.

• If a deleted user is restored in Microsoft Entra ID, you must add them again to the Entra ID app, so that the user will be enabled again in Fortanix DSM account during the next synchronization cycle.

• When a user is permanently deleted in Microsoft Entra ID (hard delete), the user is also permanently removed from the associated Fortanix DSM account. For more information on permanently deleting the user and restoring the access in Microsoft Entra ID, refer to Restore or remove a recently deleted user.

NOTE

• Users can be deprovisioned if they belong to a single group or multiple groups in Microsoft Entra ID.

• Fortanix DSM does not send email notifications upon user de-provisioning. Administrators can verify de-provisioning events through SCIM provisioning logs and Fortanix DSM audit logs.

5.0 Set Up Microsoft Entra ID For User Synchronization in Fortanix DSM

You can configure a Microsoft Entra ID enterprise application that uses the SCIM protocol to integrate and synchronize users with Fortanix DSM. This integration enables automated user lifecycle management in Fortanix DSM based on user data in Entra ID.

The process to set up Microsoft Entra ID for SCIM integration is explained in the following sections:

5.1 Prerequisites

The following are the prerequisites to set up Microsoft Entra ID for SCIM-based synchronization in Fortanix DSM:

• You must be an account administrator in your Fortanix DSM account. The account can be either new or existing. Existing users will be linked to Entra ID users during the provisioning cycle.

• You must have administrative privileges in your Microsoft Entra ID tenant.

5.2 Add an Application in Microsoft Entra ID

For detailed steps on how to add an application in Microsoft Entra ID, refer to Using Fortanix Data Security Manager with Microsoft Entra ID.

5.3 Set up an Admin App in Fortanix DSM

Perform the following steps to create an admin app and generate an API key for setting up SCIM in Fortanix DSM:

1. In your Fortanix DSM account, navigate to Settings → ADMINISTRATIVE APPS.

2. Click ADD ADMINISTRATIVE APP.

3. Enter a descriptive name for the app.

4. Select the default API Key authentication method.

5. Click CREATE to add an admin app.

6. For the created admin app, click VIEW API KEY DETAILS.

7. Copy the API Key and save it.

5.4 Configure Entra ID App provisioning options

This section describes the SCIM-based connection between Microsoft Entra ID and Fortanix DSM.

Perform the following steps to configure provisioning-related options in the Microsoft Entra ID app:

1. Navigate to the Microsoft Entra ID app already created and click Provisioning under the Manage menu.

   

2. Click Overview (Preview) → Get Started → Connect your application.

   

                                        

3. On the Connectivity (Preview) page,

   1. Enter Tenant URL in the following format: https://{URL of your Fortanix deployment}/scim/v2?aadOptscim062020.

      The ?aadOptscim062020 parameter ensures that the Microsoft Entra ID SCIM client remains SCIM-compliant.

   2. In the Secret Token field, enter the API Key of the Fortanix DSM Admin App created in Section 5.3: Set Up an Admin App in Fortanix DSM.

   

4. Click Test connection to verify the connectivity.

5. Click Create to configure the Microsoft Entra ID app provisioning options.

5.5 Configure Automatic User Synchronization for Attribute Mapping

This section configures and activates automatic user synchronization between Microsoft Entra ID and Fortanix DSM through SCIM. It defines which attributes are synchronized, who gets provisioned, and allows testing the setup before enabling complete automation.

Perform the following steps to set up user provisioning attributes mappings in Microsoft Entra ID:

1. Navigate to the Microsoft Entra ID app that was already created and click Attribute mapping (Preview) under the Manage menu.

2. Select Provision Microsoft Entra ID Users.

   NOTE

   Ensure Provision Microsoft Entra ID Groups is disabled as group provisioning is not supported.

   

3. On the Attribute Mapping page, delete all attribute mappings except the following:

   1. username: It must be mapped to the user’s email address (default).

   2. active

   3. externalId

   NOTE

   If you retain all attributes, deprovisioning and all REST API calls used for updating user roles (PATCH) will fail. For more information about the resulting error and its resolution, refer to Section 7.0: Troubleshooting.

   

4. Navigate to Users and groups under the Manage tab.

5. Click Add user/group to assign the group and/or the app. Users in the assigned group will also be managed automatically.

   

6. Navigate to Provision on demand from the left navigation menu. This option helps you manually test provisioning for a specific user to verify that attribute mappings and SCIM connectivity are correctly configured.

7. Enter the required user and click Provision to test the user provision.

   

8. After the test is successful, set Provisioning Status to On to activate automatic synchronization.

5.6 Role Provisioning and Synchronization

Fortanix DSM supports automatic role provisioning and synchronization through its SCIM integration with Microsoft Entra ID.
Role management can be performed directly in Fortanix DSM using its built-in account roles (Account Administrator, Account Member, and Account Auditor). To further streamline user management, Fortanix DSM also supports the provisioning and synchronization of custom roles through SCIM.

To enable this feature, configuration is required in both Fortanix DSM and Microsoft Entra ID.

5.6.1 Configuration in Fortanix DSM

In addition to the built-in Fortanix DSM account roles (Account Administrator, Account Member, and Account Auditor), Fortanix DSM users can define custom roles with more fine-grained permissions. User custom roles must exist in Fortanix DSM before setting up Microsoft Entra ID. User role assignment must adhere to the existing Fortanix DSM role restrictions.

To avoid invalid role combinations, refer to the User's Guide: Custom Role.

Create a Custom Role

For detailed steps on how to create a custom account role, refer to User's Guide: Custom Role.

Ensure to note down the role_id, as it will be required later.

After completing the custom role creation, the following roles can now be managed using Microsoft Entra ID:

• DSM Account Administrator

• DSM Account Member

• DSM Account Auditor

• Any Custom Account Roles defined in Fortanix DSM

5.6.2 Configuration in Microsoft Entra ID

Configuration in Microsoft Entra ID involves the following steps:

• Creating app roles

• Setting up attribute mapping

Creating App Roles

NOTE

If user roles are not assigned in the Microsoft Entra ID App roles,

• The Microsoft Entra ID app will retain its default roles.

  

• Any user added to the Microsoft Entra ID app will, by default, be provisioned with the Account Member role in Fortanix DSM.

  

Perform the following steps to create the app roles:

1. In Microsoft Entra ID, navigate to App registrations → Select your app → App roles → Create app role.

2. On the Create app role form,

   1. In the Display name field, enter one of the following: Account Administrator, Account Auditor, Account Member, or any custom role you want to add to easily distinguish it from the Fortanix DSM supported roles.

   2. For Allowed member types, select Users/Groups.

   3. In the Value field, add the value corresponding to the role name specified in Step 2.a:

      • Account Administrator: AccountAdministrator

      • Account Member: AccountMember

      • Account Editor: AccountAuditor

      • Custom roles: Enter the custom role ID obtained from Fortanix DSM in Section 5.6.1: Configuration in Fortanix DSM.

      NOTE

      Ensure that there are no spaces in the value.

   4. In the Description field, enter an appropriate description.  

   5. Select the Do you want to enable this app role? check box.

   6. Click Apply to add the app role.

   

   The app roles will be added to the App roles list.

   

   NOTE

   You can add multiple custom roles using the Steps 1 and 2 mentioned above, with different Display name.

3. After creating the app roles,

   1. Assign them to users or groups using Enterprise applications → Select your app → Users and groups → Add user/group or Edit assignment.

      

   2. If you are using Edit assignment, select a role, click Select and Assign to assign the role.

      

Set Up Attribute Mapping

Perform the following steps to set up the attribute mapping:

1. Navigate to the Microsoft Entra ID app you created and click Attribute mapping (Preview) under the Manage menu.

2. Select Provision Microsoft Entra ID Users.

3. On the Attribute Mapping page, enable Show advanced options check box and click Edit attribute list for customappsso.

   

4. On the Edit Attribute List page, add roles with type String and Multi-Value? check box enabled.

   

5. In the Attribute Mapping page, add roles using the expression AssertiveAppRoleAssignmentsComplex([appRoleAssignments]). This ensures that role provisioning and updates occur automatically whenever there are changes in Microsoft Entra ID.

   NOTE

   Fortanix DSM only supports AssertiveAppRoleAssignmentsComplex, which fully handles role provisioning and synchronization. Changes to Entra ID roles are synchronized to Fortanix DSM during the Entra ID SCIM cycle.

   For more information, refer to Tutorial - Customize user provisioning attribute-mappings for SaaS applications in Microsoft Entra ID.

   

6.0 References

If needed, configure Microsoft Entra ID SAML in Fortanix DSM to enable SSO authentication. For more information on how to set up this integration, refer to Using Fortanix Data Security Manager with Microsoft Entra ID.

7.0 Troubleshooting

• If Microsoft Entra ID encounters an error (For example, invalid credentials, mismatched attributes, or connectivity issues), it logs the failure in the Provisioning Logs under the application’s provisioning settings. These logs can be reviewed for troubleshooting.

  For detailed information on SCIM provisioning behavior and timing, refer to What are the Microsoft Entra user provisioning logs?.

• If you retain all attributes on the Attribute Mapping page, deprovisioning and any REST API (PATCH) requests used to update user roles will fail with the following error:

  • Microsoft Entra ID:

    

  • Fortanix DSM:

    

  To resolve this issue, remove any unnecessary attributes in Attributes Mapping (Preview).

• Audit log messages for create, update, and delete SCIM operations can also be found in the Fortanix DSM Audit Log menu.

8.0 Limitations

The following limitations apply to the Microsoft Entra ID SCIM integration with Fortanix DSM:

• The Microsoft Entra ID SCIM integration with Fortanix DSM does not support automatic updates to a user’s email address. If a user’s email (mapped to the userName attribute in SCIM) changes in Microsoft Entra ID, the modification will not be synchronized automatically to Fortanix DSM. Fortanix recommends not to change the email address after user provisioning.

• User de-provisioning fails when the user is part of the Fortanix DSM account/group Quorum approval policy. In this scenario, the Fortanix DSM account administrator must manually remove the user from the Fortanix DSM account/group Quorum approval policy.

9.0 FAQs