Tests

Web app addresses

Check the following URLs with the wfgen_admin user account:

• User Portal: http://[yoursite]/wfgen

• Administration Module: http://[yoursite]/wfgen/admin

If you're unable to log in, verify the web.config file in the root folder of the WorkflowGen application (usually DRIVE:\Inetpub\wwwroot\wfgen) and validate that the MainDbSource connection string contains the correct database connection information including server, database name, user, and password.

Test sample processes

You can create processes using the list of built-in process samples.

Additional configurations

You can change the security configuration (such as the authentication method) by following the instructions in the section.

This guide covers all of the procedures involved in the installation and maintenance of WorkflowGen. It's intended mainly for system administrators who'll be required to install or carry out maintenance of the application.

Preparation

You must be administrator of the web server. Using a local administrator account is recommended. You must know:

• The physical path on the web server where the WorkflowGen web application will be installed.

• The physical path on the web server where WorkflowGen Windows services will be installed.

• The URL of the web server where WorkflowGen will be installed.

• MS SQL Server database:

  • The name of the MS SQL Server.

  • The credentials of the SA account.

  • The file path of the SQL Server database files on the SQL server machine.

• The name or IP address of the SMTP gateway (it's recommended to use the IIS SMTP gateway; see ).

• The default sender email address for notifications.

• The authentication method you want to use for WorkflowGen web applications.

Using an IIS SMTP gateway

Using a local IIS SMTP gateway is strongly recommended to improve performance. A local SMTP gateway is configured to forward emails to the enterprise SMTP gateway ("smart host") only, so the current enterprise security will be applied.

There are several advantages to using an SMTP relay at the IIS WorkflowGen server:

• Better performance, since messages are sent directly to the relay.

Overview

You can customize WorkflowGen according to your language and, if applicable, the required language layout.

Customizing the resource files

To customize the resource files for your language, first make copies of the .resx files in the following folders:

• \wfgen\App_GlobalResources

• \wfgen\WfApps\WebForms\App_GlobalResources

• \wfgen\ws\App_GlobalResources

Append the file name with the language code and, if needed, a hyphen followed by the country code; for example, .ar-AE for Arabic and United Arab Emirates. Then, customize the resource files as needed.

Customizing the CSS files

If the custom language requires a different layout, such as right-to-left text, customize the CSS files as needed using the method in the previous section.

WorkflowGen engine service

Automatic task execution (e.g. overdue exceptions and notifications management) is provided by this Windows Service. This service is installed by the setup and is started automatically after installation. (Refer to WorkflowGen Windows Services installation if the manual installation procedure was used.)

If errors occurred while the service is running, those errors will appear in the Event Viewer (source: WorkflowGenEngineService) accessible in the Windows Administrative Tools. All the messages related to this service will be displayed in the Windows Logs / Application section.

To manage this Windows service execution, open Administrative Tools / Services, then select and open WorkflowGen Engine (WorkflowGenEngineService).

WorkflowGen directory synchronization service

The automatic user and group synchronization is provided by this Windows Service, which is installed by the setup and started automatically after installation. (Refer to if the manual installation procedure was used.)

If errors occurred while the service is running, those errors will appear in the Event Viewer (source: WorkflowGenDirSyncService) accessible in Windows Administrative Tools. All messages related to this service will be displayed in the Windows Logs / Application section.

To manage this Windows service execution, open Administrative Tools / Services, then select and open WorkflowGen Directory Sync (WorkflowGenDirSyncService).

Troubleshooting

After a WorkflowGen version upgrade or system change (such as a server update or configuration change), the automatic directory synchronization can fail with the error message The license file is missing, invalid or your trial period has expired.

To resolve this issue, perform the following checks on your WorkflowGen system:

• Verify that there is only one license file (.lic) in the wfgen\bin folder.

• Verify that the license file (.lic) is not locked; if so, unlock it.

• Verify that the two WorkflowGen service execution files (WfgDirectoriesSyncService.exe

License activation

Overview

You must have a trial, Developer, or Enterprise license to activate WorkflowGen.

You must have a serial number to activate the Developer and Enterprise versions of WorkflowGen. If you don't have one, contact your vendor.

How to activate WorkflowGen

Install the license file

1. Remove all current .lic files from the DRIVE:\Inetpub\wwwroot\wfgen\bin folder.

2. Copy your .lic file to the DRIVE:\Inetpub\wwwroot\wfgen\bin folder.

3. Make sure the license file inherits the security settings.

Add the serial number to the web.config file

For the Developer and Enterprise editions of WorkflowGen, you must edit the web.config file located in the DRIVE:\Inetpub\wwwroot\wfgen folder.

1. Edit the \Inetpub\wwwroot\wfgen\web.config file.

2. Set your serial number as the value of the ApplicationSerialNumber parameter.

License per user

If you have a license per user, you cannot exceed the maximum number of users supported by your license, otherwise you will receive an error message when you try to launch a new request. However, user management will still be accessible.

If you want to import several users from your enterprise directory (Active Directory, LDAP, etc.), and since only active users are considered, you can choose between the following cases:

• If your enterprise directory has fewer users than the maximum number of users supported by your WorkflowGen license, then you can import all of your users with the option New user default status set to Active.

• If your enterprise directory has more users than the maximum number of users supported by your WorkflowGen license, then you should import all your users with New user default status set to Inactive and set the Self activation option as follows:

  • If you want to manually activate users authorized to use WorkflowGen, uncheck the

End-users

The WorkflowGen Administration Module and User Portal are fully web-based applications. The requirements are as follows:

Operating systems

• Windows 11

• macOS

Web browsers

• Chrome

• Firefox

• Edge

• Safari

Display

• 1280 × 800 or higher resolution

• For form design, the suggested minimum resolution is 1366 × 768

Web server

The system requirements for the web server hosting WorkflowGen are as follows:

Operating systems

• Windows Server 2012 or later (all releases)

• Windows 11 (recommended for development environments only)

Web server

• Microsoft IIS 10 or higher

• .NET Framework 4.8

• (requires IIS)

Server options to enable

Server role

• Web server (IIS)

Features

• .NET Framework 4.8 features:

  • .NET Framework 4.8

  • ASP.NET 4.8

Web Server role (IIS) / Role services

• Security:

  • Basic Authentication

  • Integrated Windows Authentication (optional)

• Application development:

Minimum hardware configuration

• Quad-core processor

• 8 GB RAM

• SATA hard disk with 40 GB free

See the guide for up-to-date server specifications based on your planned usage of the system.

Node.js-based web applications

To use the optional GraphQL, incoming webhooks, OpenID Connect Auth, and SCIM APIs, you must first install the following requirements:

• ✏️ Note:

Database server

The system requirements for the database server hosting the WorkflowGen database are as follows:

Hardware specifications

• Quad-core processor

• 8 GB RAM

• SATA hard disk with 40 GB free

Database servers supported

• Microsoft SQL Server 2016 and Express Edition

• Microsoft SQL Server 2017 and Express Edition

• Microsoft SQL Server 2019 and Express Edition

• Microsoft SQL Server 2022 and Express Edition

See the guide for up-to-date server specifications based on your planned usage of the system.

Authentication methods and directory synchronization

Authentication methods

• Integrated Windows or IIS Basic (Active Directory)

• Applicative (WorkflowGen)

• Forms

• Custom (SSO: single sign-on)

Directory synchronization

• Active Directory (supports all releases of Windows Server 2012 and later)

• LDAP-compatible directory

• Text files

• SCIM

Notifications and XML syndication

Email notifications

• Email notifications are sent via SMTP protocols (Exchange and Lotus Notes are compatible).

• Any email client can receive WorkflowGen notifications.

• Email layout and content can be customized in HTML or plain text.

For best performance, the IIS SMTP gateway should be used (see ).

XML syndication

WorkflowGen provides an XML RSS feed (called the Portlet) to embed WorkflowGen data into existing web portals. See the for more information.

Overview

WorkflowGen stores files (such as attachments to a request) in a folder tree structure. By default these files are stored on the web server in the folder specified in the ApplicationDataPath parameter in the configuration file (web.config), e.g. <add key="ApplicationDataPath" value="\\SERVER\SHARE$\wfgen\App_Data" />.

The default value is empty and thus will point to the physical directory DRIVE:\Inetpub\wwwroot\wfgen\App_Data. The default is to keep all the files on the web server.

You might need to move this storage folder location to a dedicated file server for the following reasons:

• High volume (large attachments, document archiving, high usage level)

• Web Farm architecture implementation (see )

Basic configuration allows you to easily move these files, but with a low security level.

Basic configuration

The following steps must be followed to configure your web server:

1. Create the storage folder on the file server DRIVE:\FOLDER (e.g. D:\filepub).

2. Re-create the folder tree structure relative to the file storage location:

   • DRIVE:\FOLDER\wfgen\App_Data

Database file storage mode

Overview

This feature allows process file data (including attachments) to be stored in the database. It allows you to perform WorkflowGen data backup without interrupting service, so that WorkflowGen can still be used during the backup.

Setup and configuration

WorkflowGen web configuration

Set the ApplicationDefaultProcessDataFileStorageMethod parameter to File to store process data files in the file system, or set it to Database to store process data files in the database.

This parameter will define the default process data file storage method when creating a new process or importing a process XPDL of previous version.

Usage

Each process version can have the process data file storage method set independently. This will allow different processes using the file system or database storage method.

New process

On the Process information tab:

• Check the Process data storage option Store file content in database to enable the database file storage method.

• Uncheck the Process data storage option to disable the database file storage method. This will then use the file system storage method.

Existing process

On the Process information tab:

• Uncheck the Process data storage option to disable the database file storage method. This will then use the file system storage method.

When changing the process data storage method, the following rules must be applied:

• There should be no existing requests using the previous process data storage method. You can either delete existing requests or create a new version of the process.

• There should be no existing FILE type process data with the default file value using the previous process data storage method. You can delete all default file values, change the process data storage method, and re-upload the default file values into the process data.

Additional information

Temporary files

For a Web Farm architecture, file storage must be centralized in a common shared storage path. The settings in the section must be applied for temporary files.

In the database file storage method, WorkflowGen will still create temporary files in the \wfgen\App_Data folder (ApplicationDataPath) to be used by requests and actions at runtime.

These temporary files will be automatically deleted when the requests or actions are completed.

Custom asynchronous system action

To ensure data integrity and 24-hour / 7-days-a-week operation time in database file storage method, your custom asynchronous system action that uses FILE IN parameters must also save the file content in your custom application database when the file is referenced later by your action.

This will ensure that the file will still exist and can be used later by your asynchronous system action, since only the WorkflowGen database and your custom application database are backed up.

Overview

WorkflowGen is a Microsoft Active Server Pages .NET (ASP.NET 4) application. It includes:

• .aspx files

Overview

The WorkflowGen SQL reporting module uses SQL views to gather important information about your users, requests, and actions, allowing you to create custom data reports.

Technical requirements

These sections contain instructions on how to set up certain advanced WorkflowGen configurations.

See the WorkflowGen for Azure guide for instructions on:

• Microsoft Entra ID synchronization: How to configure WorkflowGen users and groups synchronization using Microsoft Entra ID (formerly Azure Active Directory).

• Microsoft Entra ID authentication: How to configure WorkflowGen authentication using OpenID Connect and Microsoft Entra ID.

• Microsoft Entra ID configuration for WorkflowGen Plus v2: How to authorize access to the WorkflowGen Plus v2 mobile app using OpenID Connect and Microsoft Entra ID.

• Microsoft Entra ID configuration for server-side scripts: How to authorize WorkflowGen access to server-side scripts using OpenID Connect and Microsoft Entra ID.

• Microsoft Entra ID configuration for single-page applications: How to authorize WorkflowGen access to single-page applications using OpenID Connect and Microsoft Entra ID.

• Azure SQL database configuration: How to configure the WorkflowGen database using Azure SQL database.

• Read Scale-Out: How to configure the optional Read Scale-Out feature.

• Azure Load Balancer: How to configure Azure Load Balancer for higher availability and greater scalability.

• Azure Files: How to configure an Azure Files share to use in WorkflowGen.

• Azure SendGrid SMTP configuration: How to configure an Azure SendGrid SMTP with WorkflowGen.

• Generating a universal link for WorkflowGen Plus v2: How to generate a universal link to simplify the WorkflowGen Plus v2 mobile app user login.

Overview

This section contains instructions on how to to configure WorkflowGen delegated authentication with Gardian.

The Gardian configuration process closely mirrors that of Okta. To set up Gardian, begin by following the instructions in the section, substituting the values with Gardian service provider specifications where needed. After completing those steps, return to this section for configuration details specific to Gardian.

Overview

The automatic user and group synchronization is provided by this Windows service. This service is installed by the setup pack and started automatically after installation.

Installation

Overview

The following procedure applies to the WorkflowGen PowerShell installation, which is only compatible with:

• Azure SQL Database

Overview

This section describes how to configure multiple instances of WorkflowGen on the same web server. Each instance of WorkflowGen also requires a dedicated license. This section assumes that you've already installed separate instances of WorkflowGen as described in the section.

Overview

To allow higher availability and scalability, you can install WorkflowGen in a Web Farm architecture. The application is therefore installed on several servers, but the database and file storage directory are centralized on one dedicated server.

User requests are automatically routed to different servers depending on their load and availability. You can choose between different methods of load balancing such as DNS Round Robin or set up a hardware load balancer.

Backup

Overview

The data and database files should be backed up regularly to preserve the reliability of the processes and their associated data.

Full (applications and data)

Application and data files

Back up the DRIVE:\Inetpub\wwwroot\wfgen folder.

If you've applied file storage, back up the folder as indicated in the ApplicationDataPath parameter in the web.config file.

Database

Perform a standard SQL database backup using your DBMS tools.

Data only

Database

Perform a standard SQL database backup using your DBMS tools.

Data files

Back up the DRIVE:\Inetpub\wwwroot\wfgen\App_Data folder.

Moving the WorkflowGen database

SQL Server database

To move the WorkflowGen SQL Server database from one server to another:

1. Stop IIS services on the production server.

2. Detach the WorkflowGen database.

3. Copy the .mdf and .ldf files to the new location.

Moving the WorkflowGen application

To move the WorkflowGen installation from one server to another:

1. Stop IIS services on the production server.

2. Set up the same version of WorkflowGen on the new server.

3. Copy the DRIVE:\Inetpub\wwwroot\wfgen\App_Data folder from the old server to the new one if you haven’t applied file storage externalization.

Monitoring

Storage space

File data

The only folder that you need to monitor for storage space is DRIVE:\Inetpub\wwwroot\wfgen\App_Data. The other folders should always keep the same size because everything that is generated over the time is placed in this directory.

Database

The database size can be determined by checking the .mdf and .ldf files if you're using SQL Server, or using your DBMS tools.

Storage space needs may vary depending on whether or not the Store file content in database process data storage option is selected during the process definition.

Directory synchronization

The directory synchronization log files can be found in the \wfgen\App_Data\LogFiles\Dir\Synchro directory. Alternately, you can consult and manage the logs history directly in the WorkflowGen Administration Module.

Windows Services

Windows Services should be set to run automatically when the server starts. Periodically, Windows Services will perform the following necessary tasks:

• Raise overdue exceptions

• Send overdue notifications

• Delete inactive delegations

• Delete ghost activities (activities initialized but never started)

Usage

Requests/actions by day

A statistics module and charting functions are provided in the User Portal to generate detailed reports on the requests and actions. You can customize reports using filters.

Attachment file size

Attachments to requests submitted using web forms are saved in the DRIVE:\Inetpub\wwwroot\wfgen\App_Data\Files\EFormASPX temporary folder and are automatically deleted 24 hours after their creation.

WorkflowGen will copy those runtime files to a permanent location. If the Store file content in database process data storage option is enabled, then they are stored directly in the database. Otherwise, they're stored in the file system as determined by the ApplicationDataPath configuration parameter (e.g. \App_Data\Files\DataSet\runtime).

If you know that a process takes too much space on the disk because of the process data, or too much space in the database because of file attachments, you can turn off the Archive action associated data option in the process definition. This will prevent the attached file from being stored for each action of every request. Only the data after the last action will be kept on the disk or in the database.

Database authentication

Using Windows Authentication instead of SQL Server Authentication

You can set up your SQL Server connection to use Windows Authentication (SSPI) instead of SQL Server Authentication for the WorkflowGen back-end database and other external databases. This SQL authentication mode provides additional security, since no credentials are stored in the web.config file.

To configure Windows Authentication, use one of the following connection strings in the WorkflowGen web.config file, located in the DRIVE:\Inetpub\wwwroot\wfgen folder:

OR

You'll also need to modify the WorkflowGen application pool identity for a service account. To do this:

1. In IIS Manager, right-click on the WorkflowGen application pool, then select Advanced Settings.

2. In the Process Model section, select Identity, then click the ... button.

3. Select Custom Account, then click Set...

For more information on SQL Server connection strings, see .

Database scaling

Overview

The database scaling feature allows for the addition of database servers in order to dramatically improve server performance and response times. The additional read-only replica database servers will be used as dedicated read-only servers (SELECT SQL queries). The read-only database servers are replicated from the existing primary database using the SQL Server Replication service.

Requirements

Overview

• SQL Server 2014 or later for all database servers

• SQL Server Replication feature must be installed on all SQL Server instances

• SQL Server Agent must be installed and configured on all SQL Server instances

Setup and configuration

Overview

This section provides a general procedure for configuring the SQL Server Replication service on all the SQL Server instances and enabling the WorkflowGen web server in database scaling mode. This procedure is an example based on one WorkflowGen instance and two database server instances architecture.

If your current architecture differs from this example, you can adapt the procedure and some specific configuration options according to your needs.

Your current WorkflowGen environment must meet the following prerequisites:

• The initial WorkflowGen database is already installed on the primary database instance.

• The read-only database instance does not contain an existing WorkflowGen database.

• The WorkflowGen web server is fully configured and allows access to the Administration Module with a WorkflowGen administrator account.

SQL Server configuration options

It is mandatory to update the SQL Server's max text repl size configuration option with a higher value in order for the database replication to function properly. We recommend setting this to the maximum value of 2147483647 instead of the default value of 65536.

Run the following SQL statements in the source (primary) and destination (read-only) SQL Server database instances (this example uses SQL Server 2008):

For more information, see and select your version of SQL Server from the drop-down menu.

SQL Server replication services

To set up a publication on the primary database:

1. Open SQL Server Management Studio.

2. Connect to the primary database instance.

3. Open the Replication node.

4. Right-click on Local Publications and choose New Publication. The New Publication Wizard will open. Click Next.

To set up a subscription on the read-only database:

1. Open SQL Server Management Studio.

2. Connect to the read-only database instance.

3. Open the Replication node.

4. Right-click on Local Subscriptions and choose New Subscription. The New Subscription Wizard will open. Click Next.

Database scaling in WorkflowGen

Enable the multi-database mode in WorkflowGen:

1. In the WorkflowGen Administration Module, open the Configuration Panel and select the General tab.

2. In the Read-only database connection string field, enter the WorkflowGen connection string of the read-only database instance.

3. Check Enable on Multi-database to turn on the database scaling feature.

References

• For more information on SQL Server replication, see and select your version of SQL Server from the drop-down menu.

• For more information on the SQL Server max text repl size option, see and select your version of SQL Server from the drop-down menu.

Overview

The following procedure applies to the setup using the WorkflowGen manual installation pack.

Installation pack

Start by extracting the manual installation pack (.zip) to a temporary folder on the WorkflowGen web server (e.g. DRIVE:\temp).

The installation pack contains these folders:

• Databases: The MS SQL Server database creation scripts

• Inetpub: The WorkflowGen application files

• Program Files: The WorkflowGen Windows services application file

WorkflowGen files and folders architecture

The recommended physical directory structure for WorkflowGen web application files and folders should be under DRIVE:\Inetpub\wwwroot\wfgen. This folder contains static resources such as images, HTML files and process data, and the applications used by WorkflowGen.

1. Copy the source \Inetpub folder to your destination DRIVE:\ (e.g. DRIVE:\Inetpub\wwwroot\wfgen).

2. Copy the source Advantys folder (\Program Files\Advantys) to your destination DRIVE:\Program Files (e.g. DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin).

Database creation

MS SQL Server configuration

Option 1: Create the database manually using the create.sql SQL script

1. Open the SQL Server Management Studio tool and connect to your database server with an administrator account (e.g. SA).

2. Create a new database (e.g. WFGEN).

3. Create a new SQL Server user account (e.g. WFGEN_USER).

Option 2: Create the database manually using SQL scripts

1. Open the SQL Server Management Studio tool and connect to your database server with an administrator account (e.g. SA).

2. Create a new database (e.g. WFGEN).

3. Create a new SQL Server user account (e.g. WFGEN_USER).

Azure SQL database configuration

Azure SQL database needs to be created and configured manually; see the section in the guide for instructions on how to do this.

WorkflowGen Administrator account setup

WorkflowGen requires a valid Windows NT or Active Directory account. This account will be used by the WorkflowGen Administrator, but it's not necessary to define it as an NT or Active Directory Administrator.

WorkflowGen web configuration

1. Open and edit the DRIVE:\Inetpub\wwwroot\wfgen\web.config WorkflowGen web configuration file.

2. Update the database connection string:

   • MS SQL Server: <add name="MainDbSource" connectionString="Data Source=localhost;Initial Catalog=WFGEN;User ID=WFGEN_USER;Password=Admin123!;" providerName="System.Data.SqlClient" />

For more information about the other configuration settings, see the appendix.

WorkflowGen Windows Services installation

Installation

1. Open and edit the DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\WfgWorkflowEngineService.exe.config Engine service configuration file.

2. Update the WorkflowGen web configuration path (e.g. <add key="WebConfigPath" value="DRIVE:\inetpub\wwwroot\wfgen\web.config" />).

3. Open and edit the DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\WfgDirectoriesSyncService.exe.config Directory Synchronization service configuration file.

Configuring IIS

Creating the application pool

It's recommended that WorkflowGen be isolated from other applications by creating its own application pool and associating all declared applications with the new application pool.

1. In IIS Manager, click Application pools. In the right-hand pane, right-click and choose Add application pool, then give it a name (e.g. WorkflowGen).

2. Select the .NET Framework 4 version.

3. Select Integrated pipeline mode.

Creating the website (if WorkflowGen is set up on a new website)

1. Launch IIS Manager and expand the tree structure under the IIS server name where you want to create the new site.

2. Right-click on the Sites icon and choose Add Web Site. Enter the name of the site, select its application pool (if other than the default), and enter the physical path of the root (click Browse and select the \wwwroot folder, usually DRIVE:\inetpub\wwwroot\).

Configuring the website

Default document

The default.aspx default document type must be created if it doesn't exist. By default, this default document should exist on an IIS server running .NET.

To verify this, click the site's icon and ensure that the pane on the right-hand side shows the Features view (the tab at the bottom of the pane allows you to switch between Features and Content). Double-click the Default document icon. If default.aspx is missing from the list, add it to the beginning of the comma-separated list displayed. To improve performance, you can move default.aspx to the beginning of the list if it's not already there.

Authentication

1. Click the site's icon and ensure that the pane on the right-hand side shows the Features view.

2. Double-click the Authentication icon.

3. Right-click on Anonymous authentication and choose Disable.

Creating the WorkflowGen application

1. In IIS Manager, right-click on wfgen under the \wwwroot folder and select Convert to application.

2. Select the WorkflowGen application pool if it's not the default, then click OK.

Creating workflow applications and services

The \wfgen\ws and \wfgen\WfApps\WebForms applications within WorkflowGen must be created. To do this, repeat the same steps you performed for \wfgen in the previous section.

ISAPI and CGI restrictions

If you're using IIS 8 and above and your application pool is set to use Classic Managed Pipeline Mode, make sure ASP.NET v4.0.30319 is set to Allowed in the IIS manager ISAPI and CGI Restrictions list.

Application files access configuration

File permissions

File permission settings can be configured as follows for the WorkflowGen application identity:

• DRIVE:\Inetpub\wwwroot\wfgen: Modify all

According to your authentication method (see ), the WorkflowGen application identity can be:

• The corresponding Windows users

• The ASP.NET or IIS application pool identity

Configuring the WorkflowGen root website to auto-redirect to the wfgen web app

If you'd like your WorkflowGen root website (e.g. https://server) to auto-redirect to the https://server/wfgen web app, follow the procedure below.

1. Make sure the tool is installed on your WorkflowGen server.

2. Create or update the web.config file in your website's root folder (e.g. DRIVE:\inetpub\wwwroot\web.config). ⚠️ Warning: This is not the same web.config file as the main WorkflowGen web.config file (located in DRIVE:\inetpub\wwroot\wfgen\web.config).

WorkflowGen Node.js-based web applications

To use the optional GraphQL, incoming webhooks, OpenID Connect Auth, and SCIM APIs, you must first install the following requirements:

Enabling WorkflowGen GraphQL

1. In IIS, convert /wfgen/graphql to an application with a .NET 4 application pool (integrated pipeline).

2. Configure the GraphQL application authentication mode:

   • For Windows or Basic authentication: Enable Basic authentication.

Enabling WorkflowGen incoming webhooks

In IIS, convert /wfgen/hooks to an application with a .NET 4 application pool (integrated pipeline), and configure the webhook application in Anonymous authentication mode.

Enabling WorkflowGen OpenID Connect Auth

In IIS, convert /wfgen/auth to an application with a .NET 4 application pool (integrated pipeline), and configure the application in Anonymous authentication mode.

Enabling WorkflowGen SCIM

In IIS, convert /wfgen/scim to an application with a .NET 4 application pool (integrated pipeline), and configure the application in Anonymous authentication mode.

Overview

This section details the different methods to authenticate WorkflowGen users. Choose one of them according to your needs and apply the required settings to implement it with your WorkflowGen instance.

Authentication methods

Open ID Connect

• (formerly Azure Active Directory)

Classic authentication methods

• (ensured by IIS)

• (ensured by IIS)

• (ensured by HttpModule)

• (ensured by HttpModule)

Authentication method support by application

The WorkflowGen server and mobile applications can be configured to use OpenID Connect (OIDC) compliant or classic authentication methods. The following table shows the authentication methods supported by the different WorkflowGen applications:

* Except Microsoft Identity Platform v2.0.

Classic authentication method configuration

See below for information and instructions on how to configure the classic non-OIDC , , , , and authentication methods.

Which classic authentication method to choose?

If you don’t know which authentication method to choose, follow the procedures below based on your situation:

1. If all WorkflowGen users are managed in Active Directories, which is accessible from the web server hosting WorkflowGen, then you can choose one of these authentication methods:

   • Integrated Windows authentication (ensured by IIS)

   • IIS HTTP Basic authentication (ensured by IIS)

2. If item 1 above applies to your situation, and you want to provide transparent authentication by using the current Windows session of the users, choose the following authentication method:

Integrated Windows authentication

IIS and WorkflowGen settings

1. Open the WorkflowGen Configuration Panel. In the Authentication section on the General tab, select IIS mode.

2. Enable Integrated Windows authentication access on the WorkflowGen website and disable all built-in access mechanisms. Apply this setting on all sub-applications except the graphql and ws applications.

IIS HTTP Basic authentication

IIS and WorkflowGen settings

1. Open the WorkflowGen Configuration Panel. In the Authentication section on the General tab, select IIS mode.

2. Enable Basic authentication access on the WorkflowGen website and disable all built-in access mechanisms. Apply this setting to all sub-applications as well.

WorkflowGen HTTP Basic authentication

IIS and WorkflowGen settings

1. To use WorkflowGen authentication, ensure that the directories have the Passwords are managed by WorkflowGen option selected, which allows you to set up a password for each user. Ensure that your current user has a WorkflowGen password associated with it, or you'll be locked out.

2. Open the WorkflowGen Configuration Panel and change the settings in the Authentication section on the General tab as follows:

   1. Set Mode to WorkflowGen.

Custom HTTP Basic authentication

IIS and WorkflowGen settings

1. Using the sample code in the section in the , create a new class for the HTTP module you're creating.

2. Modify the sample code to validate the credentials passed over HTTP Basic against the external configuration repository.

3. Build your module and copy the assembly DLL into the \wfgen\bin and \wfgen\wfapps\webforms\bin folders.

Form authentication

IIS and WorkflowGen settings

1. Modify the login.aspx code to validate the credentials passed over HTTP Basic against the external configuration repository. If you don’t have any external configuration repository, you can add users directly in the web.config of WorkflowGen (refer to the .NET documentation).

2. The login.aspx file must be copied to all of your webforms folders. This should only be applied to webforms. Web services must continue to use either Basic or Integrated authentication and therefore the login.aspx page cannot be used for them.

3. In the WorkflowGen web.config

FIPS compliance configuration

As of version 7.10.0, WorkflowGen is FIPS compliant and compatible with Windows FIPS compliant mode. If you want to enable FIPS compliance in your Windows environment, you have to configure the configuration password management and user password management modes beforehand.

Configuration password management mode

In the Security section on the Configuration Panel General tab, set Configuration password management mode to AES (FIPS Compliant) and enter a 32-character encryption key. When you click Save, the application passwords will automatically be converted to the new symmetric encryption mode.

User password management mode

In the Authentication section on the Configuration Panel General tab, set Password management mode to One-way Hashing (SHA256 FIPS Compliant) mode.

• If you're using applicative authentication in Version 5 (Legacy) password management mode, users' passwords will automatically be converted into One-way Hashing (SHA256 FIPS Compliant) the next time they log in to WorkflowGen.

• If you're using applicative authentication in One-way Hashing (SHA256) password management mode:

  1. Select IIS authentication mode.

HTTPS: Using SSL with WorkflowGen

Overview

This section describes how to configure WorkflowGen to use SSL connection security level on the website.

IIS configuration

Activate SSL authentication for your WorkflowGen website.

Application parameters to update

You must update the following parameter in the WorkflowGen configuration (click on the Configuration Panel from the Administration Module home page):

• Web application URL: you must update the protocol of the base URL of the application to https://.

Links to WorkflowGen

Change the links to WorkflowGen to use https:// instead of http://.

Cross-origin resource sharing (CORS)

In order to allow a client application (such as front-end JavaScript code from an outside domain) to access and request data, you must enable and configure the (CORS) settings. To do this:

1. Install the on the WorkflowGen web server.

2. Add the cors node with the list of external domains and their methods and headers (where HTTP requests will be allowed) to the WorkflowGen web configuration settings (located in \wfgen\web.config). See some common examples below.

📌 Example 1: Allow all origins

📌 Example 2: Allow specific origins

For more information about the CORS configuration, see the .

Overview

This section provides instructions on:

• AD FS 2016 authentication: How to configure WorkflowGen authentication using AD FS OpenID Connect.

• : How to authorize WorkflowGen access to mobile apps using AD FS OpenID Connect.

• : How to authorize WorkflowGen access to server-side scripts using AD FS OpenID Connect.

• : How to authorize WorkflowGen access to single-page applications using AD FS and OpenID Connect.

• : How to generate a universal link to simplify the WorkflowGen Plus mobile app user login.

AD FS authentication

This section provides instructions on how to configure WorkflowGen delegated authentication with Active Directory Federation Services (AD FS) OpenID Connect, and will show you how to set up a working WorkflowGen instance using AD FS OpenID Connect to authenticate your users.

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 installed and configured AD FS 2016 or later on a server.

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

• Make sure to have provisioned an existing Active Directory 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.

Note on provisioning users and groups

WorkflowGen supports the synchronization of Active Directory users and groups; for instructions on how to configure this, see the section in the .

AD FS configuration

Configuring AD FS is very simple: you just need to add a new application group within which you then configure a server application and a web API.

Step 1: Register a new application group

1. In the server manager, open AD FS Management.

2. Click the Application Groups directory in the left-hand pane, then click Add Application Group in the right-hand pane.

3. In the Add Application Group Wizard screen that opens:

You should now have an application group containing two applications: the WorkflowGen server application (which is the web application) and the WorkflowGen GraphQL API.

Step 2: Add the UPN to the access token

By default, a user UPN isn't included in the access token returned by AD FS, so you have to configure an Issuance Transform Rule for the GraphQL API that passes through the UPN. To do this:

1. In AD FS Management, click the Application Groups directory to the left, then double-click the WorkflowGen group.

2. You should now see all of the group's applications in a new window. Double-click WorkflowGen GraphQL API in the list.

3. On the Issuance Transform Rules tab, click Add Rule.

AD FS is now configured for WorkflowGen to delegate its authentication to it.

WorkflowGen configuration

Now, you need to configure WorkflowGen to delegate its authentication to AD FS.

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

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

• Replace <CLIENT ID> with the client identifier generated by AD FS for the WorkflowGen application.

• Replace <CLIENT SECRET> with the shared secret generated for the WorkflowGen application.

• Replace <METADATA URL> with the AD FS server's metadata URL. By default, it should look something like https://<adfs url>/adfs/.well-known/openid-configuration

WorkflowGen is now linked to AD FS 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>:

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 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 shouldn't because they're either public or aren't part of the global authentication system.

1. In the WorkflowGen web.config, add the following property:

2. In the auth module's web.config, add the following property:

   This line removes the authentication Node.js module from the global authentication system, because this Node.js application encapsulates the OpenID Connect authentication mechanisms.

Configuring the authentication without the GraphQL API

AD FS configuration for WorkflowGen Plus v2

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 AD FS for the WorkflowGen Plus mobile application so that your mobile users can benefit from delegated authentication as well.

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

Prerequisites

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

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

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

AD FS configuration

This configuration is done in several steps. First, you have to register a new native application in AD FS. Then, you have to give the application the necessary permissions to access the WorkflowGen GraphQL API.

Step 1: Register a new native application

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. Click Add application.

3. Configure the application:

You've now added the WorkflowGen Plus native application in your AD FS WorkflowGen application group.

Step 2: Grant access to the WorkflowGen GraphQL API

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. Double-click on the WorkflowGen GraphQL API application.

3. On the Client Permissions tab, click the WorkflowGen Plus application, then click Add.

AD FS 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 AD FS with a server-side script that has access to the GraphQL API.

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 AD FS to be able to configure it properly.

• Make sure to have successfully configured delegated authentication to AD FS on your WorkflowGen instance following the instructions in the

AD FS configuration

Step 1: Register a new server application

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. In the WorkflowGen Properties window, click Add application.

3. Select the Server application type, then click Next.

You should now see your new server application listed in the WorkflowGen application group.

Step 2: Grant access to the GraphQL API

Now that you've created your server application, you need to grant it access to the GraphQL API. To do this:

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. In the WorkflowGen Properties window, double-click WorkflowGen GraphQL API.

3. On the Client Permissions tab in the WorkflowGen GraphQL API Properties window, click Add.

You've now registered your server application in AD FS and granted it access to the WorkflowGen GraphQL API.

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

Your application should now appear in the list of applications.

AD FS 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: )

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 AD FS with a single-page application (SPA) so that users can authenticate through it and make requests to the WorkflowGen GraphQL API.

Prerequisites

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

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

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

AD FS configuration

Currently, AD FS only supports three types of applications: Native, Server, and Web API. As you can see, there's nothing for single-page applications in browsers or even regular web applications that renders pages on the server. However, you can use the supported types to get what you need. The Native application type enables you to retrieve a client ID and to specify a callback URI that can be used to perform an implicit grant flow with a single-page application; AD FS will answer as expected since it supports the OpenID Connect protocol.

This configuration is done in several steps. First, you have to register a new native application in AD FS. Then, you have to give the application the necessary permissions to access the WorkflowGen GraphQL API.

Step 1: Register a new native application

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. Click Add application.

3. Configure the application:

Step 2: Grant access to the WorkflowGen GraphQL API

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. Double-click on the WorkflowGen GraphQL API application.

3. On the Client Permissions tab, click the WorkflowGen Plus application, then click Add.

Generating a universal link for WorkflowGen Plus v2

As of WorkflowGen server version 7.11.2, you can generate a universal link to simplify the AD FS 2016 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: adfs

• server_address: Your WorkflowGen application URL, whose value must be URL encoded (e.g. https://mycompany.com/wfgen)

• client_id: Use the client ID you created earlier in the configuration (e.g. 6g909d00-8580-49a4-9003-a30f6b87ae86

The universal link should follow this format:

Additional information on AD FS 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.

Configurable options

This table lists all configurable options in WorkflowGen that you can use to customize your authentication experience; these are located in the WorkflowGen web.config file.

Overview

This section provides instructions on:

• Auth0 authentication: How to configure WorkflowGen authentication using Auth0.

• : How to create a directory with the self-provisioning connector.

• : How to authorize WorkflowGen access to mobile applications using Auth0.

• : How to authorize WorkflowGen access to server-side scripts using OpenID Connect and Auth0.

• : How to authorize WorkflowGen access to single-page applications using Auth0.

• : How to authorize Auth0 access to the WorkflowGen command line interface.

• : How to generate a universal link to simplify the WorkflowGen Plus mobile app user login.

It also provides additional information on and .

Prerequisites

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

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

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