Zoomed Image
USA
800 691 9120
UK
01225 704844

Azure User Groups

xAssets Configuration Guide
Single Sign On

Azure User Groups

By default, when a new user logs in via SSO for the first time, xAssets assigns them to the USERS user group. From version 7.3.43 onward, you can configure xAssets to assign new SSO users to a specific user group based on their Azure AD group membership. This page explains how to set up this mapping.

Prerequisites

  • Azure AD SSO enabled and working (see SSO with Azure)
  • xAssets user groups created that match (by description) the Azure AD groups you want to map
  • Configuration-level access to xAssets

How Group Mapping Works

When the group mapping feature is enabled, the login flow adds an extra step:

  1. The user authenticates with Azure AD
  2. xAssets queries Azure AD to ask which groups the user belongs to
  3. If one of the user's Azure AD groups matches the description (not the UserGroupCode) of an xAssets user group, the user is placed in that group
  4. If two or more Azure AD groups match xAssets user groups, the one that is alphabetically first is used
  5. If no Azure AD groups match, the user is placed in the default USERS group

Important: The match is between the Azure AD group name and the xAssets user group description (the UserGroupDesc field), not the user group code. The match must be exact -- including case and spacing.

Enabling Group Mapping

  1. Navigate to Admin > Settings
  2. Create or edit the SpecialOption called AuthenticationOptions
  3. Set its value to:
usergroup=1

This enables dynamic group mapping based on Azure AD group membership.

Alternative: Hard-Coding a User Group

To assign all new SSO users to a specific user group regardless of their Azure AD group membership, set the value to the name of the target user group:

usergroup=Accounts Users

All new SSO users will be placed in the "Accounts Users" group.

Disabling Group Mapping

To revert to the default behaviour where all new SSO users are placed in the USERS group:

  • Delete the AuthenticationOptions SpecialOption, or
  • Set its value to 0 or leave it blank

Troubleshooting

If users are unexpectedly placed in the USERS group when group mapping is enabled, the most common cause is that there is no exact match between an Azure AD group name and an xAssets user group description. Check:

  1. The exact spelling, case, and spacing of the Azure AD group name
  2. The exact spelling, case, and spacing of the xAssets user group description (not the code)
  3. That the user is actually a member of the expected Azure AD group

Tip: To verify the Azure AD group names, use the Azure Portal to list the user's group memberships, then compare those names character-by-character against the xAssets user group descriptions.