Read Scale-Out configuration

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

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

   For more information, see the Install Azure PowerShell Microsoft article.

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

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

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

Step 2: Configure WorkflowGen

1. Go to the Database section on the Configuration Panel General tab. 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:

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

4. Check the Multi-database option. Check the User Portal components and modules that will use the Read-only database. For more information about this, see in the .

Step 1: Create the Azure Load Balancer

Via the Azure Portal

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

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

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

• A virtual network

• Two virtual machines with IIS installed on both

• A network security group

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

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

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

Via the Azure CLI

To create a Load Balancer and its components via the Azure CLI, first sign in to your Azure account with Azure CLI, then follow the steps below:

1. Create a public IP address.

2. Create a load balancer with its resources (back-end address pool, health probe and a load balancer rule). ✏️ Note: You can configure the sticky-session by using the --load-distribution parameter in the script. For more details about all parameters supported see the Manage load balancing rules Microsoft article. If Session State is enabled in the web forms, the sticky-session is mandatory (see the How to enable Session State in the WebForms application WorkflowGen Knowledge Base article for more information).

3. Create and configure the virtual network. ✏️ Note: The network security group and its rules will be created when configuring the virtual network. It is recommended to add an RDP rule for testing purposes.

4. with IIS installed on both.

Step 2: Install and configure WorkflowGen

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

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

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

   • An OR

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

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

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

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

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

Step 3: Configure the web farm

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

• A common WebForms folder

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

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 Microsoft Entra ID for mobile apps so that your mobile users can benefit from delegated authentication to ME-ID as well.

Prerequisites

• Make sure to have a licensed copy of WorkflowGen installed and running on an IIS web server in HTTPS secure connection mode.

• Make sure to have administrative access to ME-ID to be able to configure it properly.

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

• Make sure to have successfully configured delegated authentication to ME-ID with the Microsoft Identity Platform v2.0 provider on your WorkflowGen instance following the instructions in the section with the WorkflowGen GraphQL API application registered as well.

Microsoft Entra ID configuration

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

Step 1: Register a new native application

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

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

   • Name: WorkflowGen Plus

   • Supported account types: Accounts in this organizational directory only (Default Directory only - Single tenant) ✏️ Note: Depending on the context, you should choose the right option for your use case for the supported account type value.

   • Redirect URI:

     • Type: Public client/native

     • Value: workflowgenplus://oidc

3. Click Register at the bottom of the page.

You've now successfully registered your WorkflowGen Plus native application in Microsoft Entra ID.

Step 2: Grant access to WorkflowGen GraphQL API

1. Click API permissions.

2. In the Configured permissions section, click Add a permission.

3. Click My APIs, then select the WorkflowGen GraphQL API application in the list.

4. Click Delegated permissions and check default under the Permission column.

5. Click Add permissions.

6. On the API permissions page, click Grant admin consent for <your tenant name>, then click Yes.

Review the registration

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

• A server address: This is your WorkflowGen application URL (e.g. https://<workflowgen url>).

• A client ID: This is the application (client) ID in the Overview section of your application registration.

• A tenant ID: This is the directory (tenant) ID in the Overview section of your application registration.

• An audience: This is the Application ID URI property (e.g. https://<workflowgen url>/graphql) in the Expose an API section of the WorkflowGen GraphQL API application registration.

You'll need to give the server address, client ID, tenant ID , and audience information to the users who will be using the WorkflowGen Plus v2 mobile application. ME-ID delegated authentication won't work unless they copy this information into the mobile app.

• Make sure to have a licensed copy of WorkflowGen installed and running on an IIS web server in HTTPS secure connection mode.

• Make sure to have Microsoft Entra ID (ME-ID) administrator access to be able to configure it.

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

• Make sure to have successfully configured delegated authentication to ME-ID with the Microsoft Identity Platform v2.0 provider on your WorkflowGen instance following the instructions in the section with the WorkflowGen GraphQL API application registered as well.

Interactive mode

Microsoft Entra ID configuration

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

Step 1: Register a new native application

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

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

   • Name: WorkflowGen CLI

   • Supported account types: Accounts in this organizational directory only (Default Directory only - Single tenant) ✏️ Note: Depending on the context, you should choose the right option for your use case for the supported account type value.

   • Redirect URI:

     • Platform: Public client/native (mobile & desktop)

     • Value: http://127.0.0.1:8888/callback

   ✏️ Note: Port 8888 is defined by default; you can change it if it's already in use on your computer.

3. Click Register at the bottom of the page.

You've now successfully registered your WorkflowGen CLI native application in ME-ID.

Step 2: Grant access to the GraphQL API

1. Click API permissions.

2. In the Configured permissions section, click Add a permission.

3. Click My APIs, then select the WorkflowGen GraphQL API application in the list.

4. Click Delegated permissions and check default under the Permission column.

5. Click Add permissions.

6. On the API permissions page, click Grant admin consent for <your tenant name>, then click Yes.

Review the registration

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

• A client ID: This is the application (client) ID in the Overview section of your application registration.

• A tenant ID: This is the directory (tenant) ID in the Overview section of your application registration.

You'll need to give this information to the users who will be using the WorkflowGen CLI.

Non-interactive mode

The configuration of non-interactive mode is the same as in the Microsoft Entra ID Configuration for Server-Side Scripts section.

You can use Azure Active Directory to authenticate and authorize users in the cluster. See the Integrate Azure Active Directory with Azure Kubernetes Service using the Azure CLI Microsoft article for more information.

Managing Windows and Linux nodes

By default, AKS doesn't restrict further Windows nodes from preventing Linux deployment on them. It's recommended to use taints and tolerations to avoid problems with Linux deployment being scheduled to Windows nodes. The following is an example of how you can use taints and tolerations to manage hybrid deployments.

Taint all Windows nodes

Tainting all Windows nodes will prevent any deployment to Windows nodes from being scheduled except when it has the required toleration. Therefore, for many Linux Helm charts that don't have a node selector, the deployments to Linux nodes will automatically be scheduled. Google Kubernetes Engine does this by default. Execute the following command to taint a Windows node:

Add tolerations to Windows deployments

To be able to deploy Windows pods to Windows nodes, you have to use a combination of tolerations and node selectors in your deployment specification. For example, consider this WorkflowGen deployment:

In order for it to be scheduled to a Windows node, you would have to add the following to the template's spec:

This adds a toleration for the taint that you've just added to the node and tells the Kubernetes scheduler to select a Windows node when scheduling the WorkflowGen pods.

You can also simplify this by creating a RuntimeClass object that holds this information and referencing the runtime class in your Windows deployments:

Apply this file:

Then, add the following to the template's spec:

As you can see, this RuntimeClass also ensures that the deployment will be on a Windows LTSC 2019 (1809) node.

Managing node updates

There are two things that you must consider for update management: the Kubernetes version and the operating system update. For information on upgrading the cluster to a specific Kubernetes version, see Upgrade an Azure Kubernetes Service (AKS) cluster.

Applying security patches and updating operating systems differ for Linux and Windows nodes. To get started with operating system updates, see Apply security and kernel updates to Linux nodes in Azure Kubernetes Service (AKS) for more information. (Don't worry about the title of the article; there's a paragraph about Windows updates in it.)

Automatically scaling node pools

You can use an autoscaler in AKS to automatically scale up the number of nodes in your cluster based on rules to keep up with demands. See Automatically scale a cluster to meet application demands on Azure Kubernetes Service (AKS) for more information. This feature pairs well with the Kubernetes horizontal pod autoscaler. See Horizontal Pod Autoscaler for more information.

You can also use Azure Container Instances to quickly scale up your cluster for a short period of time. See Scaling options for applications in Azure Kubernetes Service (AKS) for more information.

Supported account types: Accounts in this organizational directory only (Default Directory only - Single tenant)

Server address: outlook.office365.com, or your own Exchange Online domain name

Click Delegated permissions and check default under the Permission column.

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.

Configuring Azure Files for WorkflowGen

Prerequisites

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

• Make sure to know the address of the instance.

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

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

• An active Azure subscription.

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

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

Step 1: Create a storage account in Azure

Via the Azure Portal

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

2. Add a new storage account.

3. Enter a name.

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

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

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

6. Performance: Choose Standard.

7. Choose your subscription.

8. Create a new resource group.

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

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

10. Click Create.

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

Via the Azure CLI

To create a storage account via the Azure CLI, first sign in to your Azure account with Azure CLI.

The following script creates a storage account in Azure. The resource group name variable ($resourceGroup) and storage account variable ($storageAccount) should be updated.

Step 2: Create a file share in Azure

Via the Azure Portal

1. In the Storage accounts service, choose wfgendatastorage.

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

3. Add a new File share.

4. Enter a name.

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

5. Enter a quota according to your needs.

6. Click OK.

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

Via the Azure CLI

To create a file share via the Azure CLI, first sign in to your Azure account with Azure CLI.

The following script creates a file share in Azure. The storage account variable ($storageAccount) and file share variable ($share) should be updated.

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

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

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

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

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

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

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

   For more information, see .

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

   1. Enter a new username and password.

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

   2. Check User cannot change password.

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

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

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

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

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

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

10. 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:

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

    If successful, you should then see:

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

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

Step 4: Configure WorkflowGen to use the file share

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

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

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

   • Identity: wfgen_service

   • Load User Profile: True

4. Save the changes, then restart IIS.

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

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

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

7. Update the WorkflowGen web configuration file:

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

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

Appendix: Viewing Azure Files share content

Use one of the following methods:

• In your Azure portal storage account:

  • Use the Storage Explorer (preview) tool.

    or

  • Browse the wfgenshare file share under the Files section.

  OR

• Mount the file share wfgenshare in Windows. To do this:

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

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

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

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

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

✏️ 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.

✏️ Note: Do not run the Remove my public IP script if you need access to the database from your desktop or if your WorkflowGen server is not hosted by Azure.

Click Delegated permissions and check default in the Permission column.

This section provides instructions on how to configure WorkflowGen delegated authentication with Microsoft Entra ID (ME-ID) authentication via the Microsoft Identity Platform v2.0 or API endpoint v1 providers, and will show you how to set up a working WorkflowGen instance that uses ME-ID to authenticate your users.

Prerequisites

• Make sure to have a licensed copy of WorkflowGen installed and running on an IIS web server in HTTPS secure connection mode.

• You must be a WorkflowGen Administrator.

• Make sure to have ME-ID Administrator access to be able to configure ME-ID.

• Make sure to have provisioned an existing ME-ID user that you can authenticate with WorkflowGen and that the user has WorkflowGen Administrator permissions. This is important because once you've activated the delegated authentication with ME-ID, you'll still need to be able to manage the WorkflowGen web application.

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

Microsoft Entra ID configuration

The configuration of ME-ID is done in two parts. 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 in order to be able to register other custom applications to access it.

Step 1: Create a new application registration for WorkflowGen

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

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

   • Name: WorkflowGen Web app

   • Supported account type: Account in this organizational directory only (Default Directory only - Single tenant)

     ✏️ Note: Depending on the context, you should choose the right option for your use case for the Supported account type value.

   • Redirect URI:

     • Platform: Web

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

     📌 Example: https://mycompany.com/wfgen/auth/callback

3. Click Register at the bottom of the page.

You should now see the WorkflowGen Web app application registration's overview page.

Step 2: Create a client secret for the application

Now, you have to generate a client secret to be used by the WorkflowGen OIDC authentication module.

1. Click Add a certificate or secret.

2. In the Client secrets section, click New client secret.

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

   • Expires: Choose 730 days (24 months) or your desired expiration period.

3. Click Add.

4. The auto-generated client secret is now displayed under the Value column. Copy the client secret value and save it somewhere safe, since you won't be able to retrieve it afterwards.

Step 3: Add a redirect URI

In order for the communication between the WorkflowGen instance and ME-ID to work, you need to add one more authorized redirect URI to the WorkflowGen Web app application registration.

1. Under Redirect URIs on the application's overview page, click Add a Redirect URI.

2. Enter the following information:

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

3. Click Save at the bottom of the section.

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

In order to expose the WorkflowGen GraphQL API, you need to add a new application registration in ME-ID that will represent it. To do this:

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

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

   • Name: WorkflowGen GraphQL API

   • Supported account type: Account in this organizational directory only (Default Directory only - Single tenant)

   • Redirect URI: Leave this blank.

3. Click Register at the bottom of the page.

You've now successfully registered the WorkflowGen GraphQL API application in ME-ID.

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

1. Click Expose an API.

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

3. Click Save.

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

   • Scope name: default

   • Who can consent?: Admins and users
5. Click Add scope.

You should now have a new scope defined (e.g. https://<workflowgen url>/graphql/default).

Step 6: Grant WorkflowGen access to WorkflowGen GraphQL API

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

2. Click Add a permission, then select the tab My APIs.

3. Click the WorkflowGen GraphQL API application in the list.

4. Click Delegated permissions and check default under the Permission column.

5. Click Add permissions.

6. On the API permissions page, click Grant admin consent for <your tenant name>, then click Yes.

Review the registrations

You should now have all of the information you need to configure your WorkflowGen instance to delegate authentication to Microsoft Entra ID Here's a review:

• A client ID. This is the application (client) ID of the WorkflowGen Web app application registration in ME-ID. You can find it on its Overview page.

• A client secret. This is the secret previously generated in step 2 for the WorkflowGen Web app.

• An audience. This is the Application ID URI property (e.g. https://<workflowgen url>/graphql) in the Expose an API section of the WorkflowGen GraphQL API application registration.

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

  1. Go to the Overview page and opy the Tenant ID value.

  2. The metadata endpoint URL is built by replacing <Tenant ID> with your Tenant ID as follows: For Microsoft Identity Platform v2.0 (recommended):

By now, you should have all the information needed to link your WorkflowGen instance to ME-ID.

WorkflowGen configuration

Now, you have to configure WorkflowGen to delegate its authentication to ME-ID.

Step 1: Add Microsoft Entra ID values to the WorkflowGen web.config

1. Open the WorkflowGen web.config file and add and/or update the following properties under <appSettings> For Microsoft Identity Platform v2.0 (recommended):

   For Azure v1:

   ✏️ Note: Check session iFrame (e.g. ApplicationSecurityAuthCheckSessionUrl) is not supported in Microsoft Identity Platform v2.0.

2. Replace <CLIENT ID> with the WorkflowGen Web app application (client) ID from ME-ID.

3. Replace <CLIENT SECRET> with the WorkflowGen Web app application registration's generated secret from ME-ID.

4. Replace <METADATA URL> with the metadata endpoint URL that you built earlier from your ME-ID's Tenant ID value.

5. For Microsoft Identity Platform v2.0, replace <workflowgen url> with your WorkflowGen URL in the value of the ApplicationSecurityAuthAdditionalScopes key (e.g. https://mycompany.com/wfgen/graphql/default) if you have configured the WorkflowGen GraphQL API application registration (steps 4 through 6). Otherwise, remove the ApplicationSecurityAuthAdditionalScopes key completely.

6. For Azure v1, replace <CHECK SESSION URL> (which is usually https://login.microsoftonline.com/<Tenant ID>/oauth2/checksession) with the value of the metadata endpoint's check_session_iframe property. To do this, you'll have to make an HTTP GET request to your metadata endpoint URL (e.g. https://login.microsoftonline.com/<Tenant ID>/.well-known/openid-configuration), then copy and paste the value. See the examples below on how to request the metadata endpoint.

   Linux/macOS request example:

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

Table of web.config options

WorkflowGen should now be linked to your ME-ID. The last thing left to do is to 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 the WorkflowGen session token generation

WorkflowGen uses an internal session token to manage the user session and identify the current user for all the HTTP requests made to the web application after the user has logged in to ME-ID. 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 and/or update the following property under <appSettings>:

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

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 module

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

Configure IIS

1. In IIS Manager, click on the WorkflowGen website 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 sub-applications

Certain sub-applications need to have their authentication checked by the special Advantys.Security.JWTAuthenticationModule WorkflowGen authentication module, but certain other sub-applications (such as /wfgen/auth, /wfgen/hooks and /wfgen/scim) should not because they are either public or aren't part of the global authentication system.

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

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

   • Advantys.My.dll

   • Advantys.Security.dll

   • Newtonsoft.Json.dll

   • jose-jwt.dll

Calling third-party APIs with the shared access token

By default, the only recipient of the access token is the WorkflowGen GraphQL API application. This means that the access token can only be used to send queries to the GraphQL API only. In order to use the same access token to call your own APIs from WorkflowGen (e.g. web forms), you will need to perform the following steps in your Azure portal, and then modify the WorkflowGen web.config file.

In your Azure portal:

Step 1: Add a new application registration that represents all your APIs

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

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

   • Name: My APIs

   • Supported account types: Account in this organizational directory only (Default Directory only - Single tenant) ✏️ Note: Depending on the context, you should choose the right option for your use case for the Supported account type value.

   • Redirect URI: Leave this blank

3. Click Register at the bottom of the page.

Step 2: Expose your APIs in the registration

1. Click Expose an API.

2. To the right of Application ID URI, click Set and enter the URI api://my-apis.

3. Click Save.

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

   • Scope name: wfgen-graphql-full-access

   • Who can consent?: Admins and users

5. Click Add scope.

6. Add any other scopes that seem necessary for your other APIs.

Step 3: Add an application role

1. Click Manifest.

2. Find the appRoles JSON property and add the following JSON object to the JSON array:

   ✏️ Note: Replace <NEW ID> with the value generated by the [guid]::NewGuid().ToString() PowerShell command or use any GUID generators.

3. Click Save.

Step 4: Grant WorkflowGen access to My APIs application

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

2. In the Configured permissions section, click Add a permission.

3. Click My APIs, then select the My APIs application in the list.

4. Click Delegated permissions and check wfgen-graphql-full-access under the Permission column.

5. Click Add permissions.

6. On the API permissions page, click Grant admin consent for <your tenant name>, then click Yes.

Step 5 (optional): Grant your automated applications in Azure (client credentials flow) access to the My APIs application

For each of your automated applications in Azure (e.g. server-side script, background service, or application) that requires access to the My APIs application, do the following:

1. Go to the application's registration page, then click API permissions.

2. In the Configured permissions section, click Add a permission.

3. Click My APIs, then select the My APIs application in the list.

4. Click Application permissions and check wfgen-graphql-full-access-role under the Permission column.

5. Click Add permissions.

6. On the API permissions page, click Grant admin consent for <your tenant name>, then click Yes.

In the WorkflowGen web.config file:

Open the WorkflowGen web.config file, add and/or update the following application settings, then save the file:

.NET Web Forms Access Token Helper

The WorkflowPage class in the WorkflowGen.My library provides a public CurrentUserAccessToken method to easily retrieve the current user's shared access token that can be used to query the GraphQL API and your third-party APIs. See the snippet code below.

Additional information

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 (i.e. users and groups) for the SOAP API users.

2. Provision it with users and groups as needed.

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

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

About session management

Microsoft Entra ID supports OpenID Connect Session Management, an extension draft standard, in addition to the core OpenID Connect standard. This standard defines the rules to handle SSO session of the provider from the client. An example use is that if a user logs out of their ME-ID 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 ME-ID.

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.

Current limitations

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

Configuring the authentication without the GraphQL API

If for some reason you can't register the WorkflowGen GraphQL API application and you don't need GraphQL API authentication configured with the provider, you can avoid creating the registration and configure WorkflowGen with the Microsoft Graph API instead, which is included by default in all application registrations. To configure it, you only have to change some configuration options in the web.config file:

1. Change the ApplicationSecurityAuthAudience key to the Microsoft Graph API URL, e.g.https://graph.microsoft.com.

2. Set the ApplicationSecurityAuthDecodeAccessToken option to N.