Documentation  ❯   Directory synchronization

Directory synchronization with Microsoft Entra ID/Azure Active Directory

Directory synchronization is supported via the SCIM protocol. This page describes the configuration for Microsoft Entra ID (previously Azure Active Directory).

Steps

1. Create a new enterprise application in Microsoft Entra ID

In the Azure Portal, go to Microsoft Entra ID / Enterprise Applications and create a new application. Select “Create your own application” on the top.

2. Define SignPath application roles in the application registration

Go back to the Microsoft Entra ID main page, select App registrations, change the list to All Applications and find the application registration you just created.

Under App roles, create an entry for each role in SignPath using “Users/Groups” as allowed member types:

Note: For more information about the permissions assigned to each role, see the user documentation.

3. Create a synchronization user on SignPath

In your SignPath organization, create a CI user, remember the Api Token and change its role to Directory Synchronizer. This user will be the service account on SignPath that creates/updates the user and group entities.

4. Configure provisioning for the enterprise application

Go back to the Microsoft Entra ID main page, select Enterprise applications and select the application you have created in step 1.

Under Provisioning, click Get started, then enter the following settings:

• Use Automatic for the Provisioning mode.
• Enter https://scim.connectors.signpath.io/scim/<your-organization-id>/dry-run as a Tenant URL.
• Use the SignPath CI User API token from step 3 as the Secret Token.

Dry-Run mode

By specifying the /dry-run postfix in the Tentant URL, you tell the SignPath connector to only simulate the updates/changes, but not perform any write operations. We recommend testing the setup with this configuration and to remove the /dry-run URL segment when done (see step 7).

Click “Test connection” to confirm that the configuration is correct. When successful, save the provisioning settings.

5. Configure provisioning mapping for the enterprise application

Close the dialog, select Provisioning, open the Mapping group and click Azure Active Directory Users.

On the next page, check Show advanced options and click on Review your schema here.

Then, replace the existing JSON with the one from this link and save the schema. After closing the dialog, you need to refresh the Azure page, then the Attribute Mappings will be pre-filled for you. Click on the row that maps to “externalId” in the customappsso Attribute column.

Change the Mapping type to “Expression” and enter the following expression: Append("<your-sso-identifier>:", [objectId]).

Mapping expression

To find out the value for <your-sso-identifier>:, open an exising user on SignPath. In the Identity field, everything before the first : is your SSO identifier.

In order for SignPath to be able to map your Microsoft Entra ID users correctly, the second part of the SignPath Identity (after the :) should map to the respective field of the Microsoft Entra ID user. If you are mapping your Microsoft Entra ID users directly, you can use [objectId]. If you are forwarding your sid from your Active Directory, use [onPremisesSecurityIdentifier].

For details on how the expression system works in Azure, see the Microsoft reference for writing expressions for attribute mappings.

After saving the mapping, you can now test your configuration.

6. Test the configuration

Go back to the Entra ID main page, select Enterprise applications and select the enterprise application you created. Select Users and groups and click “Add users and groups”.

Select a test user that already exists in the SignPath organization and assign them a role. Then select Provisioning on the left pane and Provision on demand on the next screen. Select the user you just added and click “Provision”.

When the provisioning succeeded, click on “View details” in section 3. Match user between source and target system. The synchronization should have found an existing user on SignPath that matches. If it attempts to create a new user, there is an error in the configuration.

7. Remove the /dry-run postfix, assign users and groups and start provisioning

After you successfully tested the configuration, you can remove the /dry-run postfix of the Tenant URL that was entered in step 4. Afterwards, you can start the provisioning on the Overview page of the provisioning settings The assigned Entra ID users and groups will then be synchronized to your SignPath organization.

You can now assign all users and groups that you want to synchronize.

Notes on the synchronization

User synchronization:

In the default mapping configuration, Entra ID users are initially mapped to SignPath users by comparing the following attribute values:

• First, the externalId attribute configured in step 5
• Second, the displayName attribute

Every user must be assigned at most one role other than Regular User, otherwise the synchronization will fail.

When an Entra ID user is removed from all groups that are synchronized, the SignPath user will be deactivated.

Group synchronization:

• Groups are initially mapped using their displayName attribute. If a group does not exist in SignPath yet, it will be created.
• Nested groups are not supported by Microsoft by Microsoft Entra. However, if a user is both in a first- and second-level group, their group assignment (but not role assignment) is correctly resolved. See the official Microsoft documentation on scoping.
• We suggest creating two “types” of groups:
  • Role groups like “PKI Team” or “Auditors” where users are mapped to a specific role, e.g. Certificate Administrator or Global Reader.
  • Project specific groups that can be assigned within SignPath, such as “Project 1 Submitters” or “Project 2 Configurators”. You can assign these groups the role Regular User.

After the first mapping is done, Azure will match users and groups using their unique IDs.

Troubleshooting

All synchronization attempts can be viewed in the Enterprise Application under Provisioning logs.

Please note that some items may take a couple of hours to be synchronized.