Configure Microsoft Entra ID / Azure Active Directory

This page describes how to connect fulfillmenttools with Microsoft Entra ID. Log in to the Microsoft Entra admin center with a user who has at least the Cloud Application Administrator Role.

Create app registration

Select the tenant that contains the Microsoft Entra ID instance, which should be used as an external IDP for fulfillmenttools (settings icon, upper right corner). A separate app registration must be created for each fulfillmenttools environment (typically a test and a production environment).

Browse to App registrations (on the left navigation pane) and select New registration to open the app configuration wizard.

In the app registration wizard, select an arbitrary name (e.g., fulfillmenttools production environment). Furthermore, supply a Redirect URI, which is defined by fulfillmenttools. It has the following pattern: https://ocff-<tenantName>-<pre|prd>.firebaseapp.com/__/auth/handler. Press the Register button to create the application.

Add a second Redirect URI of the pattern https://ocff-<tenantName>-<pre|prd>.web.app/__/auth/handlerto the app registration. Afterwards, two redirect URIs are configured.

Lastly add a third Redirect URI of the pattern https://pick-<tenantName>-<pre|prd>.web.app/__/auth/handlerto the app registration. Afterwards, three redirect URIs are configured.

The OAuth application was successfully created. The landing page shows general Information about the app. The Directory (tenant) ID needs to be supplied to fulfillmenttools via API.

Activate ID- and access tokens for the application

On the left, select Authentication, scroll down, and add activate Access tokens and ID tokens. Afterward, press Save on the bottom.

Create app roles

Now, create the app roles that correspond to the fulfillmenttools roles. Navigate to App Roles and press Create app role.

Create a total of 3 roles: ADMINISTRATOR, SUPERVISOR and FULFILLER. The Display name can be chosen arbitrarily. Allowed member types need to be Users/Groups. The Value must be one of the above mentioned roles ADMINISTRATOR, SUPERVISOR or FULFILLER.

Then the app roles should look similar to this:

Linking app roles to users/groups

Next, link Microsoft Entra ID users/groups to these roles. The official documentation can be found here: Assign users and groups to roles. There are two options, either add individual users to roles or assign groups to roles.

From the landing page of the application, go to the Enterprise application.

Select the application created above

Then select 1. Assign users and groups to add the mapping from Microsoft Entra ID groups/users

Create three Entra ID groups, one for each role. Therefore, this mapping needs to be adapted for each role/group. Select Add user/group.

The following screen allows to assign users or groups. For a production setup, assign one groups for each role (total three). Then, every member of the role is assigned the corresponding fulfillmenttools role.

In the following screenshot, one user is assigned to the ADMINISTRATOR role. Nevertheless, this works the same with groups. In a production setup, the roles should always be assigned using roles.

Adding (facility) groups to the token

Model the assigned facilities to a user using Entra ID groups. In the application registry select the Token configuration from the left navigation panel and select Add groups claim.

In the following wizard select the last option.

Alternatively, select Security groups, and then all the user's assigned groups are put into the token. However, this is not recommended since the token can get too big and the token size limit is hit.

To change the groups assigned to the application, select the application from the Enterprise applications list. Select Users and Groups and then Add user/group. Select the group(s) which should be added to the application from Users and Groups.

Adding optional claims to the token

Use optional claims to add user information like firstname and lastname into the token. In the application registry select the Token configuration from the left navigation panel and select Add optional claim

Next select family_name, given_name and preferred_username from the wizzard. Then press Add.

Create Secret

Finally, create a secret which needs to be transferred to fulfillmenttools. Select Certificates & secrets on the left navigation pane. Then, on the Client secrets tab, select New client secret.

Select a name and an applicable expiry time and click Add.

Now copy the Secret ID and the secret (Value) and send them to fulfillmenttools.

In summary following information is needed:

• CLIENT_ID

  • This is the Application (client) ID of the Enterprise application in Entra

• CLIENT_SECRET

  • This is the value of the secret created in the last step

• IDP_GROUP_ID

  • id of the Entra group that should have access to one or more facilities

• FACILITY_ID_1, FACILITY_ID_1

  • id of the facilities in fulfillmenttools that this group should have access to

• TENANT_ID

  • This is the Directory (tenant) ID of the Enterprise application in Entra

Custom Parameters for Microsoft Entra ID / Azure Active Directory

When using Microsoft Entra ID / Azure Active Directory IdP add the following custom parameter to make sure that only users of the specific Microsoft Entra ID tenant can log in:

{
    ...
    "customParameters": [
        {
            "key": "tenant-name",
            "value": "azure-tenant-id"
        }
    ]
}

To register the OIDC provider to the fulfillmenttools platform, the following call needs to be utilized:

POST https://tenant-name.api.fulfillmenttools.com/api/configurations/oidcproviders

{
    "name": "MS Entra",
    "status": "ACTIVE",
    "clientId": "{CLIENT_ID}",
    "clientSecret": "{CLIENT_SECRET}",
    "issuer": "https://sts.windows.net/{TENANT_ID}",
    "customParameters": [
       {
          "key": "tenant-name",
          "value": "azure-tenant-id"
       }
    ],
    "assignedGroups": [
        {
            "group": "{IDP_GROUP_ID}",
            "facilityRefs": [
                "{FACILITY_ID_1}",
                "{FACILITY_ID_2}"
            ]
        }
    ]
}