Azure Integration
Last updated
Last updated
This section provides instructions on:
: How to configure WorkflowGen users and groups synchronization using Azure Active Directory.
: How to configure WorkflowGen authentication using OpenID Connect and Azure Active Directory.
: How to authorize access to mobile applications using OpenID Connect and Azure Active Directory.
: How to authorize WorkflowGen access to server-side scripts using OpenID Connect and Azure Active Directory.
: How to authorize WorkflowGen access to single-page applications using OpenID Connect and Azure Active Directory.
: How to configure the WorkflowGen database using Azure SQL database.
: How to configure the optional Read Scale-Out feature.
: How to configure Azure Load Balancer for higher availability and greater scalability.
: How to configure an Azure Files share to use in WorkflowGen.
: How to configure an Azure SendGrid SMTP with WorkflowGen.
: How to generate a universal link to simplify the WorkflowGen Plus mobile app user login.
It also provides additional information on , , and .
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.
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.
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.
An Azure Premium P2 license must be activated in the Azure Active Directory tenant.
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.
In the WorkflowGen Administration Module (https://<workflowgen url>/admin), click Directories, then click New directory on the Directories screen.
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.
From the Directory connector drop-down list, select Azure AD SCIM v2.
Note: You can only have one SCIM directory per WorkflowGen instance.
Copy the generated token, since you'll need it for the Azure AD configuration.
Click Save to create the directory.
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.
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.
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:
On the Azure Active Directory pane in your Microsoft Azure portal, click Enterprise applications, then click New application.
In the Add an application pane, click Non-gallery application.
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.
Click Add.
You can now proceed to configuring the application to provision WorkflowGen.
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:
Choose Automatic provisioning mode.
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.
In the Secret Token field, paste the token that WorkflowGen generated earlier when you created the new SCIM directory.
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.
Azure AD group
urn:ietf:params:scim:schemas: core:2.0:Group
WorkflowGen group
objectId
externalId
systemIdentifier
mailNickname
displayName
name
members
members
users
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.
Azure AD user
urn:ietf:params:scim:schemas: extension:enterprise:2.0:User
WorkflowGen user
IsSoftDeleted
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
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
Once you've set all of the user mappings, click Save.
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.
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.
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.
Deactivate the classic Active Directory synchronization connector.
Create a new Azure SCIM v2 directory connector.
Move the users and groups already in Azure AD from other existing WorkflowGen directories to the SCIM directory.
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:
This example contains an algorithm that links only users to Azure AD:
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.
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.
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.
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.
In the Azure portal, click App registrations in the Azure Active Directory section.
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
Click Register at the bottom of the page.
You should now see the WorkflowGen registered application's overview page.
Now, you have to generate a client secret to use in the WorkflowGen Authentication Module.
Click Certificates & secrets.
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.
Click Save. The value you entered will now be encrypted.
Save the generated value, since you won't be able to retrieve it afterwards.
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.
Click Authentication.
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.
Click Save at the top of the section.
In order to expose the GraphQL API, you need to add a new application that will represent it. To do this:
In the Azure portal, click App registrations in the Azure Active Directory section.
Click New registration, and fill in the properties form:
Name: WorkflowGen GraphQL
Supported account type: Account in this organizational directory only
Click Register at the bottom of the page.
You've now successfully registered the GraphQL API in Azure AD.
Click Expose an API.
To the right of Application ID URI, click Set and enter the URI https://<workflowgen url>/graphql.
Example: https://mycompany.com/wfgen/graphql
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
Click Add scope.
Click Save.
On the WorkflowGen application registration page, click API permissions.
Click Add a permission, then My APIs.
Click WorkflowGen GraphQL API in the list.
Click Delegated permissions and check default.
Click Add permissions.
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:
Go to your directory properties section.
Copy the Tenant ID value.
The metadata endpoint is built like this:
By now you should have all the information needed to link your WorkflowGen instance to Azure AD.
Now, you have to configure WorkflowGen to delegate its authentication to Azure AD.
web.configOpen the WorkflowGen web.config file and add the following properties under <appSettings>.
Replace <CLIENT ID> with the application ID.
Replace <CLIENT SECRET> with the the WorkflowGen registered application's generated secret on Azure.
Replace <METADATA URL> with the URL that you built earlier from the Tenant ID value of your Azure AD directory.
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:
(Note: Remove | python -m json.tool if you don't have Python; this is for pretty printing.)
Windows PowerShell request example:
Table of web.config options
Option
Description
ApplicationSecurityAuthProvider
The name of the identity provider supported by WorkflowGen. At this time, there is support only for Azure Active Directory, Auth0, and ADÂ FS. Value: azure-v1, auth0, oradfs
ApplicationSecurityAuthClientId
Each identity provider generates a code that uniquely identifies your application. In this case, this is the code that uniquely identifies the WorkflowGen web application.
ApplicationSecurityAuthClientSecret
Like the client ID, this is also generated by the identity provider, but it is more like what a password is for a user. It's important to keep this secret because malicious software that has access to this can act on the behalf of the application. This value must be explicitly generated in Azure Active Directory.
ApplicationSecurityAuthMetadataUrl
ApplicationSecurityAuthAppIdClaim
ApplicationSecurityAuthUsernameClaim
The name of the claim contained in the access token that identifies the user in WorkflowGen. This is used by WorkflowGen to generate a session token as well as by the GraphQL API when receiving an access token. Note: It's recommended to keep the default value.
ApplicationSecurityAuthClockTolerance
This value is used when verifying a token in WorkflowGen. It's essentially to deal with minor differences between servers' clocks. Note: It's recommended to keep the default value.
ApplicationSecurityAuthSessionRefreshEnableIFrame
When enabled (Y), this option activates the session auto-refresh feature using an invisible <iframe>. This allows users to enter their password less often by refreshing their session in the background while they're working.
Note: This option is only available when using WorkflowGen with OIDC authentication.
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.
In order to generate a session token, you need to add a few more settings to the web.config.
Open the WorkflowGen web.config file and add the following property under <appSettings>:
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.
You now need to activate the delegation by replacing the authentication system in IIS and pointing WorkflowGen's modules to the correct authentication module.
In IIS Manager, click on the WorkflowGen application in the tree view.
Click the Authentication button.
Enable Anonymous Authentication, and disable all other authentications.
Perform these steps for all sub-applications as well.
web.config files of certain modulesCertain 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.
Add the following property to the WorkflowGen web.config file:
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.
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.
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.
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.
In the Azure portal, click App registrations in the Azure Active Directory section.
Click New application registration, and fill in the properties:
Name: WorkflowGen Plus
Application type: Native
Redirect URI: workflowgenplus://auth.authorize/azure-v1
Click Create at the bottom of the page.
You should now see the WorkflowGen Plus registered application's overview page.
Click Settings.
In the API Access section, click Required permissions, then click Add.
Click Select an API.
Search for the WorkflowGen GraphQL API application that you registered and select it.
Click Select permissions, then check Access WorkflowGen under Delegated Permissions to grant access to the API.
Click Select.
You should now see the WorkflowGen GraphQL API listed in the list of required permissions alongside Windows Azure Active Directory.
Click Settings, then click Redirect URIs.
Add the workflowgenplus://auth.authenticate/azure-v1 and workflowgenplus://auth.deauthenticate/azure-v1 URIs to the list.
Click Save.
You've now successfully registered the WorkflowGen Plus mobile application to your Azure AD.
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.
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.
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.
In the Azure portal, click App registrations in the Azure Active Directory section.
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.
Click Create at the bottom of the page.
You've now successfully registered your script in Azure Active Directory.
On the application's overview page, click Settings.
In the API Access section, click Required permissions, then click Add.
Click Select an API.
Search for the WorkflowGen GraphQL API and select it.
Click Select permissions, then check all of the checkboxes.
Click Select.
You should now see the WorkflowGen GraphQL API in the list of required permissions.
Return to the application's overview page, then click Settings.
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.
Click Save.
Copy and save the value generated by Azure. This is your client secret, and you won't be able to retrieve it later.
Here's a review of the information you need:
A client ID, which can be found on the registered application settings tab.
A client secret, which can be found on the registered application settings tab.
Your Azure AD's tenant ID, which can be found in the properties sub-section in the Active Directory section in the portal.
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.
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.
On the Applications page in the WorkflowGen Administration Module, click New application.
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
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.
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.
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.
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.
In the Azure portal, click App registrations in the Azure Active Directory section.
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>
Click Create at the bottom of the page.
You should now be in your newly registered application's overview page.
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.
Click Settings.
In the API Access section, click Required permissions, then click Add.
Click Select an API.
Search for the WorkflowGen GraphQL API application that you registered and select it.
Click Select permissions, then check all of the checkboxes.
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.
This section provides instructions on how to create and configure your Azure SQL database.
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.
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:
Create_WFG-V7-0_SQL_Tables.sql
Create_WFG-V7-0_SQL_PKeys.sql
Create_WFG-V7-0_SQL_FKeys.sql
Create_WFG-V7-0_SQL_Indexes.sql
Create_WFG-V7-0_SQL_Triggers.sql
Create_WFG-V7-0_SQL_Const.sql
Open the WorkflowGen web.config file and add the following node under <connectionStrings>:
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.
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.
Install or update the Azure PowerShell module in PowerShell by running the following commands:
Log in to your Microsoft Azure account in PowerShell by running the following command:
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.
Enable the Read Scale-Out feature in PowerShell by running the following command:
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).
Go to the Database section on the Configuration Panel General tab.
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:
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:
Check the Multi-database option.
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.
A load balancer with its resources configured: a back-end address pool, a health probe, and a load balancer rule
A virtual network
Two virtual machines with IIS installed on both
A network security group
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.
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.
Make sure that both instances of WorkflowGen point to the same database. Your database can be:
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.
Note: Make sure to replace the ApplicationDataPath setting's value in the WorkflowGen web.config file with the new file share path.
Open the WorkflowGen web.config file and modify the value of the following setting:
For both WorkflowGen instances, replace <load balancer public IP address> above with the load balancer's public IP address.
A common WebForms folder
Both WorkflowGen Engine and Directory Synchronization services running on one of the WorkflowGen instances only.
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.
The following section provides recommendations and instructions on how to configure an Azure Files share to use in WorkflowGen.
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.
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.
In the Azure portal, choose the Storage accounts service.
Add a new storage account.
Enter a name.
Note: The wfgendatastorage storage name will be used as an example throughout this section.
Account kind: Choose Storage (general purpose v1) or StorageV2 (general purpose v2).
Location: Choose a location in the same region as your Azure Virtual machine, or the closest to your on-premise location.
Performance: Choose Standard.
Choose your subscription.
Create a new resource group.
Note: The wfgenresourcegroup resource group name will be used as an example throughout this section.
You can leave the rest of the settings set to their default values or you can customize them according to your needs.
Click Create.
In the Storage accounts service, choose wfgendatastorage.
In the Overview or the FILE SERVICE section, choose Files.
Add a new File share.
Enter a name.
Note: The wfgenshare storage name will be used as an example throughout this section.
Enter a quota according to your needs.
Click OK.
Log in to your WorkflowGen instance with your administration account.
Open an instance of Windows PowerShell 5.1 as Administrator.
Test TCP port 445 for outbound by running the following command in PowerShell:
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.
Install or update the Azure PowerShell module in PowerShell:
In the Windows Computer Management console, create a local user as the service account that will be used for the WorkflowGen IIS application pool:
Enter a new username and password.
Note: The wfgen_service username will be used as an example throughout this section.
Check User cannot change password.
Check Password never expires.
Click Create.
Assign the wfgen_service user to the IIS_IUSRS group.
Assign the user to the Remote Desktop Users group if the instance is a remote server.
Log in to your WorkflowGen instance with the wfgen_service account.
Open an instance of Windows PowerShell 5.1 as Administrator.
Log in to your Microsoft Azure account in PowerShell:
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.
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:
Persist the Azure Files share credential in Windows for the wfgen_service account in PowerShell:
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:
Verify if the credential has been stored for the storage account in PowerShell:
If successful, you should then see:
Test the Azure Files share in the Windows File Explorer.
Note: Remember to replace wfgendatastorage and wfgenshare in the above instructions with your storage account and file share names.
Log in to your WorkflowGen instance with your administration account.
Open the Internet Information Services (IIS) manager console.
Change your WorkflowGen application pool to use the custom wfgen_service account with the following settings:
Identity: wfgen_service
Load User Profile: True
Save the changes, then restart IIS.
Log in to your WorkflowGen instance with the wfgen_service account.
Copy all the existing WorkflowGen files to the Azure Files share in PowerShell:
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.
Update the WorkflowGen web configuration file:
Note: Remember to replace wfgendatastorage and wfgenshare in the above instructions with your storage account and file share names.
Open the WorkflowGen Administration Module or User Portal, then run a new request test.
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:
Navigate to the wfgenshare file share under the Files section.
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:
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.
This section provides instructions on how to configure an Azure SendGrid SMTP with WorkflowGen.
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.
To set up the connection between WorkflowGen and Azure SendGrid SMTP:
Go to the General tab in the Configuration Panel.
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.
Click Test next to the Host name field.
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.
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.
protocol: workflowgenplus://
hostname: auth.init
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:
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.
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.
Create a new separate WorkflowGen directory for the SOAP API users.
Provision it with users and groups as needed.
In the IIS Manager, enable the Basic authentication method for the \ws\wfgen application.
In the web.config file (located in \Inetpub\wwwroot\wfgen), add the following under <location path="ws" inheritInChildApplications="false"> :
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.
Make sure that the SCIM application is properly installed and configured. For instructions on how to do this, see in the section.
Another possible cause might be related to other configurations in your Azure Active Directory. For more troubleshooting steps, see the Microsoft article.
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 for more information). The Microsoft documentation on how to add and verify a custom domain is available .
The endpoint provided by the identity provider that supports the standard. It enables WorkflowGen to get some public information about your Azure Active Directory domain. Without this, you'll have to manually enter much more configuration in the web.config.
The name of the claim contained in the access token obtained from the identity provider that uniquely identifies a non-interactive client. This is only used if you have a machine-to-machine application that needs to have access to the GraphQL API. To configure this, see the section. Note: It's recommended to keep the default value.
For instructions on how to generate a universal link to simplify the Azure AD login process for your users, see the section.
Make sure to have successfully configured delegated authentication to Azure AD on your WorkflowGen instance following the instructions in the section.
Make sure to have successfully configured delegated authentication to Azure AD on your WorkflowGen instance following the instructions in the section.
(Source: )
Make sure to have successfully configured delegated authentication to Azure AD on your WorkflowGen instance following the instructions in the section.
The Azure SQL database instance has to be created in the . See for more information on how to create the database. Once you've completed the instructions, you'll have:
Connect to your Azure SQL database instance with the administrator account you created by using the or .
You have to create a SQL Server user account with db_datareader and db_datawriter permissions. See , or run the following script in the SQL Database Query Editor or SQL Management Studio (the master database must be selected):
Get the database creation script by downloading the and extracting it to DRIVE:\temp.
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 Microsoft article.
For more information, see .
You can also enable Read Scale-Out feature using the .
Check the User Portal components and modules that will use the Read-only database. For more information about this, see in the .
This section provides instructions on how to create and configure your Azure Load Balancer feature. From the Microsoft article:
Create a Basic load balancer following . Once you've completed the steps, you'll have:
Note: When creating the load balancer rule, you can configure the sticky-session from the Session persistence drop-down list. If the , the sticky-session is mandatory.
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 Microsoft article for instructions.
Install WorkflowGen on both virtual machines by following the instructions in the section in the .
An , or
Create an Azure file share following the instructions in the section in the , and copy the file share path.
Configure your WorkflowGen in a web farm architecture following the instructions in the section in the . Once you've completed the instructions, you'll have:
For more information about Azure File benefits or use cases, refer to Microsoft's guide.
For more information about storage accounts, see .
For more information about file share, see .
For more information, see .
For more information about file share in Windows, see .
If you encounter any issues, see .
The SendGrid account must be created in the . See for more information on how to create a SendGrid account. Once you've completed the configuration, you'll have:
For more information about the SendGrid SMTP integration, see .
Azure Active Directory supports , 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.