* Make sure to have Auth0 administrator 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 once you activate the delegation, you'll 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.
* AES encryption mode and its key are required for the authentication to work. {% hint style="info" %} * To test your configuration after you complete 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. `john.doe@example.com`). {% endhint %} ### 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://
5. Scroll down to the **Allowed Logout URLs** section and add `https://
2. Click **Create API**, and fill in the form: * **Name:** `WorkflowGen GraphQL API` * **Identifier:** `https://
 3. Click **Create**. **With multi-audience support:** 1. Go to the Auth0 portal **APIs** section.
2. Click **Create API**, and fill in the form: * **Name:** `My APIs` * **Identifier:** `my-apis` * **Signing algorithm**: `RS256` 3. Click **Create**. 4. Click **Permissions**. 5. In the **Define all the permissions (scopes) that this API uses** section, enter the following information: * **Permission:** `wfgen-graphql-full-access` * **Description:** `Full access to the WorkflowGen GraphQL API` 6. Click **ADD**. 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;
}
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.
3. Replace `
4. Replace `
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: ```markup
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\
* `Advantys.My.dll` * `Advantys.Security.dll` * `Newtonsoft.Json.dll` * `jose-jwt.dll` {% hint style="success" %} 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. {% endhint %} ### Configuring the authentication without the GraphQL API {% hint style="warning" %} This feature is not supported for Auth0. It is necessary to configure the GraphQL API on the provider. {% endhint %} ## Auth0 user provisioning The self-provisioning connector is a directory connector that automatically creates and synchronizes a user based on the user's session token claims that contain claims from the OpenID Connect provider ID token. This feature is only compatible with an OpenID Connect authentication. ### Prerequisites * Make sure to have a working WorkflowGen instance.
* Make sure to know the instance's IP address or its fully qualified name.
* Make sure to know the address of the instance.
* Make sure to have configured Auth0 or one of the other OIDC-compliant authentication methods ([Azure Active Directory](https://docs.advantys.com/workflowgen-for-azure/v/8.0.0/), [AD FS](https://advantys.gitbooks.io/workflowgen-technical-reference-guide/content/adfs-integration.html), [Okta](https://docs.workflowgen.com/tech/8.0/okta-integration), or [Microsoft Identity Platform v2.0](https://docs.advantys.com/workflowgen-for-azure/v/8.0.0/)). ### WorkflowGen configuration This section will guide you through the WorkflowGen configurations necessary to set up the self-provisioning feature with a directory. #### Step 1: Create a self-provisioning directory This directory will contain all of the users that are not provisioned elsewhere. To create a self-provisioning directory, do the following: 1. On the **Directories** page in the WorkflowGen Administration Module, click **New directory**.
2. Fill in the form: * **Name**: `SELF_PROVISIONING`(or something else) * **Description:** A good description of the directory * **Directory connector:** `Self-provisioning`
3. Click **Save**. #### Step 2: Configure the user fields-to-claims mapping Now that you've created a new directory with the self-provisioning connector, you need to define which claims are mapped to which WorkflowGen user field. To do this: 1. On the new directory's page, click **Edit mapping**.
2. To the right of the name of a WorkflowGen user's field, enter the name of the claim in the session token that you want to map.
Here's an example of a session token generated by the auth node application from the Auth0 ID token connected with Google Apps: ``` { "sub": "some.user@advantys.com", "iss": "https://
✏️ **Note:** The **Username** and **Name** fields are required.
3. Click **Save**. {% hint style="success" %} You've now activated the self-provisioning feature, and unknown users can be automatically provisioned and synchronized to WorkflowGen without any external actions required. {% endhint %} ## Auth0 configuration for WorkflowGen Plus v2 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](#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://oidc`.
2. Scroll down further to the **Allowed Logout URLs** section and add the URL `workflowgenplus://oidc`. #### 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: * A client ID, which can be found on the native application page's **Settings** tab.
* An Auth0 domain name, which can be found directly to the left of your profile picture on the top right corner of the page. {% hint style="success" %} 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. {% endhint %} ## 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](#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: * A client ID, which can be found on the registered application's **General** tab.
* A client secret, which can be found on the registered application's **General** tab.
* 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. {% hint style="success" %} 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. {% endhint %} ## 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:
* 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](#auth0-authentication) section. ### Auth0 configuration #### 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. {% hint style="success" %} Your application should now be 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. {% endhint %} ## 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`. {% hint style="info" %} Port `8888` is defined by default; you can change it if it's already in use on your computer. {% endhint %} #### 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. {% hint style="success" %} All of this information must be given to the users who will be using the WorkflowGen CLI. {% endhint %} ### Non-interactive mode The configuration of non-interactive mode is the same as in the [Auth0 configuration for server-side scripts](#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. {% hint style="success" %} You can now use the WorkflowGen CLI in `Client credentials` mode. {% endhint %} ## Generating a universal link for WorkflowGen Plus v2 As of 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`
* **server\_address**: Your WorkflowGen application URL, whose value must be URL encoded (e.g. `https://mycompany.com/wfgen`)
* **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, whose value must be URL encoded (e.g. `https://mycompany.com/wfgen/graphql`) The universal link should follow this format: ``` workflowgenplus://auth.init?provider=auth0&server_address=https%3A%2F%2Fmycompany.com%2Fwfgen&client_id=7gdj4hs92y&domain=mydomain.auth0.com&audience=https%3A%2F%2Fmycompany.com%2Fwfgen%2Fgraphql ``` {% hint style="success" %} 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. {% endhint %} ## 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 `
```markup