Azure AD Authentication

Overview

This section provides instructions on how to configure WorkflowGen delegated authentication with Azure AD authentication API endpoint v1, and will show you how to set up a working WorkflowGen instance using Azure to authenticate your users.

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

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 Azure AD administrator access to be able to configure Azure AD.

  • Make sure to have provisioned an existing Azure AD user that you can authenticate with to WorkflowGen and that the user has administrator privileges. This is important because once you've activated the delegation, you'll still need to be able to manage the application.

Azure Active Directory configuration

The configuration of Azure AD is done in two steps. First, you have to register the WorkflowGen web application and link it to your instance of WorkflowGen; then, you have to register the WorkflowGen GraphQL API to be able to register custom applications to access it.

Step 1: Create a new web application

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

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

    • Name: WorkflowGen Web app

    • Application type: Web app / API

    • Sign-on URL: https://<workflowgen url>

  3. Click Create at the bottom of the page.

You should now see the WorkflowGen registered application's overview page.

Step 2: Create a client secret for the application

Now you have to generate a client secret to use in the WorkflowGen Authentication Module.

  1. Click Settings.

  2. In the Keys section, add a new key.

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

    • EXPIRES: Choose Never expires.

    • VALUE: Anything with sufficient entropy that it can't be guessed, such as a UUID.

  3. Click Save. The value you entered will now be encrypted.

  4. Save the generated value, since you won't be able to retrieve it afterwards.

Step 3: Register a new API application

You now need to register the WorkflowGen GraphQL API module as a new application. This will enable other applications to access the API while registering on Azure using the OpenID Connect protocol. To do this:

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

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

    • Name: WorkflowGen GraphQL API

    • Application type: Web app / API

    • Sign-on URL: https://<workflowgen url>/graphql

  3. Click Create at the bottom of the page.

You should now see the WorkflowGen GraphQL API registered application's overview page.

Step 4: Change the API's App ID URI

To make the audience value meaningful, you have to change its default value so that it points to your instance's GraphQL API. To do this:

  1. On the GraphQL API registered application's overview page, click Settings.

  2. Go to the Properties section.

  3. Change the App ID URI value to https://<workflowgen url>/graphql, then click Save.

Step 5: Add a reply URL

In order for the communication between WorkflowGen and Azure to work, you need to add authorized reply URLs to the registered WorkflowGen Web app web application.

  1. On the WorkflowGen Web app registered application's overview page, click Settings.

  2. Go to the Reply URLs section.

  3. Add the following URLs:

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

    • https://<workflowgen url>/auth/logout/return

Step 6: Grant access to the GraphQL API

Now, you have to give the WorkflowGen web app access to the GraphQL API. To do this:

  1. On the WorkflowGen Web app overview page, click Settings.

  2. Go to the Required permissions section.

  3. Click Add, then click Select an API.

  4. Search for the WorkflowGen GraphQL API.

  5. Click on the GraphQL API application, then click Select.

  6. Click Select permissions, then check all of the checkboxes.

  7. Click Select, then click Done.

You should now see the WorkflowGen GraphQL API in the list of required permissions.

Review the registrations

You should now have all of the information you need to configure WorkflowGen to delegate authentication to Azure AD. Here's a review:

  • A client ID. This is the application ID of the registered WorkflowGen app on Azure. You can find it on its overview page.

  • A client secret. This is the secret previously generated.

  • An audience. This is the App ID URI property of the GraphQL API registered application.

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

    1. Go to your directory properties section.

    2. Copy the Directory ID value.

    3. The metadata endpoint is built like this: https://login.microsoftonline.com/<Directory ID>/.well-known/openid-configuration.

By now you should have all the information needed to link your WorkflowGen instance to Azure AD.

WorkflowGen configuration

Now, you have to configure WorkflowGen to delegate its authentication to Azure AD.

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

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

    <!-- Azure v1 auth -->
    <add key="ApplicationSecurityAuthProvider" value="azure-v1"/>
    <add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" />
    <add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" />
    <add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" />
    <add key="ApplicationSecurityAuthCheckSessionUrl" value="<CHECK SESSION URL>" />
    <add key="ApplicationSecurityAuthAppIdClaim" value="appid" />
    <add key="ApplicationSecurityAuthUsernameClaim" value="upn" />
    <add key="ApplicationSecurityAuthClockTolerance" value="60" />
    <add key="ApplicationSecurityAuthSessionRefreshEnableIFrame" value="Y"/>
  2. Replace <CLIENT ID> with the application ID.

  3. Replace <CLIENT SECRET> with the the WorkflowGen registered application's generated secret on Azure.

  4. Replace <METADATA URL> with the URL that you built earlier from the Directory ID value of your Azure AD directory.

  5. Replace <CHECK SESSION URL> with the value of the metadata endpoint's check_session_iframe property. There are two ways to do this: Option 1: Use the following format: https://login.microsoftonline.com/<Directory ID>/oauth2/checksession Replace <Directory ID> with your Azure AD Directory ID, which can be found in the Properties section of your Azure AD portal page. Option 2: Request the <METADATA URL> and get the value:

    Linux/macOS request example:

    curl "<METADATA URL>" | python -m json.tool

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

    Windows PowerShell request example:

    Invoke-RestMethod -Uri "<METADATA URL>" -Method GET | ConvertTo-JSON For more information about this property, see the table below.

Note: If your server blocks browsers from embedding web content in iframes (e.g. by returning the header X-Frame-Options: DENY), it is strongly recommended that you set the value of ApplicationSecurityAuthSessionRefreshEnableIFrame.

Table of web.config options

Option

Description

ApplicationSecurityAuthProvider

The name of the identity provider supported by WorkflowGen. At this time, there is support only for Azure Active Directory, Auth0, AD FS, and Okta. Value: azure-v1, auth0, adfs, or okta

ApplicationSecurityAuthClientId

Each identity provider generates a code that uniquely identifies your application. In this case, this is the code that uniquely identifies the WorkflowGen web application.

ApplicationSecurityAuthClientSecret

Like the client ID, this is also generated by the identity provider, but it is more like what a password is for a user. It's important to keep this secret because malicious software that has access to this can act on the behalf of the application. This value must be explicitly generated in Azure Active Directory.

ApplicationSecurityAuthMetadataUrl

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 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 Azure Active Directory 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 Azure AD and back. The last thing left to do is configure a few more options in order to finish the internal wiring of WorkflowGen so that it can delegate its authentication.

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 Node.js authentication 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. If you have developed custom web forms with their own \bin folders, you have to copy the following .NET assemblies and dependency libraries from \wfgen\bin to each custom web form's \bin folder (\wfgen\wfapps\webforms\<custom webform>\bin):

    • Advantys.My.dll

    • Advantys.Security.dll

    • Newtonsoft.Json.dll

    • jose-jwt.dll

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