# Microsoft Entra ID Configuration for Server-Side Scripts

{% 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

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 of a **server-side script** or **application** (e.g. `background service`, `daemon`, `curl` ,  `Postman`, etc.). For this, OAuth2 provides a type of grant called **Client Credentials** that simply exchanges a **client ID** and **client 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 Microsoft Entra ID (ME-ID) for a **server-side script** or **application** to have access to the WorkflowGen GraphQL API. First, you'll need to register a new web application in ME-ID; then, you'll need to configure a new application in your WorkflowGen web server.

## Prerequisites

* Make sure to have a licensed copy of WorkflowGen installed and running on an IIS web server in **HTTPS** secure connection mode.
* Make sure to have administrative access to WorkflowGen.
* Make sure to have administrative access to ME-ID to be able to configure it properly.
* Make sure to have successfully configured delegated authentication to ME-ID on your WorkflowGen instance following the instructions in the [Microsoft Entra ID Authentication](https://docs.workflowgen.com/azure/7.22/azure-active-directory-authentication) section with the `WorkflowGen GraphQL API` application registered as well.

## Microsoft Entra ID configuration

### Step 1: Register a new web application

1. In the Azure portal, click **App registrations** in the **Azure services** section.<br>
2. Click **New registration**, and fill in the properties:
   * **Name:** `My script, service or application name`
   * **Supported account types:** `Accounts 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:** Leave this blank<br>
3. Click **Register** at the bottom of the page.

You've now successfully registered your application in Microsoft Entra ID.

### Step 2: Grant access to WorkflowGen GraphQL API

1. Click **View API permissions**.<br>
2. In the **Configured permissions** section, click **Add a permission**.<br>
3. Click **My APIs**, then select the `WorkflowGen GraphQL API` application in the list.<br>
4. Click **Delegated permissions** and check `default` in the **Permission** column.<br>
5. Click **Add permissions**.<br>
6. On the **API permissions** page, click **Grant admin consent for \<your tenant name>**, then click **Yes**.

### Step 3: Create a client secret for the application

1. In the application registration's menu, click **Certificates & secrets**.<br>
2. In the **Client secrets** section, click **New client secret**.
   * **Description**: `My secret`, or something that identifies this as the client secret.
   * **Expires**: Select **730 days (24 months),** or your desired expiration period.<br>
3. Click **Add**.<br>
4. The auto-generated client secret is now displayed in 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" %}
Since the latest Azure portal update, 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 **730 days (24 months)** option was chosen) before it expires. Then, update the client secret used by your server-side script or application.
{% endhint %}

### Review the registration

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

* A **client ID**: This is the application (client) ID in the **Overview** section of your application registration.
* A **client secret** : This is the value that you generated in the **Certificates & secrets** section.
* A **tenant ID**: This is the directory (tenant) ID in the **Overview** section of your application registration.
* A **scope**: The `WorkflowGen GraphQL API` application's scope in its **Expose an API** section.

  ✏️ **Note:** You must add a **period** (`.`) before the `default` scope name in the URL when passing the scope as a parameter in the request to retrieve the access token (e.g. `https://<workflowgen url>/graphql/.default`). See the scope parameter in the [cURL example](#retrieve-the-access-token-from-azure-for-your-application).

You've now successfully registered your server-side script or application in Microsoft Entra ID.

## WorkflowGen configuration

As with user provisioning, WorkflowGen needs to know which application is accessing the GraphQL API. Therefore, you have to register the application in WorkflowGen, which consists of your server-side script or application.

### Register a new application

1. On the **Applications** page in the WorkflowGen Administration module, click **New application**.<br>
2. Fill in the form:
   * **Name**: `My Server Application`
   * **Description**: A description that clearly identifies your script, service, or application
   * **Type**: `Non-interactive Client`
   * **Impersonate username**: Any WorkflowGen username that has the required access to the GraphQL API
   * **Client ID**: The `client ID` you retrieved earlier from your application registration in ME-ID
   * **Active**: Check this checkbox<br>
3. Click **Save**.

Your application should now appear in the list of WorkflowGen applications.

{% hint style="success" %}
You should now have the necessary components in place to make GraphQL API requests with your server-side script or application by passing the access token that was previously retrieved from the ME-ID OAuth2 token endpoint using the **Client Credentials** Grant flow.
{% endhint %}

## Access token usage

In order for your server-side script or application to make requests to the WorkflowGen GraphQL API, you must first obtain an access token from your ME-ID OAuth2 token endpoint. The following are examples of how to obtain an access token for your application and how to make a request to the GraphQL API.

### Retrieve the access token from ME-ID for your application

#### cURL request

```bash
curl --location --request POST 'https://login.microsoftonline.com/<Tenant ID>/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<Client ID>' \
--data-urlencode 'client_secret=<Client Secret>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=https://<workflowgen url>/graphql/.default'

```

{% hint style="info" %}
It's suggested to use the OAuth2 v2.0 token endpoint URL (e.g. `https://login.microsoftonline.com/<Tenant ID>/oauth2/v2.0/token`), which works for both the **Microsoft Identity Platform v2.0** and **Azure v1** providers.
{% endhint %}

{% hint style="info" %}
You must also add a period (`.`) before the `default` scope name in the URL when passing the scope as a parameter in the request to retrieve the access token (e.g. `https://mycompany.com/wfgen/graphql/.default`). See the `scope` parameter in the cURL example above.
{% endhint %}

{% hint style="warning" %}
If you've configured the [Calling third-party APIs with the shared access token](https://docs.workflowgen.com/azure/7.22/azure-active-directory-authentication#calling-third-party-apis-with-the-shared-access-token) section, then the `scope` parameter value should be `api://my-apis/.default` instead of `https://<workflowgen url>/graphql/.default`.
{% endhint %}

#### JSON response

```javascript
{
    "token_type": "Bearer",
    "expires_in": 3599,
    "ext_expires_in": 3599,
    "access_token": "<access token>"
}
```

{% hint style="info" %}
To inspect the content of the **access token**, you can copy and paste the `<access token>` string value into the [jwt.io](https://jwt.io) website. The access token is a **JSON Web Token**.

By default, the access token expires in **3599 seconds**, which is about one hour.
{% endhint %}

### Requesting the GraphQL API with the access token

#### cURL request to get the viewer's username from WorkflowGen

```bash
curl --location --request POST 'https://mycompany.com/wfgen/graphql' \
--header 'Authorization: Bearer <access token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'query={
  viewer {
    userName
  }
}'
```

#### GraphQL API JSON response

```javascript
{
    "data": {
        "viewer": {
            "userName": "firstname.lastname@mycompany.com"
        }
    }
}
```

{% hint style="info" %}
For more information about the **OAuth 2.0 Client credentials grant flow** and additional examples, refer to the [Microsoft identity platform and the OAuth 2.0 client credentials flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow) guide.
{% endhint %}