How to filter users with Extension Attributes using Microsoft Graph

Extension attributes in Microsoft Entra are a great way to enable additional insights on resources such as users or devices. While there are different types of extensions for resources in Microsoft Entra, this article demonstrates how to configure Directory Extensions, which offer a versatile experience for storing additional data on objects, while other options include:

Extension attributes: For syncing with on-premises.
Schema extensions: For control over extension lifecycles.
Open extensions: To support untyped data flexibly.

Why the need for extension attributes

Extension attributes in Microsoft Entra enable administrators to enrich the data stored for different types of resources in Microsoft Entra. By adding custom extension properties to different resources, you can perform more precise filtering and gain better insights on resources through:

Filtering with Microsoft Graph
Filtering in Log Analytics
Dynamic group memberships (and hence assignment to resources)

You may also require additional data to be kept on resources to support using a lightweight application through identification or other reasons.

Another user case where I directly use extension attributes myself is to support integration with an HR system to sync additional data such as internal team membership or clearance level. A combination of default attributes and customer extension attributes are often used to enrich the administrator’s experience for managing resources in Microsoft Entra.

Different types of extension attributes

Four different types of extension attributes in Microsoft Entra can be utilised on resources, each with different supported capabilities. The table below highlights the supported capabilities for each type of extension attribute.

Is it my recommendation that if you need to extend attributes for user resources in Microsoft Entra, specifically to support filtering with Microsoft Graph or Dynamic Group membership rules, then based on the information in the table below, you should utilise Directory Extensions.

Capability	Extension attributes 1-15	Directory extensions	Schema extensions	Open extensions
Supported resource types	user device	user group administrativeUnit application device organization	user group administrativeUnit contact device event (both user and group calendars) message organization post	user group contact device event¹ (both user and group calendars) message organization post todoTask todoTaskList
Strongly typed	No	Yes	Yes	No
Filterable	Yes	Yes	Yes	No
Can store a collection	No	Yes	No	No
Tied to an "owner" application	No	Yes	Yes	No
Managed via	Microsoft Graph Exchange admin center	Microsoft Graph	Microsoft Graph	Microsoft Graph
Sync data from on-premises to extensions using AD connect	Yes, for users	YesADConnect-YES	No	No
Create dynamic membership rules using custom extension properties and data	YesDynamicMembership-YES	YesDynamicMembership-YES	No	No
Usable for customizing token claims	Yes	Yes (1DirectoryExt-CustomClaims-Concept, 2DirectoryExt-CustomClaims-HowTo)	No	No
Available in Azure AD B2C	Yes	YesB2CDirectoryExt	Yes	Yes
Available in Microsoft Entra External ID	Yes	YesB2CDirectoryExt	Yes	Yes
Limits	15 predefined attributes per user or device resource instance	100 extension values per resource instance	Maximum of five definitions per owner app 100 extension values per resource instance (directory objects only)	Two open extensions per creator app per resource instance² Max. of 2 Kb per open extension² For Outlook resources, each open extension is stored in a MAPI named propertyMAPI-named-property³

Create a new directory extension

Directory extensions in Microsoft Entra ID must first be registered on an application in Microsoft Entra. Once this is done, the extension attribute becomes available in the tenant and can be added to a user object. The first step is to register a new application, use the following example to register a new application in Microsoft Entra. The application must never be deleted while the attributes are in use, so I have made that clear in the application’s name.

Connect-MgGraph -scope Application.ReadWrite.All

$app = New-MgApplication -DisplayName "DirectoryExtension | Do Not Delete"

Once the above command is run, information on the newly created app is stored in the $app variable, which will be used in the next command.

The next step is to register a service principal from the app registration. This will make the application (and hence extension attributes) available to all users in your tenant.

New-MgServicePrincipal -AppId $App.AppId

NOTE

If you do not register the service principal, you will get the following error when trying to update your user accounts: Update-MgUser : The following extension properties are not available:

Now you must create the directory extension by running a Create extensionProperty operation on the newly registered application. The example below creates a new extension property that can be configured on user objects with the name “TrainingStatus” and a String data type.

Use the following formats when defining a new directory extension:

Name: String
dataType: Binary, Boolean, DateTime, Integer, LargeInteger, String
inMultiValued: Boolean
TargetObjects: User, Group, AdministrativeUnit, Application, Device, Organization

$params = @{
	name = "TrainingStatus"
	dataType = "String"
	targetObjects = @(
	"User"
    )
}

$Property = New-MgApplicationExtensionProperty -ApplicationId $app.Id -BodyParameter $params

Importantly, the name of the extension attribute is saved in the $Property variable and will be used to configure the attribute on a user object in your directory. To view the name of the newly created property, type the following code into your PowerShell session.

$Property.Name

The name of my property is extension_fe56defd3f8d4d10a6667e959fc61988_AreaCode. The name is a combination of ‘extension’ + the Application (Client Id) + The name of the attribute you defined.

Add a directory extension to a user

To add your custom directory extension to a user in your directory, use the Update-MgUser cmdlet and include the extension attribute in the body of the request. Modify the below example to include your extension attribute and the user you wish to update.

Connect-MgGraph -Scopes User.ReadWrite.All

$params = @{
    extension_fe56defd3f8d4d10a6667e959fc61988_TrainingStatus = "Complete"
}

Update-MgUser -UserId [email protected] -BodyParameter $params

To view the value of a custom extension using the Get-MgUser cmdlet, you must specify the extension in the name of the request, like so

$attribute = "extension_fe56defd3f8d4d10a6667e959fc61988_TrainingStatus"
$user = Get-MgUser -UserId [email protected] -Property $attribute
$user.AdditionalProperties

Alternatively, extension attributes can be accessed directly when using the Invoke-MgGraphRequest cmdlet, like so:

$user = Invoke-MgGraphRequest -Uri "beta/users/[email protected]"
$user.extension_fe56defd3f8d4d10a6667e959fc61988_TrainingStatus

Filter by directory extension in Microsoft Graph

One of my favourite features of using directory extensions in Microsoft Entra is the ability to filter users by the extension property using Microsoft Graph. This is helpful in scenarios where you want to provide specific application-based access or even when generating custom reporting.

Directory extensions support the following filter types:

eq
startsWith
eq null

For more detailed examples of filtering, see the article How to Use -Filter with Microsoft Graph PowerShell.

Based on the examples above, the following filter example will return all users where the extension_fe56defd3f8d4d10a6667e959fc61988_TrainingStatus is equal to Complete.

Get-MgUser -Filter "extension_fe56defd3f8d4d10a6667e959fc61988_TrainingStatus eq 'Complete'"