# Microsoft Entra ID Authentication {% hint style="warning" %} Azure Active Directory (Azure AD) has been renamed to **Microsoft Entra ID** (**ME-ID**). While the WorkflowGen documentation has been updated to reflect this name change, the WorkflowGen application settings still refer to Azure AD (for example, `Azure AD SCIM v2` directory connector). Likewise, certain ME-ID configuration items in the Azure portal have been renamed and/or moved. The WorkflowGen documentation has been updated accordingly, but still might not be completely accurate in this regard. See the [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/) documentation for more information. {% endhint %} ## Overview This section provides instructions on how to configure WorkflowGen delegated authentication with Microsoft Entra ID (ME-ID) authentication via the **Microsoft Identity Platform v2.0** or **API endpoint v1** providers, and will show you how to set up a working WorkflowGen instance that uses ME-ID to authenticate your users. {% hint style="info" %} In the instructions, substitute `` with the domain and path to your WorkflowGen instance; for example, `localhost/wfgen` or `www.mycompany.com/wfgen`. {% endhint %} ## Prerequisites * Make sure to have a licensed copy of WorkflowGen installed and running on an IIS web server in **HTTPS** secure connection mode. * You must be a **WorkflowGen Administrator**. * Make sure to have **ME-ID Administrator access** to be able to configure ME-ID. * Make sure to have provisioned an existing ME-ID user that you can authenticate with WorkflowGen and that the user has **WorkflowGen Administrator** permissions. This is important because once you've activated the delegated authentication with ME-ID, you'll still need to be able to manage the WorkflowGen web application. * AES encryption mode and its key are required for the authentication to work. ## Microsoft Entra ID configuration The configuration of ME-ID is done in two parts. 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 in order to be able to register other custom applications to access it. ### Step 1: Create a new application registration for WorkflowGen 1. In the Azure portal, click **App registrations** in the **Azure services** section.
2. Click **New registration**, and fill in the properties form: * **Name:** `WorkflowGen Web app` * **Supported account type:** `Account in this organizational directory only (Default Directory only - Single tenant)` ✏️ **Note:** Depending on the context, you should choose the right option for your use case for the **Supported account type** value. * **Redirect URI:** * **Platform:** `Web` * **Value:** `https:///auth/callback` 📌 **Example:** `https://mycompany.com/wfgen/auth/callback`
3. Click **Register** at the bottom of the page. You should now see the `WorkflowGen Web app` application registration's overview page. ### Step 2: Create a client secret for the application Now, you have to generate a **client secret** to be used by the WorkflowGen OIDC authentication module. 1. Click **Add a certificate or secret**.
2. In the **Client secrets** section, click **New client secret**. * **Description**: `My secret`, or something to know that this is the client secret. * **Expires**: Choose **730 days (24 months)** or your desired expiration period.
3. Click **Add**.
4. The auto-generated client secret is now displayed under the **Value** column. Copy the client secret value and save it somewhere safe, since you won't be able to retrieve it afterwards. {% hint style="warning" %} It's no longer possible to set client secrets to **never** expire. You'll need to manually regenerate a new client secret every two years (if the **24 months** option was selected) before it expires. Then, update the client secret used by WorkflowGen instance in its web configuration file (**`ApplicationSecurityAuthClientSecret`** key). {% endhint %} ### Step 3: Add a redirect URI In order for the communication between the WorkflowGen instance and ME-ID to work, you need to add one more authorized redirect URI to the `WorkflowGen Web app` application registration. 1. Under **Redirect URIs** on the application's overview page, click **Add a Redirect URI**.
2. Enter the following information: * **Redirect URI**: `https:///auth/logout/return` \ 📌 **Example:** `https://mycompany.com/wfgen/auth/logout/return`\ ✏️ **Note:** You should also see `https:///auth/callback` in this list.
3. Click **Save** at the bottom of the section. ### Step 4: Create a new application registration for WorkflowGen GraphQL API {% hint style="info" %} If you don't need WorkflowGen GraphQL API access, you can skip this application registration and configuration in Azure (**steps 4 through 6**). In this case, continue the configuration procedure from [Review the registrations](#review-the-registrations) through [WorkflowGen configuration](#workflowgen-configuration) completely. Finally, follow the configuration in the [Configuring the authentication without the GraphQL API](#configuring-the-authentication-without-the-graphql-api) section. {% endhint %} In order to expose the WorkflowGen GraphQL API, you need to add a new application registration in ME-ID that will represent it. To do this: 1. In the Azure portal, click **App registrations** in the **Azure services** section.
2. Click **New registration**, and fill in the properties form: * **Name:** `WorkflowGen GraphQL API` * **Supported account type:** `Account in this organizational directory only (Default Directory only - Single tenant)` * **Redirect URI**: Leave this blank.
3. Click **Register** at the bottom of the page. You've now successfully registered the `WorkflowGen GraphQL API` application in ME-ID. ### Step 5: Expose the API in the WorkflowGen GraphQL API application registration 1. Click **Expose an API**. 2. To the right of **Application ID URI**, click **Set** and enter the URI `https:///graphql`\ 📌 **Example:** `https://mycompany.com/wfgen/graphql` 3. Click **Save**.
4. Click **Add a scope** and enter the following information: * **Scope name:** `default` * **Who can consent?:** `Admins and users` * **Admin consent display name:** `Default access to the WorkflowGen GraphQL API` * **Admin consent description:** `Allows the application to get access to WorkflowGen GraphQL API.` * **User consent display name:** `Default access to the WorkflowGen GraphQL API` * **User consent description:** `Allows the application to get access to WorkflowGen GraphQL API.` 5. Click **Add scope**. You should now have a new scope defined (e.g. `https:///graphql/default`). {% hint style="warning" %} Since October 2021, the use of a default schema or a verified domain for the AppId URL on a single tenant application (see the Microsoft documentation [here](https://learn.microsoft.com/en-us/azure/active-directory/develop/reference-breaking-changes#appid-uri-in-single-tenant-applications-will-require-use-of-default-scheme-or-verified-domains) for more information) is required.\ \ The Microsoft documentation on how to add and verify a custom domain is available [here](https://learn.microsoft.com/en-us/azure/active-directory/enterprise-users/domains-manage). {% endhint %} ### Step 6: Grant WorkflowGen access to WorkflowGen GraphQL API 1. On the `WorkflowGen Web app` application registration page, click **API permissions**.
2. Click **Add a permission**, then select the tab **My APIs**.
3. Click the `WorkflowGen GraphQL API` application in the list.
4. Click **Delegated permissions** and check `default` under the **Permission** column.
5. Click **Add permissions**.
6. On the **API permissions** page, click **Grant admin consent for \**, then click **Yes**. ### Review the registrations You should now have all of the information you need to configure your WorkflowGen instance to delegate authentication to Microsoft Entra ID Here's a review: * A **client ID**. This is the application (client) ID of the `WorkflowGen Web app` application registration in ME-ID. You can find it on its **Overview** page. * A **client secret**. This is the secret previously generated in **step 2** for the `WorkflowGen Web app`. * An **audience**. This is the `Application ID URI` property (e.g. `https:///graphql`) in the **Expose an API** section of the `WorkflowGen GraphQL API` application registration. * The **metadata endpoint URL**. This URL is bound to your ME-ID directory. To find it: 1. Go to the **Overview** page and opy the `Tenant ID` value. 2. The metadata endpoint URL is built by replacing `` with your **Tenant ID** as follows: \ \ **For Microsoft Identity Platform v2.0 (recommended):** ``` https://login.microsoftonline.com//v2.0/.well-known/openid-configuration ``` \ **For Azure v1:** ``` https://login.microsoftonline.com//.well-known/openid-configuration ``` By now, you should have all the information needed to link your WorkflowGen instance to ME-ID. ## WorkflowGen configuration Now, you have to configure WorkflowGen to delegate its authentication to ME-ID. ### Step 1: Add Microsoft Entra ID values to the WorkflowGen `web.config` 1. Open the WorkflowGen `web.config` file and add and/or update the following properties under ``\ \ **For Microsoft Identity Platform v2.0 (recommended):** ```markup ``` \ **For Azure v1:** ```markup ``` \ ✏️ **Note:** Check session iFrame (e.g. `ApplicationSecurityAuthCheckSessionUrl`) is not supported in **Microsoft Identity Platform v2.0**.
2. Replace `` with the `WorkflowGen Web app` application (client) ID from ME-ID.
3. Replace `` with the `WorkflowGen Web app` application registration's generated secret from ME-ID.
4. Replace `` with the metadata endpoint URL that you built earlier from your ME-ID's `Tenant ID` value.
5. For **Microsoft Identity Platform v2.0**, replace `` with your WorkflowGen URL in the value of the **`ApplicationSecurityAuthAdditionalScopes`** key (e.g. `https://mycompany.com/wfgen/graphql/default`) if you have configured the `WorkflowGen GraphQL API` application registration (**steps 4 through 6**). Otherwise, remove the **`ApplicationSecurityAuthAdditionalScopes`** key completely. 6. For **Azure v1**, replace `` (which is usually `https://login.microsoftonline.com//oauth2/checksession`) with the value of the metadata endpoint's `check_session_iframe` property. To do this, you'll have to make an HTTP GET request to your metadata endpoint URL (e.g. `https://login.microsoftonline.com//.well-known/openid-configuration`), then copy and paste the value. See the examples below on how to request the metadata endpoint.
**Linux/macOS request example:** ``` curl "" | 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 "" -Method GET | ConvertTo-JSON ``` **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 Microsoft Entra ID, Microsoft Identity Platform v2.0, Auth0, AD FS, and Okta. Value: `azure-v1`, `ms-identity-v2`,`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 app` application in ME-ID. | | `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 ME-ID. | | `ApplicationSecurityAuthMetadataUrl` | The endpoint provided by the identity provider that supports the [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) standard. It enables WorkflowGen to get some public information about your ME-ID domain. Without this, you'll have to manually enter much more configuration in the `web.config`. Take note that the metadata endpoint URL is different for **Microsoft Identity Platform v2.0** and **Azure v1**. | | `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.

| | `ApplicationSecurityAuthAccessTokenUsernameClaim` |

This is used 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 \