Zoomed Image
USA
800 691 9120
UK
01225 704844

Entra Auto-Permissions

xAssets Configuration Guide
Single Sign-On

Entra Auto-Permissions

This page describes how to configure xAssets to automatically assign user permissions based on Microsoft Entra ID (formerly Azure AD) group membership. When a new user logs in via SSO for the first time, xAssets can read their Entra group list and assign them to the appropriate xAssets user group automatically, eliminating the need for manual user setup.

Note: This feature builds on the Azure User Groups capability introduced in version 7.3.43. This page covers the expanded auto-permissions behaviour, including automatic profile assignment and Custodian record creation.

Prerequisites

  • Microsoft Entra ID SSO enabled and working (see SSO with Azure)
  • The Azure AD application registration must include the GroupMember.Read.All permission (or equivalent) so xAssets can query the user's group memberships
  • xAssets user groups must be created with descriptions that match the Entra group names exactly
  • Configuration-level access to xAssets

How Auto-Permissions Work

When a user authenticates via Entra SSO for the first time, the following sequence occurs:

  1. The user authenticates with Microsoft Entra ID.
  2. xAssets queries Entra to retrieve the user's group membership list.
  3. xAssets compares each Entra group name against the descriptions of xAssets user groups.
  4. If a match is found, the user is automatically placed in that xAssets user group.
  5. If multiple matches are found, the alphabetically first match is used.
  6. If no match is found, the user is placed in the default USERS group.
  7. A Custodian record is created for the user if one does not exist, using information from the Entra profile (name, email address).
  8. The user's start profile is set according to the matched user group's default profile.

Important: The match is based on exact text comparison between the Entra group name and the xAssets user group description (the UserGroupDesc field, not the UserGroupCode). Case and spacing must match exactly.

Enabling Auto-Permissions

Step 1: Configure the AuthenticationOptions Setting

  1. Navigate to Admin > Settings.
  2. Create or edit the SpecialOption called AuthenticationOptions.
  3. Set the usergroup parameter to enable group-based mapping:
usergroup=1

This tells xAssets to dynamically assign user groups based on Entra group membership.

Step 2: Ensure User Group Descriptions Match Entra Groups

For each Entra group that should map to an xAssets user group:

  1. Navigate to Admin > User Groups.
  2. Open the target user group.
  3. Set the Description to exactly match the Entra group name.
  4. Save.

For example:

Entra Group Name xAssets User Group Code xAssets User Group Description
IT Asset Managers ITAM IT Asset Managers
Finance Users FINANCE Finance Users
Help Desk Agents HELPDESK Help Desk Agents
Read Only Access READONLY Read Only Access

Step 3: Configure the Azure App Registration

Ensure your Azure app registration has the necessary permissions to read group memberships:

  1. In the Azure Portal, navigate to Azure Active Directory > App registrations.
  2. Select your xAssets application.
  3. Under API permissions, ensure GroupMember.Read.All (or Directory.Read.All) is granted.
  4. If using delegated permissions, ensure admin consent has been granted.

Automatic Custodian Record Creation

When auto-permissions are enabled, xAssets can also create a Custodian record for the new user automatically. The Custodian record is populated with:

Custodian Field Source
Name User's display name from Entra
Email User's email address from Entra
User ID The SSO principal name

This ensures that new SSO users have a linked Custodian record from their first login, enabling them to receive email notifications and be associated with organisational data.

What Happens on Subsequent Logins

Auto-permissions mapping is primarily a first login feature. On subsequent logins:

  • The user's existing xAssets user group is retained.
  • If an administrator manually changes the user's group, the manual change takes precedence.

Assigning All SSO Users to a Fixed Group

If you do not need dynamic group mapping and want all new SSO users placed in the same group regardless of their Entra memberships, set the value to the target group name:

usergroup=Accounts Users

All new SSO users will be assigned to the "Accounts Users" user group.

Disabling Auto-Permissions

To revert to the default behaviour (all new SSO users placed in the USERS group):

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

Troubleshooting

Problem Cause Solution
New SSO user placed in USERS instead of expected group Entra group name does not exactly match any xAssets user group description Compare names character by character -- check case, spacing, and special characters.
Entra groups not being read Azure app registration lacks GroupMember.Read.All permission Add the permission in Azure Portal and grant admin consent.
Wrong group assigned when user belongs to multiple matching groups Alphabetically first match is used Rename groups or consolidate Entra group membership so only one match exists per user.
Custodian record not created Auto-Custodian creation may not be enabled Verify the AuthenticationOptions setting includes the relevant parameters.
User's group not updating after Entra group change Group mapping may only apply on first login Manually update the user's group in xAssets, or delete and recreate the user record.

Tip: Test the mapping with a single test account before rolling out to all users. Create a test user in Entra, add them to one of the mapped groups, and log in to verify they are assigned to the correct xAssets user group.