Azure AD Synchronization

Overview

This section provides instructions on how to configure the WorkflowGen Azure Active Directory (AD) synchronization connector, which relies on Azure AD user provisioning features. Users and groups are automatically updated (pushed to WorkflowGen) by Azure AD (every 20 to 40 minutes) using the SCIM v2 protocol. Azure user passwords are not synchronized. An Azure Premium P2 license is required to enable the user provisioning feature. Only one WorkflowGen directory can be synchronized by Azure.

In the instructions, substitute <workflowgen url> with the domain and path to your WorkflowGen instance; for example, localhost/wfgen or www.mycompany.com/wfgen.

Note: If you're using Azure AD SCIM user provisioning, you should disable the WorkflowGen Directory Synchronization Service if it's been installed and started.

Prerequisites

  • Make sure to have a working WorkflowGen instance within a network reachable by Azure AD with the HTTPS or HTTP ports opened.

  • Make sure to know the address of the instance.

  • Make sure to have run an npm install --production in the scim folder.

  • Make sure that the WorkflowGen instance is running.

  • An Azure Premium P2 license must be activated in the Azure Active Directory tenant.

WorkflowGen configuration

This section provides instructions on how to define a new directory that will be used by Azure AD 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 Azure AD.

Note: Before going further with the configuration, make sure that the EngineServiceImpersonificationUsername parameter in the WorkflowGen web.config is set to an existing Administrator username. Otherwise, the synchronization connector won't have sufficient privileges to make all of the requests needed to provision users and groups.

Create and configure an Azure AD SCIM v2 directory

  1. In the WorkflowGen Administration Module (https://<workflowgen url>/admin), click Directories, then click New directory on the Directories screen.

  2. Enter a name and a description for the directory.

    Important: Don't check the User password option, since authentication will be managed by Azure AD.

  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. Copy the generated token, since you'll need it for the Azure AD configuration.

  5. Click Save to create the directory.

Azure Active Directory configuration

This section provides the steps for configuring a typical enterprise application with Azure AD in order to provision your WorkflowGen instance with users and groups.

Note on existing WorkflowGen instances

If you've already synchronized a WorkflowGen instance with an enterprise application in 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.

Step 1: Create a new enterprise application

In order to provision WorkflowGen, you have to register it in the Azure AD portal, which is done by adding a new enterprise application. To do this:

  1. On the Azure Active Directory pane in your Microsoft Azure portal, click Enterprise applications, then click New application.

  2. In the Add an application pane, click Non-gallery application.

  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 Add.

You can now proceed to configuring the application to provision WorkflowGen.

Step 2: Configure the Azure AD application

Establish a connection between WorkflowGen and Azure AD

Click Provisioning on the application page. All of the remaining configuration will be done here.

To set up the connection between WorkflowGen and Azure AD:

  1. Choose Automatic provisioning mode.

  2. For the Tenant URL, add your WorkflowGen address (e.g. https://<workflowgen url>/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 token 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.

Configure the provisioning

Two new sections should now be available: 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 member mappings set to customappsso. You'll also need to change the mapping of externalId to Azure AD's objectId. This will prevent two different groups from being provisioned with the same externalId. This attribute must be unique.

This table lists the default mappings for groups:

Azure AD group

urn:ietf:params:scim:schemas: core:2.0:Group

WorkflowGen group

displayName

externalId

systemIdentifier

mail

emails[type eq "work"].value

Not mapped

mailNickname

displayName

name

members

members

users

objectId

id

Not mapped

proxyAddresses

emails[type eq "other"].Value

Not mapped

Once you've set all of the group mappings, click Save.

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 Azure AD's objectId.

This table lists the default mappings for users:

Azure AD user

urn:ietf:params:scim:schemas: extension:enterprise:2.0:User

WorkflowGen user

IsSoftDeleted

active

isActive

displayName

displayName

commonName

Facsimile-TelephoneNumber

phoneNumbers[type eq "fax"].value

fax

givenName

name.givenName

firstName

jobTitle

title

jobTitle

mail

emails[type eq "work"].value

email

mailNickname

externalId

systemIdentifier

manager

manager

manager

mobile

phoneNumbers[type eq "mobile"].value

mobile

objectId

id

Not mapped

postalCode

addresses[type eq "work"].postalCode

postalCode

proxy-Addresses

emails[type eq "other"].Value

Not mapped

physical-Delivery-OfficeName

addresses[type eq "other"].Formatted

office

streetAddress

addresses[type eq "work"].streetAddress

postalAddress

surname

name.familyName

lastName

telephone-Number

phoneNumbers[type eq "work"].value

phone

user-PrincipalName

userName

userName

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 Azure AD users and groups, select the option to synchronize assigned users and groups, 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. Again, select the correct scope to do this.

Once you're ready, change the provisioning status to On, then click Save.

You've now finished configuring the user and group provisioning from Azure AD 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.

Migrating from classic Active Directory to Azure Active Directory

If you already have a synchronization with a classic AD, this section provides instructions on how to migrate your WorkflowGen users to your new Azure AD without having to delete then re-create them.

About Azure Active Directory provisioning

First, it's important to understand how Azure AD synchronizes your directory through the SCIM connector before going ahead with a migration. In this guide, we've changed the default mapping between Azure AD 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 Azure AD to objectId. In WorkflowGen, externalId maps to a user's systemIdentifier property; therefore, the objectId value from Azure AD is being provisioned into the systemIdentifier value in WorkflowGen.

Second, Azure AD 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 Azure AD'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 Azure AD.

How to migrate users and groups to Azure Active Directory

  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 Azure AD 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 Azure AD objectId properties.

This example contains an algorithm that links users and groups to Azure AD:

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 Azure AD:

users = fetch_users_from_azure()
for user in users:
wfgUser = fetch_wfg_user_with_key(user.something)
wfgUser.systemIdentifier = user.objectId
update(wfgUser)