Microsoft Entra ID Configuration for Server-Side Scripts

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 documentation for more information.

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

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

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.

2. In the Configured permissions section, click Add a permission.

3. Click My APIs, then select the WorkflowGen GraphQL API application in the list.

4. Click Delegated permissions and check default in the Permission column.

5. Click Add permissions.

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.

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.

3. Click Add.

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.

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.

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.

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.

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

3. Click Save.

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

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.

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

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'

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.

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.

If you've configured the 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.

JSON response

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

To inspect the content of the access token, you can copy and paste the <access token> string value into the 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.

Requesting the GraphQL API with the access token

cURL request to get the viewer's username from WorkflowGen

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

{
    "data": {
        "viewer": {
            "userName": "[e-mail]"
        }
    }
}

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 guide.