Configure Microsoft Entra ID/Azure Active Directory
In this article, we'll take you through how to connect fulfillmenttools with Microsoft Entra ID.
Prerequisites
Adminstrator role in Microsoft Entra
Logged into the Microsoft Entra admin center
Administrator role in a fulfillmenttools tenant
Create app registration
Start the app registration
In the left-hand navigation, select App registrations, then click New registration. This will open app configuration wizard.
Input the details for the app
Input a name (for example, fulfillmenttools production environment), leave the supported account types as is, then input a Redirect URI. This has to follow the pattern: https://ocff-<tenantName>-<pre|prd>.firebaseapp.com/__/auth/handler. For example, https://ocff-myproject-prd.firebaseapp.com/__/auth/handler. Then click the Register button.
A separate app registration must be created for each fulfillmenttools environment (for example, one for pre-production and one for production).
Add two more redirect URIs
Select Authentication in the left-hand navigation, then select Add URI, and input a second URI. This has to follow the pattern: https://ocff-<tenantName>-<pre|prd>.web.app/__/auth/handler. For example, https://ocff-myproject-prd.web.app/__/auth/handler.
Select Add URI again, and input a third URI. This has to follow the pattern: https://pick-<tenantName>-<pre|prd>.web.app/__/auth/handler. For example, https://pick-myproject-prd.web.app/__/auth/handler.
Then, click Save.
Copy the Directory and Application IDs
The OAuth application was successfully created. You'll be shown a landing page with the general information about the set up. You need to copy the Directory (tenant) ID and the Application (client) ID. These needs to be supplied to fulfillmenttools via API (we'll go through this in a later step).
Activate the ID and access tokens
Select Authentication in the left-hand navigation, scroll down the page, and check the check boxes for Access tokens and ID tokens. Then, click Save.
Now we have everything set up for the main connection, we can create the app roles.
Create app roles
We need to create app roles that correspond to the fulfillmenttools roles. To do this, follow the steps below.
Start the creation process
In the left-hand navigation, select App roles. Then, click the Create app role button.
Create the default fulfillmenttools roles
Input the Display name of ADMINISTRATOR, select Users/Groups as the Allowed member types, input a Value of ADMINISTRATOR, input a Description of Administrator role for fulfillmenttools, check the Do you want to enable this app role? check box, then click Save.
Repeat this for SUPERVISOR and FULFILLER.
Afterward, the app roles should look similar to this:
If you're using custom roles, you'll also need to create these.
Now we've created the roles, we can assign users or groups to the roles.
Linking app roles to users/groups
The official documentation can be found in the Assign users and groups to roles article.
There are two options to assign roles, either add individual users to roles or assign groups to roles.
Navigate to Enterprise applications
From the landing page of the application, select Enterprise applications from the left-hand navigation.
Select the app created earlier
From the application list, click on the appplication you created at the beginning of this article.
Select Assign users
In the Getting started section, select 1. Assign users and groups.
Add users or groups
Click the Add user/group button, then select a user, and assign a role to that user. You can also do this for user groups.
In a production environment, always add users, and don't assign groups.
You can change a users role at any time.
Once a user's role has been changed, this won't take effect within fulfillmenttools clients until the user has logged out and logged in again.
Adding (facility) groups to the token
You can create an Entra ID group to align to a facility group. Model the assigned facilities to a user using Entra ID groups.
Create a token configuration
From the App registrations screen, select Token configuration from the left-hand navigation and then click the Add groups claim button.
Add groups claim
Click the check box next to Groups assigned to the application, then click the Add button.
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
You can also add optional claims to add user information like first name and last name into the token.
Create a token configuration
From the App registrations screen, select Token configuration from the left-hand navigation and then click the Add optional claim button.
Select the relevant entities
Using the checkboxes, check which entities you want to use, we suggest family_name, given_name, and preferred_username, then click the Add button.
Create secret
Finally, you need to create a secret which needs to be transferred to fulfillmenttools.
Add a secret
In the left-hand navigation, select Certificates & secrets, select the Client secrets tab, and then click the New client secret button.
Add a description
Input a name as the Description, select an expiry time, and then click Add.
Copy the secret values
Copy the Value and the Secret ID and send them to fulfillmenttools.
In summary following information is needed:
CLIENT_IDThis is the
Application (client) IDof the Enterprise application in Entra (from step 4 in Create app registration)
CLIENT_SECRETThis is the value of the secret created in the last step (from step 3 in Create secret)
IDP_GROUP_IDID of the Entra group that should have access to one or more facilities (if you're using facily groups)
FACILITY_ID_1,FACILITY_ID_2ID of the facilities in fulfillmenttools that this group should have access to
TENANT_IDThis is the
Directory (tenant) IDof the Enterprise application in Entra (from step 4 in Create app registration)
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:
To register the OIDC provider to the fulfillmenttools platform, the following call needs to be utilized:
Last updated