Microsoft Entra Connect Sync: Directory extensions

You can use directory extensions to extend the schema in Microsoft Entra ID with your own attributes from on-premises Active Directory. This feature enables you to build LOB apps by consuming attributes that you continue to manage on-premises. These attributes can be consumed through extensions. You can see the available attributes by using Microsoft Graph Explorer. You can also use this feature to create dynamic membership groups in Microsoft Entra ID.

At present, no Microsoft 365 workload consumes these attributes.

Important

If you have exported a configuration that contains a custom rule used to synchronize directory extension attributes and you attempt to import this rule in to a new or existing installation of Microsoft Entra Connect, the rule will be created during import, but the directory extension attributes will not be mapped. You will need to re-select the directory extension attributes and re-associate them with the rule or recreate the rule entirely to fix this.

Customize which attributes to synchronize with Microsoft Entra ID

You configure which additional attributes you want to synchronize in the custom settings path in the installation wizard.

Note

Manually editing or cloning the sync rules for Directory Extensions can cause synchronization issues. It is not supported to manage Directory Extensions outside of this wizard page.

The installation shows the following attributes, which are valid candidates:

• User and Group object types
• Single-valued attributes: String, Boolean, Integer, Binary
• Multi-valued attributes: String, Binary

Note

Not all features in Microsoft Entra ID support multi valued extension attributes. Please refer to the documentation of the feature in which you plan to use these attributes to confirm they are supported.

The list of attributes is read from the schema cache that's created during installation of Microsoft Entra Connect. If you have extended the Active Directory schema with additional attributes, you must refresh the schema before these new attributes are visible.

An object in Microsoft Entra ID can have up to 100 attributes for directory extensions. The maximum length is 250 characters. If an attribute value is longer, the sync engine truncates it.

Note

It is not supported to sync constructed attributes, such as msDS-UserPasswordExpiryTimeComputed. If you upgrade from an old version of Microsoft Entra Connect you may still see these attributes show up in the installation wizard, you should not enable them though. Their value will not sync to Microsoft Entra ID if you do. You can read more about constructed attributes in this article. You should also not attempt to sync Non-replicated attributes, such as badPwdCount, Last-Logon, and Last-Logoff, as their values will not be synced to Microsoft Entra ID.

Configuration changes in Microsoft Entra ID made by the wizard

During installation of Microsoft Entra Connect, an application is registered where these attributes are available. You can see this application in the Microsoft Entra admin center. Its name is always Tenant Schema Extension App.

Note

The Tenant Schema Extension App is a system-only application that can't be deleted and attribute extension definitions can't be removed.

Make sure you select All applications to see this app.

The attributes are prefixed with extension _{ApplicationId}_. ApplicationId has the same value for all attributes in your Microsoft Entra tenant. You will need this value for all other scenarios in this topic.

Viewing attributes using the Microsoft Graph API

These attributes are now available through the Microsoft Graph API, by using Microsoft Graph Explorer.

Note

In the Microsoft Graph API, you need to ask for the attributes to be returned. Explicitly select the attributes like this: https://graph.microsoft.com/beta/users/abbie.spencer@fabrikamonline.com?$select=extension_9d98ed114c4840d298fad781915f27e4_employeeID,extension_9d98ed114c4840d298fad781915f27e4_division.

For more information, see Microsoft Graph: Use query parameters.

Note

It is not supported to sync attribute values from Microsoft Entra Connect to extension attributes that are not created by Microsoft Entra Connect. Doing so may produce performance issues and unexpected results. Only extension attributes that are created as shown in the above are supported for synchronization.

Use the attributes in dynamic membership groups

One of the more useful scenarios is to use these attributes in dynamic security or Microsoft 365 groups.

1. Create a new group in Microsoft Entra ID. Give it a good name and make sure the Membership type is Dynamic User.

   

2. Select to Add dynamic query. If you look at the properties, then you will not see these extended attributes. You need to add them first. Click Get custom extension properties, enter the Application ID, and click Refresh properties.

   

3. Open the property drop-down and note that the attributes you added are now visible.

   

   Complete the expression to suit your requirements. In our example, the rule is set to (user.extension_9d98ed114c4840d298fad781915f27e4_division -eq "Sales and marketing").

4. After the group has been created, give Microsoft Entra some time to populate the members and then review the members.

   

Next steps

Learn more about the Microsoft Entra Connect Sync configuration.

Learn more about Integrating your on-premises identities with Microsoft Entra ID.