7.11

Azure Integration

Overview

This section provides instructions on:

It also provides additional information on SOAP services support, session management, and current limitations.

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

Azure Active Directory synchronization

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 P1 license is required to enable the user provisioning feature. Only one WorkflowGen directory can be synchronized by Azure.

As mentioned, it's Azure AD that pushes the data to WorkflowGen. The nature of the protocol doesn't allow WorkflowGen to update in any way the directory in Azure. In other words, it's Azure that queries WorkflowGen for information, not the other way around. This means that the Active Directory is the only source of truth for users and groups for the system.

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 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 in the WorkflowGen Node.js-based applications section.

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

Azure requires that the WorkflowGen website link be publicly accessible.

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.

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 the Active Directory.

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.

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.

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 the Active Directory.

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.

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)

Troubleshooting

Users and groups are marked as skipped in Azure'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 Azure Active Directory. For more troubleshooting steps, see the No users are being provisioned Microsoft article.

Azure Active Directory authentication

This section provides instructions on how to configure WorkflowGen delegated authentication with Azure AD authentication API endpoint v1, and will show you how to set up a working WorkflowGen instance that uses Azure to authenticate your users.

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

Prerequisites

  • Make sure to have a licensed copy of WorkflowGen installed and running on a server. You must be a WorkflowGen administrator.

  • Make sure to have Azure AD administrator access to be able to configure Azure AD.

  • Make sure to have provisioned an existing Azure AD user that you can authenticate with to WorkflowGen and that the user has administrator privileges. This is important because once you've activated the delegation, you'll still need to be able to manage the application.

  • AES encryption mode and its key are required for the authentication to work.

Azure Active Directory configuration

The configuration of Azure AD is done in two steps. First, you have to register the WorkflowGen web application and link it to your instance of WorkflowGen; then, you have to register the WorkflowGen GraphQL API to be able to register custom applications to access it.

Step 1: Create a new application registration for WorkflowGen

  1. In the Azure portal, click App registrations in the Azure Active Directory section.

  2. Click New registration, and fill in the properties form:

    • Name: WorkflowGen Web app

    • Supported account type: Account in this organizational directory only

    • Redirect URI:

      • Type: Web

      • Value: https://<workflowgen url>/auth/callback

      Note: Depending on the context, you should choose the right option for your use case for the Supported account type value. Example: https://mycompany.com/wfgen/auth/callback

  3. Click Register at the bottom of the page.

You should now see the WorkflowGen registered application's overview page.

Step 2: Create a client secret for the application

Now, you have to generate a client secret to use in the WorkflowGen Authentication Module.

  1. Click Certificates & secrets.

  2. In the Client secrets section, add a new client secret.

    • DESCRIPTION: secret, or something to know that this is the client secret.

    • EXPIRES: Choose Never.

    • VALUE: Anything with sufficient entropy that it can't be guessed, such as a UUID.

  3. Click Save. The value you entered will now be encrypted.

  4. Save the generated value, since you won't be able to retrieve it afterwards.

Step 3: Add a redirect URI

In order for the communication between WorkflowGen and Azure to work, you need to add one more authorized redirect URI to the registered WorkflowGen Web app web application.

  1. Click Authentication.

  2. In the Redirect URIs section, enter the following information:

    • Type: Web

    • Redirect URI: https://<workflowgen url>/auth/logout/return Example: https://mycompany.com/wfgen/auth/logout/return Note: You should also see https://<workflowgen url>/auth/callback in this list.

  3. Click Save at the top of the section.

Step 4: Create a new application registration for the WorkflowGen GraphQL API

In order to expose the GraphQL API, you need to add a new application that will represent it. To do this:

  1. In the Azure portal, click App registrations in the Azure Active Directory section.

  2. Click New registration, and fill in the properties form:

    • Name: WorkflowGen GraphQL

    • Supported account type: Account in this organizational directory only

  3. Click Register at the bottom of the page.

You've now successfully registered the GraphQL API in Azure AD.

Step 5: Expose the API in the WorkflowGen GraphQL API application registration

  1. Click Expose an API.

  2. To the right of Application ID URI, click Set and enter the URI https://<workflowgen url>/graphql. Example: https://mycompany.com/wfgen/graphql

  3. Click Add a scope and enter the following information:

    • Scope name: default

    • Who can consent?: Admins and users

    • Admin consent display name: Default access to the GraphQL API

    • Admin consent description: Allows the application to get access to WorkflowGen's GraphQL API.

    • User consent display name: Use the admin consent display name

    • User consent description: Use the admin consent description

  4. Click Add scope.

  5. Click Save.

Since October 2021, Azure AD requires the use of a default schema or a verified domain for the AppId URL on single tenant application (see the Microsoft documentation here for more information). The Microsoft documentation on how to add and verify a custom domain is available here.

Step 6: Give access to WorkflowGen

  1. On the WorkflowGen application registration page, click API permissions.

  2. Click Add a permission, then My APIs.

  3. Click WorkflowGen GraphQL API in the list.

  4. Click Delegated permissions and check default.

  5. Click Add permissions.

Review the registrations

You should now have all of the information you need to configure WorkflowGen to delegate authentication to Azure AD. Here's a review:

  • A client ID. This is the application ID of the registered WorkflowGen app on Azure. You can find it on its overview page.

  • A client secret. This is the secret previously generated.

  • An audience. This is the Application ID URI property in the Expose an API section.

  • The metadata endpoint. This URL is bound to your Azure directory. To find it:

    1. Go to your directory properties section.

    2. Copy the Tenant ID value.

    3. The metadata endpoint is built like this: 

      https://login.microsoftonline.com/<Tenant ID>/.well-known/openid-configuratio

By now you should have all the information needed to link your WorkflowGen instance to Azure AD.

WorkflowGen configuration

Now, you have to configure WorkflowGen to delegate its authentication to Azure AD.

Step 1: Add Azure AD values to the WorkflowGen web.config

  1. Open the WorkflowGen web.config file and add the following properties under <appSettings>.

    <!-- Azure v1 auth -->
<add key="ApplicationSecurityAuthProvider" value="azure-v1"/>
<add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" />
<add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" />
<add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" />
<add key="ApplicationSecurityAuthCheckSessionUrl" value="<CHECK SESSION URL>" />
<add key="ApplicationSecurityAuthAppIdClaim" value="appid" />
<add key="ApplicationSecurityAuthUsernameClaim" value="upn" />
<add key="ApplicationSecurityAuthClockTolerance" value="60" />
<add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/>

  2. Replace <CLIENT ID> with the application ID.

  3. Replace <CLIENT SECRET> with the the WorkflowGen registered application's generated secret on Azure.

  4. Replace <METADATA URL> with the URL that you built earlier from the Tenant ID value of your Azure AD directory.

  5. Replace <CHECK SESSION URL> with the value of the metadata endpoint's check_session_iframe property. To do this, you'll have to make a request to the <METADATA URL>, then copy and paste the value. (See the table below for more information about this property.)

    Linux/macOS request example:

    curl "<METADATA URL>" | python -m json.tool

    (Note: Remove | python -m json.tool if you don't have Python; this is for pretty printing.)

    Windows PowerShell request example:

    Invoke-RestMethod -Uri "<METADATA URL>" -Method GET | ConvertTo-JSON

Table of web.config options

WorkflowGen is now linked to Azure AD and back. The last thing left to do is configure a few more options in order to finish the internal wiring of WorkflowGen so that it can delegate its authentication.

Step 2: Add security values for session generation

In order to generate a session token, you need to add a few more settings to the web.config.

  1. Open the WorkflowGen web.config file and add the following property under <appSettings>:

     <!-- Auth -->
 <add key="ApplicationSecurityAuthSessionTokenSigningSecret" value="<SECRET>" />

  2. Replace <SECRET> with a value that can't be guessed, such as a UUID.

The secret will be only accessible inside your instance of WorkflowGen, so when generating a session token, WorkflowGen will sign it with this secret in order to check the validity of all session tokens passed to it.

Step 3: Activate the authentication delegation

You now need to activate the delegation by replacing the authentication system in IIS and pointing WorkflowGen's modules to the correct authentication module.

Configure IIS

  1. In IIS Manager, click on the WorkflowGen application in the tree view.

  2. Click the Authentication button.

  3. Enable Anonymous Authentication, and disable all other authentications.

  4. Perform these steps for all sub-applications as well.

Add properties to the web.config files of certain modules

Certain modules need to have their authentication checked by the special Advantys.Security.JWTAuthenticationModule WorkflowGen authentication module, but certain other modules should not because they are either public or aren't part of the global authentication system.

  1. Add the following property to the WorkflowGen web.config file:

    <?xml version="1.0" encoding="UTF-8"?>
<configuration>
 <system.webServer>
     <modules>
         <add name="ApplicationSecurityAuthenticationModule" type="Advantys.Security.Http.JWTAuthenticationModule" />
     </modules>
 </system.webServer>
</configuration>

  2. If you have developed custom web forms with their own \bin folders, you have to copy the following .NET assemblies and dependency libraries from \wfgen\bin to each custom web form's \bin folder (\wfgen\wfapps\webforms\<custom webform>\bin):

    • Advantys.My.dll

    • Advantys.Security.dll

    • Newtonsoft.Json.dll

    • jose-jwt.dll

You should now have a working WorkflowGen instance with the authentication delegated to Azure AD through the OpenID Connect protocol. Make sure to have provisioned your users to WorkflowGen in order for them to successfully access WorkflowGen.

Azure Active Directory configuration for mobile apps

Mobile applications must use an approach similar to that of regular web applications, which is called Authorization Code Flow with Proof Key for Code Exchange (PKCE). The main difference between this and the classic Authorization Code Flow is that the mobile application doesn't get a client secret, but instead exchanges a pair of codes to prove the origin of the authentication attempt. The issue is that a mobile application can't be trusted with a client secret because it's distributed directly to users and is therefore no longer under the developer's control, and the sources can be decompiled and analyzed to find secrets like this.

This section provides instructions on how to configure Azure AD for mobile apps so that your mobile users can benefit from delegated authentication as well.

For instructions on how to generate a universal link to simplify the Azure AD login process for your users, see the Generating a universal link for WorkflowGen Plus section.

Prerequisites

  • Make sure to have a licensed copy of WorkflowGen installed and running on a server.

  • Make sure to have administrative access to Azure AD to be able to configure it properly.

  • Make sure to have provisioned an existing Azure AD user with which you can authenticate to WorkflowGen so that you can use the application afterwards.

  • Make sure to have successfully configured delegated authentication to Azure AD on your WorkflowGen instance following the instructions in the Azure Active Directory authentication section.

Azure Active Directory configuration

This configuration is done in several steps. First, you have to register a new native application in Azure AD. Then, you have to give the application the necessary permissions to access the WorkflowGen GraphQL API. Finally, you have to register the correct callback URLs that will redirect within the native application.

Step 1: Register a new native application

  1. In the Azure portal, click App registrations in the Azure Active Directory section.

  2. Click New application registration, and fill in the properties:

    • Name: WorkflowGen Plus

    • Application type: Native

    • Redirect URI: workflowgenplus://auth.authorize/azure-v1

  3. Click Create at the bottom of the page.

You should now see the WorkflowGen Plus registered application's overview page.

Step 2: Grant access to the WorkflowGen GraphQL API

  1. Click Settings.

  2. In the API Access section, click Required permissions, then click Add.

  3. Click Select an API.

  4. Search for the WorkflowGen GraphQL API application that you registered and select it.

  5. Click Select permissions, then check Access WorkflowGen under Delegated Permissions to grant access to the API.

  6. Click Select.

You should now see the WorkflowGen GraphQL API listed in the list of required permissions alongside Windows Azure Active Directory.

Step 3: Add the necessary redirect URIs

  1. Click Settings, then click Redirect URIs.

  2. Add the workflowgenplus://auth.authenticate/azure-v1 and workflowgenplus://auth.deauthenticate/azure-v1 URIs to the list.

  3. Click Save.

You've now successfully registered the WorkflowGen Plus mobile application to your Azure AD.

Review the registration

Take note of the information you'll need later on:

  • The application's client ID, which you can find on the registration's overview page as the Application ID.

  • Your directory's tenant ID, which you can find in the Active Directory section's property sub-section as the Tenant ID.

You'll need to give these IDs to the users who will be using the mobile application. Delegated authentication won't work unless they copy the IDs into the app.

Azure Active Directory configuration for server-side scripts

In some cases, you'll want to perform a specific task that can be automated but needs access to the WorkflowGen GraphQL API; this use case is often in the form as a server-side script. For this, OAuth2 provides a type of grant called Client Credentials that simply exchanges a client ID and secret for an access token. There is no ID token since it's not part of the OpenID Connect standard and there's no user involved.

This section provides instructions on how to configure Azure AD with a server-side script that has access to the GraphQL API. First, you'll need to configure a new web application in the Azure portal; then, you'll need to configure a new application in WorkflowGen.

Prerequisites

  • Make sure to have a licensed copy of WorkflowGen installed and running on a server.

  • Make sure to have administrative access to WorkflowGen.

  • Make sure to have administrative access to Azure Active Directory to be able to configure it properly.

  • Make sure to have successfully configured delegated authentication to Azure AD on your WorkflowGen instance following the instructions in the Azure Active Directory authentication section.

Azure AD configuration

Step 1: Register a new web application

  1. In the Azure portal, click App registrations in the Azure Active Directory section.

  2. Click New application registration, and fill in the properties:

    • Name: Your script name

    • Application type: Web App / API

    • Sign-on URL: This isn't needed, since there's no login involved.

  3. Click Create at the bottom of the page.

You've now successfully registered your script in Azure Active Directory.

Step 2: Grant access to the GraphQL API

  1. On the application's overview page, click Settings.

  2. In the API Access section, click Required permissions, then click Add.

  3. Click Select an API.

  4. Search for the WorkflowGen GraphQL API and select it.

  5. Click Select permissions, then check all of the checkboxes.

  6. Click Select.

You should now see the WorkflowGen GraphQL API in the list of required permissions.

Step 3: Generate a key

  1. Return to the application's overview page, then click Settings.

  2. In the Keys section, enter a new key with the following properties:

    • Description: client_secret (or something that clearly identifies that it's a secret)

    • Expires: Never expires

    • Value: A string that represents the secret. Make sure that it has sufficient entropy so that it can't be guessed, such as a UUID.

  3. Click Save.

  4. Copy and save the value generated by Azure. This is your client secret, and you won't be able to retrieve it later.

Review the registration

Here's a review of the information you need:

  1. A client ID, which can be found on the registered application settings tab.

  2. A client secret, which can be found on the registered application settings tab.

  3. Your Azure AD's tenant ID, which can be found in the properties sub-section in the Active Directory section in the portal.

  4. The WorkflowGen GraphQL API's application ID, which can be found on its overview page.

You're now ready to register your script in WorkflowGen.

WorkflowGen configuration

As with user provisioning, WorkflowGen needs to know which application is accessing the GraphQL API. Therefore, you have to register the application, which consists of your script.

Register a new application

  1. On the Applications page in the WorkflowGen Administration Module, click New application.

  2. Fill in the form:

    • Name: My Server Application

    • Description: A description that clearly identifies the script

    • Type: Non-interactive Client

    • Impersonate username: Any username that has the required access to the GraphQL API

    • Client ID: The client ID you retrieved earlier

    • Active: Check this checkbox

  3. Click Save.

Your application should now appear in the list of applications.

You should now have the necessary components in place to make GraphQL API requests with your script by passing the access token received from Azure AD from a Client Credentials Grant flow.

Azure Active Directory configuration for single-page applications

JavaScript applications running in a browser are often hard to secure due to the open nature of the Web. Secure storage is nonexistent, and everything is in clear text (for HTTP version 1.1). Here's a quote from the Azure Active Directory team that summarizes the state of authentication with single-page applications:

The OAuth2 implicit grant is notorious for being the grant with the longest list of security concerns in the OAuth2 specification. And yet, that is the approach implemented by ADAL JS and the one we recommend when writing SPA applications. What gives? It’s all a matter of tradeoffs: and as it turns out, the implicit grant is the best approach you can pursue for applications that consume a Web API via JavaScript from a browser.

(Source: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant)

It's therefore important that you make all of the necessary checks to verify the validity of your requests and the responses.

This section provides instructions on how to configure Azure AD with a single-page application (SPA) so that users can authenticate through it and make requests to the WorkflowGen GraphQL API. This configuration is done in three steps: registering your SPA, granting access to the API, and setting some redirect URLs.

Prerequisites

  • Make sure to have a licensed copy of WorkflowGen installed and running on a server.

  • Make sure to have administrative access to Azure AD to be able to configure it properly.

  • Make sure to have provisioned an existing Azure AD user with which you can authenticate to WorkflowGen so that you can use the application afterwards.

  • Make sure to have successfully configured delegated authentication to Azure AD on your WorkflowGen instance following the instructions in the Azure Active Directory authentication section.

Azure Active Directory configuration

Step 1: Register a new web application

  1. In the Azure portal, click App registrations in the Azure Active Directory section.

  2. Click New application registration, and fill in the properties:

    • Name: Your SPA name

    • Application type: Web app / API

    • Sign-on URL: https://<your SPA login url>

  3. Click Create at the bottom of the page.

You should now be in your newly registered application's overview page.

Step 2: Grant access to the GraphQL API

Now that you've successfully registered your SPA, you need to grant it access to the WorkflowGen API, which should be already registered if you've met the prerequisites.

  1. Click Settings.

  2. In the API Access section, click Required permissions, then click Add.

  3. Click Select an API.

  4. Search for the WorkflowGen GraphQL API application that you registered and select it.

  5. Click Select permissions, then check all of the checkboxes.

  6. Click Select.

You should now see the WorkflowGen GraphQL API in the list of your registered SPA's required permissions. Therefore, when requesting an access token to Azure, based on the audience you should be able to obtain a correct token that you will send to your WorkflowGen instance's GraphQL API in addition to the request.

Azure SQL database configuration

This section provides instructions on how to create and configure your Azure SQL database.

Create the Azure SQL database

The Azure SQL database instance has to be created in the Azure Portal. See Create an Azure SQL database in the Azure portal for more information on how to create the database. Once you've completed the instructions, you'll have:

  • The name of the Azure SQL server,

  • The credentials of the administrator account,

  • A server-level firewall rule for your IP address server, and

  • The name of the Azure SQL database.

Step 1: Configure the Azure SQL database

  1. Connect to your Azure SQL database instance with the administrator account you created by using the SQL Database Query Editor in Azure Portal or SQL Management Studio.

  2. You have to create a SQL Server user account with db_datareader and db_datawriter permissions. See How to create a non-administrator user account, or run the following script in the SQL Database Query Editor or SQL Management Studio (the master database must be selected):

     -- Replace <database name>, <database user>, and <password> with the ones you choose (e.g. WFGEN, wfgen_user, Admin123!)
 -- Create SQL Login template for Azure SQL Database and Azure SQL Data Warehouse Database

 CREATE LOGIN <database user>
     WITH PASSWORD = '<password>' 
 GO

 -- Create SQL Login template for Azure SQL Database and Azure SQL Data Warehouse Database

 CREATE USER <database user>
     FROM LOGIN <database user>
     WITH DEFAULT_SCHEMA = <database name>
 GO

 -- Add user to the database owner role
 EXEC sp_addrolemember N'db_datawriter', N'<database user>'
 EXEC sp_addrolemember N'db_datareader', N'<database user>'
 GO

  3. Get the database creation script by downloading the latest WorkflowGen manual installation pack and extracting it to DRIVE:\temp.

  4. Open the DRIVE:\temp\pack\Databases\MsSQLServer source folder and run the following database creation SQL scripts on the new database instance in the following order:

    1. Create_WFG-V7-0_SQL_Tables.sql

    2. Create_WFG-V7-0_SQL_PKeys.sql

    3. Create_WFG-V7-0_SQL_FKeys.sql

    4. Create_WFG-V7-0_SQL_Indexes.sql

    5. Create_WFG-V7-0_SQL_Triggers.sql

    6. Create_WFG-V7-0_SQL_Const.sql

Step 2: Configure WorkflowGen

Open the WorkflowGen web.config file and add the following node under <connectionStrings>:

<add name="MainDbSource" connectionString="Data Source=<server name>;Initial Catalog=<database name>;User ID=<database user>;Password=<password>;encrypt=true;trustServerCertificate=false;" providerName="System.Data.SqlClient" />

  • Replace <server name> with the server name (e.g. workflowgen.database.windows.net).

  • Replace <database name> with the database name (e.g. WFGEN).

  • Replace <database user> with the database user (e.g. wfgen_user).

  • Replace <password> with the database user's password (e.g. Admin123!).

Note: We highly recommend that you add encrypt=true and trustServerCertificate=false; to the connectionString in order to establish a secure connection to the database.

Read Scale-Out (Preview)

This section provides instructions on how to configure the optional Read Scale-Out feature, which allows load balancing of SQL Database read-only workloads using a read-only replica rather than a read-write replica. For more information on this feature, see the Use read-only replicas to load balance read-only query workloads (preview) Microsoft article.

Prerequisites

  • Make sure to have either a Premium or a Business Critical service tier.

  • You must have permissions to make changes to the database in the Azure portal.

Step 1: Enable the Read Scale-Out feature in PowerShell

  1. Install or update the Azure PowerShell module in PowerShell by running the following commands:

     Install-Module -Name AzureRM -AllowClobber
 Import-Module -Name AzureRM

    For more information, see Install Azure PowerShell on Windows with PowerShellGet.

  2. Log in to your Microsoft Azure account in PowerShell by running the following command:

     Login-AzureRmAccount

    If you encounter any security issues with the Microsoft Azure sign-in process, then you must manually add https://login.microsoftonline.com/ and all related websites' URIs to the Trusted sites zone in Internet Explorer's Internet Options.

  3. Enable the Read Scale-Out feature in PowerShell by running the following command:

    Set-AzureRmSqlDatabase -ResourceGroupName <resource group> -ServerName <server name> -DatabaseName <database name> -ReadScale Enabled

    • Replace <resource group> with the resource group name.

    • Replace <server name> with the server name (e.g. workflowgen.database.windows.net).

    • Replace <database name> with the database name (e.g. WFGEN).

You can also enable Read Scale-Out feature using the Azure SQL Database Rest API.

Step 2: Configure WorkflowGen

  1. Go to the Database section on the Configuration Panel General tab.

  2. In the Master database connection string field, add the ApplicationIntent=ReadWrite parameter to the existing connection string and click Test to test the database availability. Here's an example of a connection string:

     Data Source=workflowgen.database.windows.net;Initial Catalog=WFGEN;User ID=wfgen_user;Password=Admin123!;encrypt=true;trustServerCertificate=false;ApplicationIntent=ReadWrite;

  3. In the Read-only database connection string field, add (or edit) the connection string with the new ApplicationIntent=ReadOnly parameter, and click Test to test the database availability. Here's an example of a connection string:

     Data Source=workflowgen.database.windows.net;Initial Catalog=WFGEN;User ID=wfgen_user;Password=Admin123!;encrypt=true;trustServerCertificate=false;ApplicationIntent=ReadOnly;

  4. Check the Multi-database option.

  5. Check the User Portal components and modules that will use the Read-only database. For more information about this, see Database in the WorkflowGen Administration Guide.

Azure Load Balancer

This section provides instructions on how to create and configure your Azure Load Balancer feature. From the What is Azure Load Balancer? Microsoft article:

With Azure Load Balancer you can scale your applications and create high availability for your services. Load Balancer supports inbound and outbound scenarios, provides low latency and high throughput, and scales up to millions of flows for all TCP and UDP applications.

Load Balancer distributes new inbound flows that arrive on the Load Balancer's frontend to backend pool instances, according to rules and health probes.

Additionally, a public Load Balancer can provide outbound connections for virtual machines (VMs) inside your virtual network by translating their private IP addresses to public IP addresses.

Step 1: Create the Azure Load Balancer

Create a Basic load balancer following the instructions on the Azure Quickstart page. Once you've completed the steps, you'll have:

  • A load balancer with its resources configured: a back-end address pool, a health probe, and a load balancer rule

    Note: When creating the load balancer rule, you can configure the sticky-session from the Session persistence drop-down list. If the Session state is enabled in the web forms, the sticky-session is mandatory.

  • A virtual network

  • Two virtual machines with IIS installed on both

  • A network security group

    Note: When creating the NGS rules, adding the RDP rule is recommended for testing only. For production, we recommend using a VPN or private connection. See the Creating the NSG rules Microsoft article for instructions.

  • The public IP address for the load balancer, which you can find on its overview page

    Note: This public IP address will be used to access to WorkflowGen instances.

Step 2: Install and configure WorkflowGen

  1. Install WorkflowGen on both virtual machines by following the instructions in the Setup section in the WorkflowGen Technical Guide.

    Note: Once WorkflowGen installed, it is required to enable Anonymous Authentication for the WorkflowGen web site. The wfgen application and sub-applications may have different authentications enabled.

  2. Make sure that both instances of WorkflowGen point to the same database. Your database can be:

    • An Azure SQL database, or

    • A classic MS SQL database instance in a dedicated server or in one of the virtual machines. Be sure to add inbound and outbound security rules (depending on your needs) for the SQL port in the network security group.

  3. Create an Azure file share following the instructions in the Azure files section in the WorkflowGen Technical Guide, and copy the file share path.

    Note: Make sure to replace the ApplicationDataPath setting's value in the WorkflowGen web.config file with the new file share path.

  4. Open the WorkflowGen web.config file and modify the value of the following setting:

    <add key="ApplicationUrl" value="http[s]://<load balancer public IP address>/wfgen" />

    For both WorkflowGen instances, replace <load balancer public IP address> above with the load balancer's public IP address.

Step 3: Configure the web farm

Configure your WorkflowGen in a web farm architecture following the instructions in the Web farm architecture section in the WorkflowGen Technical Guide. Once you've completed the instructions, you'll have:

  • A common WebForms folder

  • Both WorkflowGen Engine and Directory Synchronization services running on one of the WorkflowGen instances only.

Azure Files

Azure Files is a cloud-based service that provides a file storage backing service for WorkflowGen instances that are hosted on Azure cloud or on-premise via a file share using the standard SMB protocol. This service provides different great options for data access, sharing, synchronization, and redundancy for use in single or multiple WorkflowGen instance scenarios.

For more information about Azure File benefits or use cases, refer to Microsoft's Introduction to Azure Files guide.

The following section provides recommendations and instructions on how to configure an Azure Files share to use in WorkflowGen.

Recommendations

Before choosing Azure Files as your primary file storage backing service for your WorkflowGen, there are a few performance configuration scenarios to consider for your data storage:

  • In a WorkflowGen single instance configuration

    • Hosted on an Azure Virtual Machine:

      • For best performance, use an SSD-grade local disk.

      • For good performance, use an Azure Files share in the same region.

    • Hosted on-premise:

      • For best performance, use an SSD-grade local disk.

      • For basic performance, use an Azure Files share in the region closest to your server for the lowest latency.

  • In a WorkflowGen web farm configuration

    • Hosted on an Azure Virtual Machine:

      • For best performance, use a file share from a file server backed by SSD-grade storage.

        Note: One of the WorkflowGen web servers or a dedicated virtual machine can act as the file server role.

      • For good performance, use an Azure Files share in the same region.

    • Hosted on-premise:

      • For best performance, use a file share from a file server backed by SSD-grade storage.

        Note: One of the WorkflowGen web servers or a dedicated server can act as the file server role.

      • For basic performance, use an Azure Files share in the region closest to your server for the lowest latency.

Configuring Azure Files for WorkflowGen

Prerequisites

  • Make sure to have a working WorkflowGen instance with internet access.

  • Make sure to know the address of the instance.

  • TCP port 445 must be open for outbound from the instance.

  • Windows PowerShell version 5.1 or later is required on the instance for one of the steps of the configuration.

  • An active Azure subscription.

  • You must have permissions to make changes in Windows of the WorkflowGen instance, e.g. Administrator privileges.

  • You must have permissions to make changes to the Storage accounts service in the Azure portal.

Step 1: Create a storage account in Azure

  1. In the Azure portal, choose the Storage accounts service.

  2. Add a new storage account.

  3. Enter a name.

    Note: The wfgendatastorage storage name will be used as an example throughout this section.

  4. Account kind: Choose Storage (general purpose v1) or StorageV2 (general purpose v2).

  5. Location: Choose a location in the same region as your Azure Virtual machine, or the closest to your on-premise location.

  6. Performance: Choose Standard.

  7. Choose your subscription.

  8. Create a new resource group.

    Note: The wfgenresourcegroup resource group name will be used as an example throughout this section.

  9. You can leave the rest of the settings set to their default values or you can customize them according to your needs.

  10. Click Create.

For more information about storage accounts, see About Azure storage accounts.

Step 2: Create a file share in Azure

  1. In the Storage accounts service, choose wfgendatastorage.

  2. In the Overview or the FILE SERVICE section, choose Files.

  3. Add a new File share.

  4. Enter a name.

    Note: The wfgenshare storage name will be used as an example throughout this section.

  5. Enter a quota according to your needs.

  6. Click OK.

For more information about file share, see Create a file share in Azure Files.

Step 3: Mount the file share in the WorkflowGen web server

  1. Log in to your WorkflowGen instance with your administration account.

  2. Open an instance of Windows PowerShell 5.1 as Administrator.

  3. Test TCP port 445 for outbound by running the following command in PowerShell:

     Test-NetConnection -ComputerName "wfgendatastorage.file.core.windows.net" -Port 445

    Note: Remember to replace wfgendatastorage in the above instructions with your storage account name.

    If the test result is successful, proceed to the next step. Otherwise, contact your network administrator to open TCP port 445 for outbound.

  4. Install or update the Azure PowerShell module in PowerShell:

     Install-Module -Name AzureRM -AllowClobber
 Import-Module -Name AzureRM

    For more information, see Install Azure PowerShell on Windows with PowerShellGet.

  5. In the Windows Computer Management console, create a local user as the service account that will be used for the WorkflowGen IIS application pool:

    1. Enter a new username and password.

      Note: The wfgen_service username will be used as an example throughout this section.

    2. Check User cannot change password.

    3. Check Password never expires.

    4. Click Create.

    5. Assign the wfgen_service user to the IIS_IUSRS group.

    6. Assign the user to the Remote Desktop Users group if the instance is a remote server.

  6. Log in to your WorkflowGen instance with the wfgen_service account.

  7. Open an instance of Windows PowerShell 5.1 as Administrator.

  8. Log in to your Microsoft Azure account in PowerShell:

     Login-AzureRmAccount

    If you encounter any security issues with the Microsoft Azure sign-in process, then you must manually add https://login.microsoftonline.com/ and all related websites' URIs to the Trusted sites zone in Internet Explorer's Internet Options.

  9. In the Microsoft Azure window, sign in to the Azure account that you used to create your storage account.

    If you've successfully signed in to your Azure account, PowerShell will display the following information:

     Account          : <your-microsoft-azure-account-name>
 SubscriptionName : <your-subscription-name>
 SubscriptionId   : <your-subscription-id>
 TenantId         : <your-tenant-id>
 Environment      : AzureCloud

  10. Persist the Azure Files share credential in Windows for the wfgen_service account in PowerShell:

    $resourceGroupName = "wfgenresourcegroup"
$storageAccountName = "wfgendatastorage"
$storageAccount = Get-AzureRmStorageAccount -ResourceGroupName $resourceGroupName -Name $storageAccountName
$storageAccountKeys = Get-AzureRmStorageAccountKey -ResourceGroupName $resourceGroupName -Name $storageAccountName
Invoke-Expression -Command "cmdkey /add:$([System.Uri]::new($storageAccount.Context.FileEndPoint).Host) /user:AZURE\$($storageAccount.StorageAccountName) /pass:$($storageAccountKeys[0].Value)"

    Note: Remember to replace wfgendatastorage and wfgenresourcegroup in the above instructions with your storage account and resource group names.

    The credential needs to be persisted for the wfgen_service account in the event of a Windows server restart.

    If the credential is successfully stored then you should see the following message:

    CMDKEY: Credential added successfully.

  11. Verify if the credential has been stored for the storage account in PowerShell:

    cmdkey /list

    If successful, you should then see:

    Target: Domain:target=wfgendatastorage.file.core.windows.net
Type: Domain Password
User: AZURE\wfgendatastorage

  12. Test the Azure Files share in the Windows File Explorer.

    \\wfgendatastorage.file.core.windows.net\wfgenshare

    Note: Remember to replace wfgendatastorage and wfgenshare in the above instructions with your storage account and file share names.

For more information about file share in Windows, see Use an Azure file share with Windows.

Step 4: Configure WorkflowGen to use the file share

  1. Log in to your WorkflowGen instance with your administration account.

  2. Open the Internet Information Services (IIS) manager console.

  3. Change your WorkflowGen application pool to use the custom wfgen_service account with the following settings:

    • Identity: wfgen_service

    • Load User Profile: True

  4. Save the changes, then restart IIS.

  5. Log in to your WorkflowGen instance with the wfgen_service account.

  6. Copy all the existing WorkflowGen files to the Azure Files share in PowerShell:

     Copy-Item -Path "C:\inetpub\wwwroot\wfgen\App_Data" -Recurse -Destination "\\wfgendatastorage.file.core.windows.net\wfgenshare" -Container

    Note: Remember to replace C:\inetpub\wwwroot\wfgen\App_Data, wfgendatastorage, and wfgenshare in the above instructions with your WorkflowGen instance's app_data folder, storage account, and file share names.

  7. Update the WorkflowGen web configuration file:

     <add key="ApplicationDataPath" value="\\wfgendatastorage.file.core.windows.net\wfgenshare\App_Data" />

    Note: Remember to replace wfgendatastorage and wfgenshare in the above instructions with your storage account and file share names.

  8. Open the WorkflowGen Administration Module or User Portal, then run a new request test.

Appendix: Viewing Azure Files share content

Use one of the following methods:

  • In your Azure portal storage account:

    • Use the Storage Explorer (preview) tool.

      or

    • Browse the wfgenshare file share under the Files section.

    OR

  • Mount the file share wfgenshare in Windows:

    1. Navigate to the wfgenshare file share under the Files section.

    2. Click Connect to display a tab with connection instructions.

    For example, to mount the file share to the Z drive from the WorkflowGen instance's administration account, run the following instructions provided by the Connect tab in PowerShell:

      $acctKey = ConvertTo-SecureString -String "aftEV8YUKljZeiwKP9Ts/kZysDASFVFsvSqAvWVjMb3E+QP4BWpVSNLVyqB2ScZjGtEIg/k0P7WBIg==" -AsPlainText -Force
  $credential = New-Object System.Management.Automation.PSCredential -ArgumentList "Azure\wfgendatastorage", $acctKey
  New-PSDrive -Name Z -PSProvider FileSystem -Root "\\wfgendatastorage.file.core.windows.net\wfgenshare" -Credential $credential -Persist

    Note: Remember to replace the key string assigned to $acctKey, wfgendatastorage, and wfgenshare in the above instructions with one of your storage account's Access keys, storage account, and file share names.

You should now be able to browse the content of the Z drive in the Windows File Explorer.

If you encounter any issues, see Troubleshoot Azure Files problems in Windows.

Azure SendGrid SMTP configuration

This section provides instructions on how to configure an Azure SendGrid SMTP with WorkflowGen.

Step 1: Create the SendGrid account in the Azure Portal

The SendGrid account must be created in the Azure Portal. See Create a SendGrid Account for more information on how to create a SendGrid account. Once you've completed the configuration, you'll have:

  • The server name (e.g. smtp.sendgrid.net),

  • The username (e.g. apikey),

  • The generated password, and

  • Port 25 or 587 set for TLS connections and explicit SSL connections.

For more information about the SendGrid SMTP integration, see SendGrid SMTP API.

Step 2: Configure WorkflowGen

To set up the connection between WorkflowGen and Azure SendGrid SMTP:

  1. Go to the General tab in the Configuration Panel.

  2. In the SMTP section:

    • Choose Server as the delivery method.

    • In the Host name field, enter your server name.

    • In the Port field, enter port 25 or 587.

    • Check Use SSL/TLS.

    • In the Username field, add your username.

    • In the Password field, add your password.

  3. Click Test next to the Host name field.

  4. In the Recipient mail field that will then appear under Sender mail, add an email address for testing, then click Send.

Note: WorkflowGen only supports TLS connections and explicit SSL connections.

Generating a universal link for WorkflowGen Plus

As of WorkflowGen Plus version 1.2.0 and WorkflowGen server version 7.11.2, you can generate a universal link to simplify the Azure AD login process for your WorkflowGen Plus mobile app users.

Base URL

  • protocol: workflowgenplus://

  • hostname: auth.init

Parameters

You'll need to specify the following parameters:

  • provider: azure-v1

  • tenant_id: Use the tenant ID you created earlier in the configuration (e.g. 4b72dd6c-013e-4a9c-b837-f03a58cb8fd1)

  • client_id: Use the application client ID (WorkflowGen Plus native app in Azure AD) you created earlier in the configuration (e.g. 6g909d00-8580-49a4-9003-a30f6b87ae86)

  • audience: Your WorkflowGen web application URL (e.g. http://workflow.mycompany.com/wfgen). Note: The value must be URL encoded.

The universal link should follow this format:

workflowgenplus://auth.init?provider=azure-v1&tenant_id=6g909d00-8580-49a4-9003-a30f6b87ae86&client_id=4b72dd6c-013e-4a9c-b837-f03a58cb8fd1&audience=http%3A%2F%2Fworkflow.mycompany.com%2Fwfgen

Once you've generated the universal link, give it to your users, who can use it to sign in to WorkflowGen Plus with the preset sign-in method.

Additional information on Azure integration

SOAP services support

WorkflowGen only supports requests to the SOAP API using classic authentication methods. If you still need to use this API, you have to perform some additional steps to configure it properly.

  1. Create a new separate WorkflowGen directory for the SOAP API users.

  2. Provision it with users and groups as needed.

  3. In the IIS Manager, enable the Basic authentication method for the \ws\wfgen application.

  4. In the web.config file (located in \Inetpub\wwwroot\wfgen), add the following under <location path="ws" inheritInChildApplications="false"> : 

    <system.webServer>
    <modules>
        <remove name="ApplicationSecurityAuthenticationModule" />
    </modules>
</system.webServer>

About session management

Azure Active Directory supports OpenID Connect Session Management, an extension draft standard, in addition to the core OpenID Connect standard. This standard defines the rules to handle SSO session of the provider from the client. An example use is that if a user logs out of their Azure AD session from any device, a regular web client will receive a message that enables it to remove the same user's local session. WorkflowGen supports this feature when activating delegated authentication with Azure AD.

Current limitations

  • If the WorkflowGen User Portal or Administration Module is displayed without the main header menu, this feature will not work. For example, this scenario could happen when the portal home page or a request follow-up form is displayed inside an iFrame in an external solution.

  • The GraphiQL module (/wfgen/graphql) doesn't support session management when displayed in a browser.

PreviousSynchronizing a Directory in Command LineNextAD FS Integration

Last updated