# Microsoft Entra ID Synchronization {% hint style="warning" %} Azure Active Directory (Azure AD) has been renamed to **Microsoft Entra ID** (**ME-ID**). While the WorkflowGen documentation has been updated to reflect this name change, the WorkflowGen application settings still refer to Azure AD (for example, `Azure AD SCIM v2` directory connector). Likewise, certain ME-ID configuration items in the Azure portal have been renamed and/or moved. The WorkflowGen documentation has been updated accordingly, but still might not be completely accurate in this regard. See the [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/) documentation for more information. {% endhint %} ## Overview This section provides instructions on how to configure the WorkflowGen Azure AD synchronization connector, which relies on Microsoft Entra ID user provisioning features. Users and groups are automatically updated (pushed to WorkflowGen) by ME-ID (every 20 to 40 minutes) using the SCIM v2 protocol. As mentioned, it's ME-ID that pushes the data to WorkflowGen. The nature of the protocol doesn't allow WorkflowGen to update in any way the directory in ME-ID. In other words, it's ME-ID that queries WorkflowGen for information, not the other way around. This means that ME-ID is the only source of truth for users and groups for the system. In the instructions, substitute `` with the domain and path to your WorkflowGen instance; for example, `localhost/wfgen` or `mycompany.com/wfgen`. {% hint style="info" %} * ME-ID user passwords are not provisioned. * Only one WorkflowGen directory can be provisioned by ME-ID. * If you're using ME-ID SCIM user provisioning, you should **disable** the WorkflowGen Directory Synchronization Service (e.g. `WfgDirectoriesSyncService.exe`) if it's been installed and started. {% endhint %} ## Prerequisites * Make sure to have a working WorkflowGen instance within a network reachable by ME-ID with the **HTTPS** (recommended) or **HTTP** ports opened. * Make sure to know the address of the instance. * Make sure that the WorkflowGen instance is running. * Make sure that the SCIM application is properly installed and configured. For instructions on how to do this, see [Enabling WorkflowGen SCIM](https://docs.workflowgen.com/tech/setup/manual-installation#enabling-workflowgen-scim) in the [WorkflowGen Node.js-based applications](https://docs.workflowgen.com/tech/setup/manual-installation#workflowgen-node.js-based-web-applications) section in the WorkflowGen Technical Guide. * A P2 license must be activated in the ME-ID tenant. {% hint style="info" %} ME-ID requires that the WorkflowGen website link be publicly accessible. {% endhint %} ## WorkflowGen configuration This section provides instructions on how to define a new directory that will be used by ME-ID to synchronize users and groups. Once you've made sure you've met the prerequisites, you can proceed with configuring WorkflowGen to receive information from ME-ID. {% hint style="info" %} Before going further with the configuration, make sure that the **`EngineServiceImpersonificationUsername`** key in the WorkflowGen `web.config` is set to an existing Administrator username. Otherwise, the synchronization connector won't have sufficient permissions to make all of the requests needed to provision users and groups. {% endhint %} ### Create and configure an ME-ID SCIM v2 directory 1. In the WorkflowGen Administration Module (`https:///admin`), click **Directories**, then click **New directory** on the **Directories** screen.
2. Enter a name and a description for the directory.
3. From the **Directory connector** drop-down list, select **Azure AD SCIM v2**.
✏️ **Note:** You can only have one SCIM directory per WorkflowGen instance.
4. Click **Save** to create the directory.
5. Copy the generated **SCIM token** value, since you'll need it for the next step. ## Microsoft Entra ID configuration This section provides the steps for configuring a typical enterprise application with ME-ID in order to provision your WorkflowGen instance with users and groups. {% hint style="info" %} **Note on existing WorkflowGen instances** If you've already synchronized a WorkflowGen instance with an enterprise application in ME-ID (or Azure AD), **don't re-use the same enterprise application with another WorkflowGen instance**. Instead, create a new enterprise application for each new WorkflowGen instance you want to synchronize. {% endhint %} ### Step 1: Create a new enterprise application In order to provision WorkflowGen, you have to register it in the Microsoft Entra admin center, which is done by adding a new enterprise application. To do this: 1. In your Azure portal, go to the **Enterprise applications** page, then click **New application**.
2. In the **Browse Microsoft Entra Gallery** page, click **Create your own application**, then select `Integrate any other application you don't find in the gallery (Non-gallery)`
3. Enter a name for the application. Typically, you'd want to give it a name like `WorkflowGen SCIM v2` in order to identify it easily.
4. Click **Create**. You can now proceed to configure the ME-ID application to provision WorkflowGen. ### Step 2: Configure the Microsoft Entra ID application #### **Establish a connection between WorkflowGen and Microsoft Entra ID** Click **Provision User Accounts** on the application page, then click **Get started** on the **Overview** page**.** All of the remaining configurations will be done here. To set up the connection between WorkflowGen and ME-ID: 1. Choose **Automatic** provisioning mode.
2. Click **Admin Credentials**. In the **Tenant URL** field, add your WorkflowGen SCIM URL `https:///scim` (e.g. `https://mycompany.com/wfgen/scim`).
✏️ **Note:** If your WorkflowGen base domain already points to the WorkflowGen instance, don't include the `wfgen` part of the address.
3. In the **Secret Token** field, paste the **SCIM token** value that WorkflowGen generated earlier when you created the new SCIM directory.
4. Click **Test Connection** and wait for the results. If all goes well, you'll receive a notification along with additional options.
5. Click **Save** at the top of the page. #### **Configure the provisioning** Two new sections should now appear: **Mapping** and **Settings**. You'll need to change some mappings in order to correctly match the corresponding data in WorkflowGen, and to reduce the possibility of errors. ***Groups*** Click the option that contains **Groups** to change the mapping for groups. Then, in the new page, go to the **Attribute Mappings** section and keep only the `externalId`, `displayName`, and `members` mappings set to `customappsso`. You'll also need to change the mapping of `externalId` to ME-ID's `objectId` if it is not correctly mapped already. This will prevent two different groups from being provisioned with the same `externalId`. This attribute must be unique. You also have the ability to customize which operations should be executed in the WorkflowGen directory. If you're starting from scratch, you should leave **Create**, **Update**, and **Delete** enabled to make sure that Azure can perform any operation it needs to keep WorkflowGen in sync with ME-ID. The final mapping should resemble the following table. If you have any additional mappings that aren't listed here, you should **delete** them, because they won't be mapped in WorkflowGen. | **ME-ID attribute** | **customappsso attribute** | **WorkflowGen group** | | ------------------- | -------------------------- | --------------------- | | `objectId` | `externalId` | `systemIdentifier` | | `mailNickname` | `displayName` | `name` | | `members` | `members` | `users` | {% hint style="info" %} * The **ME-ID attribute** column corresponds to the group's attributes defined in Microsoft Entra. * The **customappsso attribute** column corresponds to the group's attributes defined in the SCIM specification (e.g. `urn:ietf:params:scim:schemas:core:2.0:Group`). * The **WorkflowGen group** column corresponds to the group fields and properties that will be updated in WorkflowGen. {% endhint %} Once you've set all of the group mappings, click **Save** again. ***Users*** You also need to modify the user mappings. To do this, return to the **Provisioning** options for the enterprise application, then click the button for user mappings in the **Mappings** section. In the **Attribute Mappings** section of the new page, you only need to change the mapping of `externalId` to ME-ID's `objectId`. You also have the ability to customize which operations should be executed in the WorkflowGen directory. If you're starting from scratch, you should leave **Create**, **Update**, and **Delete** enabled to make sure that Microsoft Entra ID can perform any operation it needs to keep WorkflowGen in sync with it. The final mapping should resemble the following table. If you have any additional mappings that aren't listed here, you should **delete** them, because they won't be mapped in WorkflowGen. | **ME-ID attribute** | **customappsso attribute** | **WorkflowGen user** | | ------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------- | | `Switch([IsSoftDeleted], , "False", "True", "True", "False")` | `active` | `isActive` | | `displayName` | `displayName` | `commonName` | | `FacsimileTelephoneNumber` | `phoneNumbers[type eq "fax"].value` | `fax` | | `givenName` | `name.givenName` | `firstName` | | `jobTitle` | `title` | `jobTitle` | | `mail` | `emails[type eq "work"].value` | `email` | | `objectId` | `externalId` | `systemIdentifier` | | `manager` | `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager` | `manager` | | `mobile` | `phoneNumbers[type eq "mobile"].value` | `mobile` | | `postalCode` | `addresses[type eq "work"].postalCode` | `postalCode` | | `physicalDeliveryOfficeName` | `addresses[type eq "other"].Formatted` | `office` | | `streetAddress` | `addresses[type eq "work"].streetAddress` | `postalAddress` | | `surname` | `name.familyName` | `lastName` | | `telephoneNumber` | `phoneNumbers[type eq "work"].value` | `phone` | | `userPrincipalName` | `userName` | `userName` | {% hint style="info" %} * The **ME-ID attribute** column corresponds to the user's attributes defined in Microsoft Entra. * The **customappsso attribute** column corresponds to the user's attributes defined in the SCIM specification (e.g. `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`). * The **WorkflowGen user** column corresponds to the user fields which will be updated in WorkflowGen. {% endhint %} Once you've set all of the user mappings, click **Save**. ### Step 3: Launch the synchronization You're now ready to launch the synchronizations of users and groups with your WorkflowGen instance. To do this, go to the **Settings** section of your enterprise application's **Provisioning** page. If you want to synchronize only a subset of your ME-ID users and groups, select the `Sync only assigned users and groups` scope, then manually assign them to this application in the directory. To do this, go to the application's **Users and groups** section and manually add your users there. You can also configure the application to synchronize all of your directory's users and groups. In this case, select the `Sync all users and groups` scope. Once you're ready, change the provisioning status to **On**, then click **Save**. {% hint style="success" %} You've now finished configuring the user and group provisioning from Microsoft Entra ID to WorkflowGen using the SCIM v2 protocol. In WorkflowGen, you can review the provisioning in the synchronization logs in the Administration Module, or in the log files created by the WorkflowGen SCIM API, located in WorkflowGen's `APP_DATA` directory. {% endhint %} ## Migrating from classic Active Directory to Microsoft Entra ID If you already have a synchronization with a classic AD, this section provides instructions on how to migrate your WorkflowGen users to your new Microsoft Entra ID without having to delete then re-create them. ### About Microsoft Entra ID provisioning First, it's important to understand how Microsoft Entra ID synchronizes your directory through the SCIM connector before going ahead with a migration. In this guide, we've changed the default mapping between ME-ID object properties and SCIM properties. One of these is the `externalId` SCIM property, which represents a unique identifier from an external system, so it must be opaque for WorkflowGen. This guide has you change this mapping from `displayName` in ME-ID to `objectId`. In WorkflowGen, `externalId` maps to a user's `systemIdentifier` property; therefore, the `objectId` value from ME-ID is being provisioned into the `systemIdentifier` value in WorkflowGen. Second, ME-ID begins the synchronization by interrogating the SCIM connector to find existing users. It begins by sending GET requests with its `objectId` values. Since WorkflowGen doesn't have any `Id` that corresponds to ME-ID's `objectId`, it will always fail with a `404 NOT FOUND` error. Then, it sends GET requests but with a filter on `externalId`, and this time, it will find users in WorkflowGen if their `systemIdentifier` matches a user's `objectId` in ME-ID. ### How to migrate users and groups to Microsoft Entra ID 1. Deactivate the classic Active Directory synchronization connector.
2. Create a new Azure SCIM v2 directory connector.
3. Move the users and groups already in Active Directory from other existing WorkflowGen directories to the SCIM directory.
4. Create a script that will update users and groups in the SCIM directory with their `systemIdentifier` properties set to their corresponding ME-ID `objectId` properties. This example contains an algorithm that links users and groups to ME-ID: ``` groups = fetch_groups_from_azure() for group in groups: for user in group.users: wfgUser = fetch_wfg_user_with_key(user.something) wfgUser.systemIdentifier = user.objectId update(wfgUser) wfgGroup = fetch_wfg_group_with_key(group.something) wfgGroup.systemIdentifier = group.objectId update(wfgGroup) ``` This example contains an algorithm that links only users to ME-ID: ``` users = fetch_users_from_azure() for user in users: wfgUser = fetch_wfg_user_with_key(user.something) wfgUser.systemIdentifier = user.objectId update(wfgUser) ``` ## Troubleshooting ### Users and groups are marked as skipped in ME-ID's synchronization logs If you encounter this issue, it might be because the users and groups are outside the scope of the synchronization. The reason could be that you didn't assign users to the enterprise application and you selected a scope of assigned users only. To resolve this, assign users to the enterprise application by going into its **Users and groups** section. You can also change the scope of the synchronization to all of the directory's users and groups by editing the enterprise application's synchronization settings. Another possible cause might be related to other configurations in your Microsoft Entra ID. For more troubleshooting steps, see the [No users are being provisioned](https://docs.microsoft.com/en-ca/azure/active-directory/app-provisioning/application-provisioning-config-problem-no-users-provisioned?WT.mc_id=UI_AAD_Enterprise_Apps_Support_L2_Overview#provisioning-logs-say-users-are-skipped-and-not-provisioned-even-though-they-are-assigned) Microsoft article.