How to Assign Users to Business Units Using Entra ID (formerly Active Directory)

Overview

Business Unit membership in Workpath is managed through SAML attributes sent by your Identity Provider (IdP) during login. This article shows how to configure Microsoft Entra ID to automatically assign users to the correct Business Units when they sign in.

 

Prerequisites:

• Business Units feature must be enabled on your Workpath account
• A working Workpath SAML integration in Entra ID
• Business Units created in Workpath with their External ID field set (see Step 3)

How It Works

Every time a user logs in via SAML, Workpath reads the Business Unit identifiers from the SAML response and synchronizes the user's memberships:

• Users are added to any Business Units whose External ID matches an identifier in the SAML response
• Users are removed from any Business Units whose External ID is no longer present in the SAML response
• Identifiers that don't match any Business Unit in Workpath are silently ignored
   

This means BU membership is fully controlled by your IdP — changes take effect on the user's next login.
 

Choose Your Setup Method

There are two ways to send Business Unit identifiers to Workpath, depending on your Entra ID structure:

Method	When to use	SAML attribute
Group Claim	You have a single Entra ID group per Business Unit	business_units
App Roles	You need to combine multiple Entra groups into one Business Unit, or prefer role-based assignment	Role claim (sent automatically)

 

Method 1: Using Group Claims

Use this method if you have one Entra ID group per Workpath Business Unit.

 

Prerequisite: You have already created a group for the members of this BU in Entra ID. 

 

Step 1: Configure the Group Claim in Entra ID

1. Open Entra ID
2. In the navigation, select Entra ID > Enterprise apps
3. Select your Workpath SAML Integration
4. Add the group under Users and groups so that users are entitled to log in
5. Go to Single Sign-on
6. Click Edit on Attributes & Claims
7. Click Add a Group Claim
8. Select All groups, or filter for the specific groups that represent Business Units
9. Under Advanced options, tick Customize the name of the group claim
10. Set the name to: business_units
11. Click Save

Your Additional Claims section should now include a claim named business_units.

 

Note: If the Edit button is greyed out, you may already have a group claim configured. Check the Additional Claims list for an existing group claim and ensure the relevant Business Unit groups are included.

 

Step 2: Note the Group Object IDs

For each Entra ID group that represents a Business Unit, copy its Object ID (a UUID like a1b2c3d4-e5f6-...). You'll need these in Step 3.

 

Step 3: Set External IDs on Business Units in Workpath

If this is the first Business Unit you're activating, notify your Workpath Client Success Manager to activate the feature.

For each Business Unit in Workpath, set its External ID to the Object ID of the corresponding Entra ID group. This is the identifier Workpath uses to match incoming SAML data to Business Units.

 

Method 2: Using App Roles

Use this method if a single Business Unit maps to multiple Entra ID groups, or if you prefer role-based assignment.

App Roles are sent via the standard Microsoft role claim — no additional attribute configuration is needed in Workpath.

Step 1: Create App Roles in Entra ID

1. Open Entra ID
2. In the navigation, select Entra ID > App registrations
3. Select the app registration associated with your Workpath SAML integration
4. Go to App Roles > Create App Role
5. Set:
   • Display name: A descriptive name (e.g., the Business Unit name)
   • Allowed member types: Users/Groups
   • Value: A unique identifier (this is what Workpath will match against the External ID)
6. Click Apply
7. Repeat for each Business Unit

 

Step 2: Assign Users or Groups to App Roles

1. Go back to Enterprise Applications > your Workpath SAML integration
2. Go to Users and groups > Add user/group
3. Select the users or groups and assign them to the appropriate App Role

 

This allows you to combine multiple Entra groups under a single App Role, which maps to one Business Unit in Workpath.

 

Step 3: Set External IDs on Business Units in Workpath

For each Business Unit in Workpath, set its External ID to the Value of the corresponding App Role from Step 1.

 

FAQs

Q: I've changed the BU membership of a user, but don't see the result in Workpath?

A: Workpath can only synchronize BU membership during a login, due to limitations of the underlying protocol, SAML. Ask the user to log out and back in.

Q: What happens when a user logs in and their groups/roles have changed?

A: Workpath performs a full sync on every login. Users are added to BUs matching the new identifiers and removed from BUs that are no longer present. Changes take effect immediately upon login.

Q: Does this work with IdPs other than Microsoft Entra ID?

A: Yes. Any SAML-compatible IdP can send a `business_units` attribute containing the External IDs. The Entra-specific role claim is additionally supported for Microsoft environments.