Authentication

Overview

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

In the server manager, open AD FS Management.
Click the Application Groups directory in the left-hand pane, then click Add Application Group in the right-hand pane.
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.
Click Next.
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.
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.
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.
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:

In AD FS Management, click the Application Groups directory to the left, then double-click the WorkflowGen group.
You should now see all of the group's applications in a new window. Double-click WorkflowGen GraphQL API in the list.
On the Issuance Transform Rules tab, click Add Rule.
On the Select Rule Template screen, select the Pass Through or Filter an Incoming Claim claim rule template, then click Next.
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.

For information about available configuration options to use with your instance, see the Web and Application Configuration Parameters appendix.

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.

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.

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

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

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

In IIS Manager, click the WorkflowGen application in the tree view.
Click the Authentication button.
Enable Anonymous Authentication and disable all other authentications.
Perform these steps for all sub-applications as well.

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.

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>

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.
Repeat the above two steps for the hooks and scim modules as well.
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.