Auth0 Integration

Overview

This section provides instructions on:

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

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

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

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

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

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

It also provides additional information on SOAP services support and provisioning users and groups.

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.

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

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

Auth0 authentication

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 Auth0 adminstrator access.

• Make sure to have provisioned an existing Auth0 user that you can authenticate with to WorkflowGen and that the user has administrator privileges. This is important because when you'll activate the delegation, you will need to still be able to manage the application. The Auth0 user is in fact a user of an identity provider that's linked to Auth0, such as GitHub or Google. You have to have provisioned at least one user.

Notes

• To test your configuration after the steps below, you can add an Auth0 user in the Users section of the Auth0 portal.

• When importing users into WorkflowGen from the Auth0 database, make sure to set the username as the email (e.g. [e-mail]).

Auth0 configuration

The configuration of Auth0 is done in several 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 regular web application

1. Go to the Auth0 portal Applications section.

2. Click Create Application, and fill in the form:

   • Name: WorkflowGen Web App

   • Type: Regular Web Application

3. Click Create. You should now see the application's Quick Start page:

   
4. On the Settings tab, scroll down to the Allowed Callback URLs section and add https://<workflowgen url>/auth/callback to it.

5. Scroll down to the Allowed Logout URLs section and add https://<workflowgen url>/auth/logout/return to it.

Your WorkflowGen Regular Web App is now configured.

Step 2: Register the GraphQL API

Now, you need to register the WorkflowGen GraphQL API module so that applications external to WorkflowGen can use the API by authentication through Auth0 using the OpenID Connect protocol.

1. Go to the Auth0 portal APIs section.

2. Click Create API, and fill in the form:

   • Name: WorkflowGen GraphQL API

   • Identifier: https://<workflowgen url>/graphql

   • Signing algorithm: RS256

     Your form should look like this:

     
3. Click Create.

The GraphQL API is now registered in Auth0.

Step 3: Add an Auth0 action

In order to get a proper username from the access token when receiving one in the GraphQL API, you need to use a special feature of Auth0 called an action. Actions act as middleware between the linked cloud provider and Auth0 in order to get the correct values when needed.

1. Go to the Auth0 portal and select Actions in the left menu, then select Library in the sub-menu.

2. Click Create Action, then choose the Build from scratch template.

3. Give the action a name (e.g. WorkflowGen (Action)). Trigger should be set to Login / Post Login and Runtime set to Node 18 (Recommended).
4. Replace the code with the following:

   exports.onExecutePostLogin = async (event, api) => {
       const username = event.user.username || event.user.email || event.user.nickname;
              
       api.accessToken.setCustomClaim('https://api.workflowgen.com/username', username);
       api.idToken.setCustomClaim('https://api.workflowgen.com/username', username);
   
       return;
   }

5. Click Deploy.

6. Go to the Auth0 portal and select Actions in the left menu, then select Flows in the sub-menu.

7. On the Flows page, click the Login icon.

8. In the right panel of the graphical view, select the Custom tab, where your custom action should appear.

   

9. Drag and drop your action between the Start and Complete actions.

   

10. Click the Apply button in the top right.

This step will ensure that WorkflowGen and the GraphQL API always get a username through the same claim instead of having to make a lot of conditional statements. However, this doesn't apply to machine-to-machine authentication since there's no human user involved.

If you use a different claim from the Auth0 mapping than the one specified in the function above (e.g. user.username, user.email, user.nickname), just modify this rule or add your own. Make sure to populate https://api.workflowgen.com/username with the value or to configure the ApplicationSecurityAuthUsernameClaim option in your web.config with the correct claim to take. Note that this option is used both in the authentication application and the GraphQL API.

WorkflowGen configuration

Now, you have to configure WorkflowGen to delegate its authentication to Auth0.

Step 1: Add Auth0 values to the WorkflowGen web.config

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

    <!-- Auth0 auth -->
    <add key="ApplicationSecurityAuthProvider" value="auth0"/>
    <add key="ApplicationSecurityAuthClientId" value="<CLIENT ID>" />
    <add key="ApplicationSecurityAuthClientSecret" value="<CLIENT SECRET>" />
    <add key="ApplicationSecurityAuthMetadataUrl" value="<METADATA URL>" />
    <add key="ApplicationSecurityAuthUsernameClaim" value="https://api.workflowgen.com/username" />
    <add key="ApplicationSecurityAuthAppIdClaim" value="azp" />
    <add key="ApplicationSecurityAuthClockTolerance" value="60" />

2. Replace <CLIENT ID> with the client ID of the WorkflowGen Regular Web App in Auth0.

3. Replace <CLIENT SECRET> with the client secret of the WorkflowGen Regular Web App in Auth0.

4. Replace <METADATA URL> with the URL that you built earlier from your domain name in Auth0. The METADATA URL is https://[YOUR_AUTH0_DOMAIN].auth0.com/.well-known/openid-configuration.

Note that the ApplicationSecurityAuthUsernameClaim key is set to the value entered in the rule earlier. Therefore, you can use any value here as long as you also modify the rule.

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 Auth0, Azure Active Directory, and AD FS. Value: auth0, azure-v1, or adfs
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 on Auth0, Azure Active Directory, or AD FS.
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 behalf of the application. This value is auto-generated by Auth0.
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 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 Auth0 configuration for server-side scripts 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 recieving 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.

WorkflowGen is now linked to Auth0 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 properties under <appSettings>:

    <!-- Auth -->
    <add key="ApplicationSecurityAuthLogoutUrl" value="https://<your auth0 domain>.auth0.com/v2/logout"/>
    <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 file 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 Auth0 through the OpenID Connect protocol. Make sure to have provisioned your users to WorkflowGen in order for them to successfully access WorkflowGen.

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 from Auth0. Default: the exp value of the Auth0 ID token
ApplicationSecurityAuthMobileSessionTimeOut	The duration of the session in seconds when requested from mobile devices on the token endpoint. Default: 7200 seconds

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

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.

• Make sure to have the WorkflowGen Plus mobile application installed on a device that you have access to.

• 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 Auth0 on your WorkflowGen instance following the instructions in the Auth0 authentication section.

Auth0 configuration

This configuration is done in several steps. First, you have to register a new native application in Auth0. 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 Auth0 portal, click Create Application in the Applications section.

2. Fill in the form:

   • Name: WorkflowGen Plus

   • Type: Native

3. Click Create at the bottom of the page.

You've now registered a new native application in Auth0.

Step 2: Add callback URLs

1. On the Settings tab, scroll down to the Allowed Callback URLs and add the URL workflowgenplus://auth.authenticate.

2. Scroll down further to the Allowed Logout URLs section and add the URL workflowgenplus://auth.deauthenticate.

Review the registration

You don't need to give the application access to the GraphQL API since all applications (except for machine-to-machine applications) have access to all registered APIs within a domain. Here's a review of the information you need:

1. A client ID, which can be found on the native application page's Settings tab.

2. An Auth0 domain name, which can be found directly to the left of your profile picture on the top right corner of the page.

All of this information must be given to the users who will be using the mobile application; they'll need to copy them directly into the app.

Auth0 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 Auth0 with a server-side script that has access to the GraphQL API. First, you'll need to configure a new web application in the Auth0 portal; then, you'll need to configure a new application in WorkflowGen.

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

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

Auth0 configuration

Step 1: Register a new machine-to-machine application

1. In the Auth0 portal Applications section, click Create Applications.

2. Fill in the form:

   • Name: Your script name

   • Application Type: machine-to-machine

3. Click Create.

You've now successfully registered your script in Auth0.

Step 2: Grant access to the GraphQL API

1. In the Auth0 portal APIs section, click WorkflowGen GraphQL API.

2. On the Machine-to-Machine tab, authorize the application that you just created.

You've now successfully granted the GraphQL API access to your script.

Review the registration

Here's a review of the information you need:

1. A client ID, which can be found on the registered application settings tab.

2. A client secret, which can be found on the registered application settings tab.

3. The WorkflowGen GraphQL API identifier, which can be found on its settings page.

You're now ready to register your script in WorkflowGen.

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 retrieved 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 Auth0 from a Client Credentials Grant flow.

Auth0 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 Auth0 with a single-page application (SPA) so that users can authenticate through it and make requests to the WorkflowGen GraphQL API. This configuration is done in three steps: registering your SPA, granting access to the API, and setting some redirect URLs.

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.

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

Step 1: Register a new web application

1. In the Auth0 portal, click Create Application in the Applications section.

2. Fill in the form:

   • Name: Your SPA name

   • Type: Single Page Web Applications

3. Click Create at the bottom of the page.

You should now be on the registered application page.

Step 2: Add redirect URLs

1. On the Settings tab, scroll down to the Allowed Callback URLs section and add your application's login callback URL (for example, https://localhost/login/callback).

2. If you support logout from Auth0, scroll down to the Allowed Logout URLs section and add your post logout redirect URL (for example, https://localhost/logout/return).

Review the registration

• You need a client ID, which can be found on the application page's Settings tab.

• You need your Auth0 domain name, which can be found next to your Auth0 profile picture in the top right corner of the portal.

Your application should now successfully linked to the Auth0 infrastructure and users can login through it. If you have met the prerequisites, your application will receive an access token that it can send to the WorkflowGen GraphQL API to make authorized requests as a Bearer token via the Authorization header.

Auth0 configuration for the WorkflowGen CLI

Interactive mode

Step 1: Register a new native application

1. In the Auth0 portal Applications section, click Create Application.

2. Fill in the form:

   • Name: WorkflowGen CLI

   • Type: Native

3. Click Create at the bottom of the page.

You've now registered a new native application in Auth0.

Step 2: Add a callback URL

On the Settings tab, scroll down to the Allowed Callback URLs and add the URL http://127.0.0.1:8888/callback.

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

Step 3: Verify the grant types

In Settings > Advanced Settings > Grant Types, make sure that the Implicit, Authorization Code, and Refresh Token checkboxes are checked.

Review the registration

Since all applications in a domain can automatically access each other, your native application inherits access to the GraphQL API. Here's a review of all the information you need:

• A client ID, which can be found on the native application's Settings tab.

• An Auth0 domain name, which can be found on the native application's Settings tab.

All of this information must be given 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 Auth0 configuration for server-side scripts section.

Here's a review of the information you'll need:

• A client ID< which can be found on the registered application's parameters page.

• A client secret, which can be found on the registered application's parameters page.

• The domain, which can be found on the registered application's parameters page.

You can now use the WorkflowGen CLI in Client credentials mode.

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

• client_id: Use the client ID you created earlier in the configuration (e.g. 7gdj4hs92y).

• domain: The Auth0 domain name without URL protocol (e.g mydomain.auth0.com).

• audience: Your WorkflowGen GraphQL API URL (e.g. http://workflow.mycompany.com/wfgen/graphql). Note: The value must be URL encoded.

The universal link should follow this format:

workflowgenplus://auth.init?provider=auth0&client_id=7gdj4hs92y&domain=mydomain.auth0.com&audience=http%3A%2F%2Fworkflow.mycompany.com%2Fwfgen%2Fgraphql

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

Provisioning users and groups

There's no automatic way to provision your users and groups from the identity providers you use behind Auth0 with WorkflowGen. You'll have to synchronize them using one of the supported directory synchronization methods.