AD FS Integration

Overview

This section provides instructions on:

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

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

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

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

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

• This integration is specific to AD FS 2016.

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

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.

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

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 Advanced Configuration section in the WorkflowGen Technical Guide.

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:

   1. Enter the name of the group: WorkflowGen

   2. Select the template: Server application accessing a web API.

4. Click Next.

5. On the Server application screen:

   1. Enter the name of the application: WorkflowGen - Server application

   2. Copy the client identifier, which you'll need in the WorkflowGen configuration later.

   3. Enter the redirect URI: https://<workflowgen url>/auth/callback

   4. Click Add. You should now see the redirect URI in the list below the Redirect URI field.

      
   5. Click Next.

6. On the Configure Application Credentials screen, you'll generate a client secret:

   1. Check only the Generate a shared secret checkbox.

   2. Copy the generated secret; you won't be able to retrieve it afterwards.

      
   3. Click Next.

7. On the Configure Web API screen, you'll configure the WorkflowGen GraphQL API name and identifier:

   1. Enter the name of the application: WorkflowGen GraphQL API

   2. Enter the API identifier: https://<workflowgen url>/graphql

   3. Click Add.

      
   4. Click Next.

8. On the Configure Application Permissions screen, you'll configure GraphQL access to the WorkflowGen web application:

   1. Make sure the WorkflowGen web application (WorkflowGen - Server application) is in the Client application list.

   2. Check the openId, profile, and email checkboxes.

      
   3. Click Next.

   4. Review the summary section and complete the application group.

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.

4. On the Select Rule Template screen, select the Pass Through or Filter an Incoming Claim claim rule template, then click Next.

5. On the Configure Rule screen:

   1. Enter Pass through UPN in the Claim rule name field.

   2. Select UPN in the Incoming claim type drop-down list

   3. Make sure that Pass through all claim values is selected.

      
   4. Click Finish.

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

<!-- ADFS auth -->
<add key="ApplicationSecurityAuthProvider" value="adfs"/>
<add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" />
<add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" />
<add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" />
<add key="ApplicationSecurityAuthAppIdClaim" value="appid" />
<add key="ApplicationSecurityAuthUsernameClaim" value="upn" />
<add key="ApplicationSecurityAuthClockTolerance" value="60" />
<add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/>

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

• If your server blocks browsers from embedding web content in iFrames (by returning the X-Frame-Options: DENY header), it is strongly recommended that you set the value of ApplicationSecurityAuthSessionRefreshEnableIFrame to N. Otherwise, when the session expires and a user submits a form, they will be redirected for authentication and lose the data they entered in the form.

• If you're using AD FS 2016 or later, you can configure the X-Frame-Options header to allow specified origins to embed AD FS content in an iFrame. In this case, you can set the value of ApplicationSecurityAuthSessionRefreshEnableIFrame to Y, because the automatic refresh will work as expected.

Table of web.config options

Option	Description
ApplicationSecurityAuthProvider	The name of the supported identity provider supported by WorkflowGen. At this time, there is support only for AD FS, Azure Active Directory, Auth0, Okta, and Microsoft Identity Platform v2.0 Value: adfs, azure-v1, auth0, okta, or ms-identity-v2
ApplicationSecurityAuthClientId	Each identity provider generates a code that uniquely identifies your application. In this case, this is the code that uniquely identifies the WorkflowGen web application.
ApplicationSecurityAuthClientSecret	Like the client ID, this is also generated by the identity provider, but it is more like what a password is for a user. It's important to keep this secret because malicious software that has access to this can act on the behalf of the application. For AD FS, this option must be selected.
ApplicationSecurityAuthMetadataUrl	The endpoint provided by the identity provider that supports the OpenID Connect Discovery standard. It enables WorkflowGen to get some public information about your Azure Active Directory or Auth0 domain. Without this, you'll have to manually enter much more configuration in the web.config.
ApplicationSecurityAuthAppIdClaim	The name of the claim contained in the access token obtained from the identity provider that uniquely identifies a non-interactive client. This is only used if you have a machine-to-machine application that needs to have access to the GraphQL API. To configure this, see the AD FS configuration for single-page applications section. ✏️ Note: It's recommended to keep the default value.
ApplicationSecurityAuthUsernameClaim	The name of the claim contained in the access token that identifies the user in WorkflowGen. This is used by WorkflowGen to generate a session token as well as by the GraphQL API when receiving an access token. ✏️ Note: It's recommended to keep the default value.
ApplicationSecurityAuthClockTolerance	This value is used when verifying a token in WorkflowGen. It's essentially to deal with minor differences between servers' clocks. ✏️ Note: It's recommended to keep the default value.
ApplicationSecurityAuthSessionRefreshEnableIFrame	When enabled (Y), this option activates the session auto-refresh feature using an invisible <iframe>. This allows users to enter their password less often by refreshing their session in the background while they're working. ✏️ Note: This option is only available when using WorkflowGen with OIDC authentication.

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

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

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

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

Step 3: Activate the authentication delegation

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

Configure IIS

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

2. Click the Authentication button.

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

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

Add properties to the web.config files of certain modules

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

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

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

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

   <?xml version="1.0" encoding="UTF-8"?>
   <configuration>
    <system.webServer>
        <modules>
            <remove name="ApplicationSecurityAuthenticationModule"/>
        </modules>
    </system.webServer>
   </configuration>

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

3. Repeat the above two steps for the hooks and scim modules as well.

4. Copy the following .NET assemblies and dependency libraries from \wfgen\bin to each custom webform's \bin folder (\wfgen\wfapps\webforms\<custom webform>\bin):

   • Advantys.My.dll

   • Advantys.Security.dll

   • Newtonsoft.Json.dll

   • jose-jwt.dll

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

AD FS configuration for mobile apps

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

This section provides instructions on how to configure 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 Generating a universal link for WorkflowGen Plus section.

Prerequisites

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

• Make sure to have administrative access to 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.

• Make sure to have the latest WorkflowGen Plus version installed on your device and that your device is supported.

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

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:

   1. Name: WorkflowGen Plus

   2. Copy the client identifier, which you'll need in the application.

   3. Redirect URI: workflowgenplus://auth.authenticate

4. Click Add, then click Next.

5. Review the configuration; once you've finished, click Next and then Close.

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.

4. Select WorkflowGen Plus in the application permissions list.

5. Make sure that the openid, profile, and email scopes are checked.

6. Click OK, then click OK in the WorkflowGen application group menu.

You've now configured WorkflowGen Plus within AD FS.

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 authentication section.

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.

4. Configure the server application:

   1. Name: My Server Application

   2. Copy the client identifier, which you'll need for the client credentials grant flow. You won't be able to retrieve it afterwards.

   3. Add a redirect URI. Here, it doesn't matter what you enter because the client credentials grant doesn't use this value.

   4. Click Add, then click Next.

5. In the Configure Application Credentials window, generate a client secret for the server application:

   1. Check the Generate a shared secret checkbox.

   2. Copy the value; you'll need it for the client credentials grant flow.

   3. Click Next.

6. Review the configuration; once you've finished, click Next.

7. Click Close.

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.

4. Click the server application that you created in the previous section, then click Add.

5. You should now see your server application in the list of client applications; make sure it's selected.

6. Make sure that the openid, profile, and email scopes are checked.

   
7. Click OK.

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

   • Description: A description that clearly identifies the script.

   • Type: Non Interactive Client

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

   • Client ID: The client ID you copied earlier.

   • Active: Check this checkbox.

3. Click Save.

Your application should now appear in the list of applications.

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

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: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant)

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

This section provides instructions on how to configure 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.

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

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:

   1. Name: My Single-Page App

   2. Copy the client identifier, which you'll need in the application.

   3. Redirect URI: https://mysinglepageapp.com/callback

4. Click Add, then click Next.

5. Review the configuration; once you've finished, click Next and then Close.

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.

4. Select My Single-Page App in the application permissions list.

5. Make sure that the openid, profile, and email scopes are checked.

6. Click OK, then click OK in the WorkflowGen application group menu.

You've now configured your single-page app within AD FS.

Generating a universal link for WorkflowGen Plus

As of WorkflowGen Plus version 1.2.0 and WorkflowGen server version 7.11.2, you can generate a universal link to simplify the 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

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

• domain: The AD FS domain name without URL protocol (e.g. mycompany.com)

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

The universal link should follow this format:

workflowgenplus://auth.init?provider=adfs&client_id=6g909d00-8580-49a4-9003-a30f6b87ae86&domain=mycompany.com&audience=http%3A%2F%2Fworkflow.mycompany.com%2Fwfgen

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

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

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

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

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.

Option	Description
ApplicationSecurityAuthSessionTokenCookie	The name of the session cookie that is generated by the authentication module. Default: wfgen_token ✏️ Note: This is useful when you have multiple instances of WorkflowGen running and you want to have access to both and be authenticated on both instances at the same time.
ApplicationSecurityAuthSessionTimeOut	The duration of the session in seconds. It defaults to the ID token expiration time received. Default: the exp value of the ID token
ApplicationSecurityAuthMobileSessionTimeOut	The duration of the session in seconds when requested from mobile devices on the token endpoint. Default: 7200 seconds