Configure Microsoft Entra ID / Azure Active Directory

This page describes what you have to configure in the Microsoft Entra admin center. Log in with a user who has at least the Cloud Application Administrator Role.

Create app registration

If you have access to multiple tenants use the settings icon (upper right corner) to select the tenant which contains the Microsoft Entra ID instance you want to use as external IDP for fulfillmenttools. For each fulfillmenttools environment you use (typically a test and a production environment) you need to create a separate app registration.

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

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

Now we need to add a second Redirect URI of the pattern https://ocff-<tenantName>-<pre|prd>.web.app/__/auth/handlerto the app registration. Afterwards, you have two redirect URIs configured.

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

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, we create the app roles that correspond to the fulfillmenttools roles. Navigate to App Roles and press Create app role.

You have to add a total of 3 roles: ADMINISTRATOR, SUPERVISOR and FULFILLER. You can choose an arbitrary Display name. Allowed member types need to be Users/Groups. The Value must be one of the above mentioned roles ADMINISTRATOR, SUPERVISOR or FULFILLER.

After you created the 3 roles, your app roles should look similar to this:

Linking app roles to users/groups

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

From the landing page of the application we just created, go to the Enterprise application.

Select the application we created above

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

Typically you have 3 Entra ID groups for each role. Therefore, you need to do this mapping for each role/group you want to assign and select Add user/group.

The following screen allows you to assign users or groups. For a production setup, you typically assign 3 groups for each role. Then, every member of the role is assigned the corresponding fulfillmenttools role.

In the following screenshot, we assign one user 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

We 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, you can select Security groups, and then all the user's assigned groups are put into the token. However, you can easily hit the token size limit, so this is not recommended for production scenarios.

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) you want to add to the application from Users and Groups.

Adding optional claims to the token

We 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, we need to 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 you need to gather the following information:

• CLIENT_ID

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

• CLIENT_SECRET

  • This is the value of the secret you 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 your Enterprise application in Entra

To register the OIDC provider to the fulfillmenttools platform you need to execute the following call:

POST https://your.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",
      "value": "{TENANT_ID}"
    ],
    "assignedGroups": [
        {
            "group": "{IDP_GROUP_ID}",
            "facilityRefs": [
                "{FACILITY_ID_1}",
                "{FACILITY_ID_2}"
            ]
        }
    ]
}