Microsoft Entra ID / Azure Active Directory (AD)

Step-By-Step Guide to Configure Microsoft Entra ID OAuth App for the fulfillmentools platform.

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

Sign in into the Microsoft Entra admin center with an user which 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 need to select a arbitrary name (e.g. fulfillmenttools production environment). Furthermore, you need to supply a Redirect URI which is supplied by fulfillmenttools to you. 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 Accesstokens for the Application

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

Create App Roles

Now we create the app roles which 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, 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. Select Add user/group

In the following screen you can 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.

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

Note: Alternatively you can select Security groups, then all assigned groups of the user are put into the token. 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.

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

In summary you need to gather the following information:

• ClientId

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

• ClientSecret

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

• group ids

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

• facilityRefs:

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

• TenantId

  • 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:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/configurations/oidcproviders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "name": "MS Entra",
    "status": "ACTIVE",
    "clientId": "<ClientId>",
    "clientSecret": "<ClientSecret>",
    "issuer": "https://sts.windows.net/<TenantId>",
    "customParameters": [
      "key": "tenant",
      "value": "<TenantId>"
    ],
    "assignedGroups": [
        {
            "group": "<idp-group-id>",
            "facilityRefs": [
                "<facility-id-1>",
                "<facility-id-2>"
            ]
        }
    ]
}'