​
Overview

Microsoft Entra is Microsoft’s unified identity and access management solution designed to protect access to applications, resources, and user data across an organization’s environment. It provides a robust identity and access management (IAM) framework, allowing secure access control, role management, and integration of various applications under a single directory. Entra is crucial for managing multi-cloud and hybrid environments securely, enforcing policies, and supporting both on-premises and cloud resources.

​
Prerequisites

  • Application Administrator role
  • Basic understanding of IAM and OIDC concepts

This setup configures Microsoft Entra to manage and secure access for FlowX.AI applications, handling user roles, custom attributes, and application-specific permissions. The setup covers these main components:

​
Flowx-web app registration

The Flowx-web application serves as the main entry point for logging into FloWX Designer or container applications.

​
Appplication registration steps

To register the Flowx-web application, follow these steps:

  1. Navigate to https://portal.azure.com and log in to your EntraID directory, which will host your FlowX.AI application registrations.
  2. Go to Microsoft EntraID > App registrations > New registration

  1. Enter a name for your application, then select Accounts in this organizational directory only (Single tenant) to limit access to your organization’s directory.

  1. Click Register to complete the setup.

You will be redirected to the overview of the newly created app registration.

​
Authentication steps

Follow these steps to configure authentication for the Flowx-web application:

  1. Go to the Authentication tab. Under Platform configurations, add a new platform by selecting Single-page application (SPA). Then, set the Redirect URIs to point to the URIs of your Designer application.

  1. Click Configure to save the platform settings.
  2. Next, click Add URI to include an additional redirect URI, this time pointing to your container application’s URI.

  1. Click Save to confirm the redirect URI changes.
  2. Scroll down to Advanced Settings. Under Mobile and Desktop Applications, toggle Enable the following mobile and desktop flows to Yes.

  1. Click Save again to apply all changes.

​
API permissions

To configure the necessary API permissions, follow these steps:

  1. Navigate the API permissions tab and click Add a permission.

  1. In the permissions menu, select Microsoft Graph and then choose Delegated permissions.

  1. Add the following permissions by selecting each option under OpenId permissions:
  • email
  • offline_access
  • openid
  • profile

  1. After adding these permissions, click Add permissions to confirm.

​
Token configuration

Configure the claims you want to include in the ID token.

  1. Navigate to the Token configuration tab. Click Add optional claim, then select Token type > Access.
  • Choose the following claims to include in the token:
    • email
    • family_name
    • given_name
    • preferred

  1. Click Add to save these optional claims.

  1. Next, add group claims to the token by clicking Add groups claim.
  2. Select All groups and, under each token type, select sAMAccountName (this may differ for your specific organization).

​
Setting token expiration policies

For organizations that require specific control over token lifetimes, Microsoft Entra allows customization of token expiration policies.

  1. Create a Custom Token Lifetime Policy: Define the desired expiration settings for access, ID, and refresh tokens in the policy.
  2. Assign the Policy to a Service Principal: Apply the policy to your Flowx-web or Flowx-API app registrations to enforce token lifetime requirements.

For more details on creating and assigning policies for token expiration, refer to Microsoft’s guide on configuring token lifetimes.

Adjusting token lifetimes can enhance security by reducing the window for unauthorized access.

​
Flowx-API app registration

The Flowx-API application is used to configure the access token necessary for secure communication between the browser and all exposed FlowX APIs.

​
Appplication registration steps

To register the Flowx-API application, follow these steps:

  1. Navigate to https://portal.azure.com and log in to your EntraID directory, which will host your FlowX.AI application registrations.
  2. Go to Microsoft EntraID > App registrations > New registration

  1. Enter a name for your application, then select Accounts in this organizational directory only (Single tenant) to limit access to your organization’s directory.

  1. Click Register to complete the setup.

You will be redirected to the overview page of the newly created app registration.

​
API permissions

To configure the necessary API permissions, follow these steps:

  1. Go to the API permissions tab and click Add a permission.

  1. In the permissions menu, select Microsoft Graph and then choose Delegated permissions.

  1. Add the following permissions by selecting each option under OpenId permissions:
  • email
  • offline_access
  • openid
  • profile

  1. After adding these permissions, click Add permissions to confirm.

​
Token configuration

Configure the claims you want to include in the ID token.

  1. Navigate to the Token configuration tab. Click Add optional claim, then select Token type > Access.
  • Choose the following claims to include in the token:
    • email
    • family_name
    • given_name
    • preferred

  1. Click Add to save these optional claims.
  2. Next, add group claims to the token by clicking Add groups claim.
  3. Select All groups and, under each token type, select sAMAccountName (this may differ for your specific organization).

​
Expose an API

To configure the API exposure and define scopes:

  1. In the Expose an API section, click Add under Application ID URI. It’s recommended to use the application’s name for consistency.

  1. Click Save.
  2. Under Scopes defined by this API, click Add a scope and configure it as follows:
  • Scope name: FlowxAI.ReadWrite.All
  • Who can consent: Admins and users
  • Admin consent display name: Full API Access for FlowX.AI Platform
  • Admin consent description: Grants this application full access to all available APIs, allowing it to read, write, and manage resources across the FlowX.AI platform.
  • User consent display name: Same as admin consent display name
  • User consent description: Same as admin consent description
  • State: Enabled

This scope is not used directly to grant permissions. Instead, it is included in login requests made from a web client. When a client makes a login request with this scope, Entra ID uses it to identify and provide the appropriate access token configured here, ensuring secure access.

  1. Under Authorized client applications, click Add a client application. Add each of the following client applications, selecting the FlowxAI.ReadWrite.All scope:
  • flowx-web
  • flowx-admin
  • flowx-process-engine
  • flowx-integration-designer
  • flowx-task-management-plugin
  • flowx-scheduler-core

Client IDs for these applications can be found on the Overview page of each respective application. If some applications are not created yet, you can return and add them to this section after their creation.

​
Application roles

To configure application roles, follow these steps:

  1. Navigate to App roles and click Create app role.
  2. Select Allowed member types select Both (Users/Groups + Applications).

  1. Complete the role details with the following information:
  • Display name: The name displayed for the role.
  • Value: A unique identifier for the role within applications.
  • Description: A description of the role’s purpose.

App role list should be the same as the Keycloak setup. A list of default roles can be found here.

​
Other applications registration

The following FlowX.AI applications require similar steps for registration:

  • Flowx-Admin
  • Flowx-Process-Engine
  • Flowx-Integration-designer
  • Flowx-Task-Management-Plugin
  • Flowx-Scheduler-Core

​
Flowx-Admin app registration

  1. Create a New Application Registration

    • Go to https://portal.azure.com and log in to your Entra ID directory where you will host FlowX.AI application registrations.

  2. Register the Application

    • Navigate to Microsoft Entra ID > App registrations > New registration.
    • Set the application name and select Accounts in this organizational directory only (Single tenant).
    • Click Register. You will be redirected to the overview page of the newly created app registration.

You will now see the overview for your new app registration.

​
Configure client secrets

  1. Navigate to Certificates & secrets.
  2. Under Client secrets, click New client secret.
  3. Set a description and choose an expiration time for the client secret, then click Add.

Copy the generated client secret value. This will be used to configure SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET.

​
Configure API permissions

  1. Go to the API permissions tab and click Add a permission.
  2. Select Microsoft Graph > Application permissions.
  3. Add the following permissions for flowx-admin:
    • Application.Read.All

If you have admin privileges, you can click Grant admin consent to apply these permissions. If not, contact your tenant administrator to grant consent.

​
Flowx-Process-Engine app registration

Follow the same Application Registration Steps and Configure Client Secrets steps as above.

​
Configure API permissions

  • API Permissions: No additional permissions required.

​
Flowx-Integration-Designer app registration

Follow the same Application Registration Steps and Configure Client Secrets steps as above.

​
Configure API permissions

  • API Permissions: No additional permissions required.

​
Flowx-Task-Management-Plugin app registration

Follow the same Application Registration Steps and Configure Client Secrets steps as above.

​
Configure API permissions

  1. Go to the API permissions tab and click Add a permission.
  2. Select Microsoft Graph > Application permissions.
  3. Add the following permissions for flowx-task-management-plugin:
    • Application.Read.All
    • Group.Read.All
    • User.Read.All

If you have admin privileges, you can click Grant admin consent to apply these permissions. If not, contact your tenant administrator to grant consent.

​
Flowx-Scheduler-Core app registration

Follow the same Application Registration Steps and Configure Client Secrets steps as above.

​
Configure API permissions

  • API Permissions: No additional permissions required.

​
Assigning a role to a user/group

To assign a role to a user or group for your FlowX.AI applications, follow these steps:

  1. Go to https://portal.azure.com and log in to your Entra ID directory that hosts your FlowX.AI application registrations.

  2. Navigate to Microsoft Entra ID > Enterprise applications and search for your flowx-api app registration name.
    (An enterprise application with the same name was automatically created when the app registration was set up.)

  1. Under Users and groups, select Add user/group.

  • Choose the user or group you want to assign.

  • Select the appropriate role from the available options.
  1. Click Assign to complete the role assignment.

It is recommended to provide roles through group membership for easier management and scalability.

​
Adding custom attributes

Using Microsoft Graph CLI, you can add custom attributes such as businessFilter.

For more information about Microsoft Graph CLI, check the following docs:

Get started with Microsoft Graph CLI

​
Prerequisites

​
Create an attribute extension property

Create an Attribute Extension Property on the flowx-api app registration:

  1. Log in to Microsoft Graph CLI with the necessary permissions:
   $ mgc login --scopes Directory.Read.All

You can add additional permissions by repeating the mgc login command with the new permission scopes.

  1. Create the attribute extension property by running the following command. Replace <application_object_id> with the object ID of your flowx-api application:
$ mgc applications extension-properties create --application-id <application_object_id> --body '
{
  "dataType": "String",
  "name": "businessFilter",
  "targetObjects": [
    "User", "Group"
  ]
}'

​
Retrieve the attribute extension name

To confirm the attribute extension name, use the command below. This will output the exact name of the created extension property.

$ mgc applications extension-properties list --application-id <application_object_id> --select name

Example output:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications(\u0027<application_object_id>\u0027)/extensionProperties(name)",
  "value": [
    {
      "name": "extension_ec959542898b42bcb6922e7d3f9df282_businessFilter"
    }
  ]
}

​
Configure token claim

  1. Go to the flowx-api app registration in the Azure portal.
  2. Navigate to Token configuration.
  3. Click Add optional claim.
    • Select Token type as Access.
    • Check the box for extn.businessFilter.
  4. Click Add to save the changes.

​
Assign attribute extension to a user

  1. Log in with the required permissions to modify user attributes:
$ mgc login --scopes User.ReadWrite.All
  1. Assign the businessFilter attribute to a user by running the command below. Replace <user_object_id> with the user’s object ID:
$ mgc users patch --user-id <user_object_id> --body '
{
  "extension_ec959542898b42bcb6922e7d3f9df282_businessFilter": "docs"
}'

​
Assign attribute extension to a group

Follow similar steps to assign the businessFilter attribute to a group. Replace <group_object_id> with the group’s object ID and use the following command:

  1. Log in with the required permissions to modify group attributes:
$ mgc login --scopes User.ReadWrite.All
  1. Assign the custom attribute by the command below, replacing <user_object_id> with the user’s object ID. The businessFilter attribute is set to “docs” in this example.
$ mgc groups patch --group-id <group_object_id> --body '
{
  "extension_ec959542898b42bcb6922e7d3f9df282_businessFilter": "docs"
}'

​
Example JWT token for user

To verify that the custom attributes and roles have been correctly applied, you can inspect a sample JWT token issued to a user. This token will include standard claims along with any custom attributes and roles configured in your Entra ID setup.

​
Steps to retrieve a JWT token

  1. Login to the FlowX.AI Application
    Log in to the FlowX.AI application as the user for whom the JWT token needs to be inspected.

  2. Retrieve the JWT Token
    After logging in, retrieve the JWT token by one of the following methods:

    • Using browser developer tools to inspect network requests (look for requests with an Authorization header).
    • Accessing a token endpoint if available, using a tool like Postman.

  3. Decode the JWT Token
    Use a JWT decoding tool, such as jwt.io, to decode and inspect the token.

​
Sample JWT token structure

Below is an example JWT token structure that includes key claims, custom attributes, and roles:

​
Configure helm charts

This section provides details on configuring Helm charts for FlowX.AI applications, including where to retrieve required values and setting environment variables for different application components.

​
Where to get the values

  • tenant_id: The unique identifier for your Entra ID tenant.

  • client_id: The client ID for the specific FlowX.AI application.

  • client_secret: The client secret generated during app registration (only visible at creation).

​
Helm chart values

These configurations are required for different FlowX.AI application components. Substitute <tenant_id>, <flowx_web_client_id>, and <client_id> with your specific values.

​
Designer

For the Designer component, use the following settings:

SKIP_ISSUER_CHECK: true
STRICT_DISCOVERY_DOCUMENT_VALIDATION: false
KEYCLOAK_ISSUER: https://login.microsoftonline.com/<tenant_id>/v2.0
KEYCLOAK_CLIENT_ID: <flowx_web_client_id>
KEYCLOAK_SCOPES: "openid profile email offline_access api://rd-e-example-flowx-api/FlowxAI.ReadWrite.All"
KEYCLOAK_REDIRECT_URI: https://flowx.example.az1.cloud.flowxai.dev

​
All Java application

SECURITY_TYPE: jwt-public-key
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI: https://sts.windows.net/<tenant_id>/
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI: https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys

​
Java applications with a Service Principal

These settings apply to Java applications that require a service principal, such as Admin, Integration Designer, Process Engine, Scheduler Core, and Task Management Plugin.

SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: <client_id>
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: <client_secret>
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_SCOPE: api://rd-p-example-flowx-api/.default

​
Java applications with access to Microsoft Graph API

The following configuration is required for Java applications that need access to the Microsoft Graph API, such as Admin and Task Management Plugin.

OPENID_PROVIDER: entra
OPENID_ENTRA_TENANT_ID: <tenant_id>
OPENID_ENTRA_PRINCIPAL_ID: <flowx_admin_client_id>