Edit

Share via

Cloud sync directory extensions and custom attribute mapping

  • Article

Microsoft Entra ID must contain all the data (attributes) required to create a user profile when provisioning user accounts from Microsoft Entra ID to a line of business (LOB), SaaS app, or on-premises application. 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, provision users from Windows Server Active Directory through Microsoft Entra ID to SaaS apps, and use extension attributes in Microsoft Entra ID and Microsoft Entra ID Governance features such as dynamic membership groups.

For more information on directory extensions, see Using directory extension attributes in claims, Microsoft Entra Connect Sync: directory extensions, and Syncing extension attributes for Microsoft Entra application provisioning.

You can see the available attributes by using Microsoft Graph Explorer.

Note

In order to discover new Active Directory extension attributes, the provisioning agent needs to be restarted. You should restart the agent after the directory extensions have been created. For Microsoft Entra extension attributes, the agent doesn't need to be restarted.

Syncing directory extensions for Microsoft Entra Cloud Sync

You can use directory extensions to extend the synchronization schema directory definition in Microsoft Entra ID with your own attributes.

Important

Directory extension for Microsoft Entra Cloud Sync is only supported for applications with the identifier URI “api://<tenantId>/CloudSyncCustomExtensionsApp” and the Tenant Schema Extension App created by Microsoft Entra Connect

Create application and service principal for directory extension

You need to create an application with the identifier URI "api://<tenantId>/CloudSyncCustomExtensionsApp" if it doesn't exist and create a service principal for the application if it doesn't exist.

  1. Check if application with the identifier URI "api://<tenantId>/CloudSyncCustomExtensionsApp" exists.

    • Using Microsoft Graph
    GET /applications?$filter=identifierUris/any(uri:uri eq 'api://<tenantId>/CloudSyncCustomExtensionsApp')

    For more information, see Get application

    • Using PowerShell
    Get-MgApplication -Filter "identifierUris/any(uri:uri eq 'api://<tenantId>/CloudSyncCustomExtensionsApp')"

    For more information, see Get-MgApplication

  2. If the application doesn't exist, create the application with identifier URI "api://<tenantId>/CloudSyncCustomExtensionsApp."

    • Using Microsoft Graph
    POST https://graph.microsoft.com/v1.0/applications
Content-type: application/json

{
 "displayName": "CloudSyncCustomExtensionsApp",
 "identifierUris": ["api://<tenant id>/CloudSyncCustomExtensionsApp"]
}

    For more information, see create application

    • Using PowerShell
    New-MgApplication -DisplayName "CloudSyncCustomExtensionsApp" -IdentifierUris "api://<tenant id>/CloudSyncCustomExtensionsApp"

    For more information, see New-MgApplication

  3. Check if the service principal exists for the application with identifier URI "api://<tenantId>/CloudSyncCustomExtensionsApp."

    • Using Microsoft Graph
    GET /servicePrincipals?$filter=(appId eq '{appId}')

    For more information, see get service principal

    • Using PowerShell
    Get-MgServicePrincipal -Filter "AppId eq '<application id>'"

    For more information, see Get-MgServicePrincipal

  4. If a service principal doesn't exist, create a new service principal for the application with identifier URI "api://<tenantId>/CloudSyncCustomExtensionsApp."

    • Using Microsoft Graph
    POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
"appId": 
"<application appId>"
}

    For more information, see create servicePrincipal

    • Using PowerShell
    New-MgServicePrincipal -AppId '<appId>'

    For more information, see New-MgServicePrincipal

  5. You can create directory extensions in Microsoft Entra ID in several different ways.

Method Description URL
MS Graph Create extensions using GRAPH Create extensionProperty
PowerShell Create extensions using PowerShell New-MgApplicationExtensionProperty
Using cloud sync and Microsoft Entra Connect Create extensions using Microsoft Entra Connect Create an extension attribute using Microsoft Entra Connect
Customizing attributes to sync Information on customizing, which attributes to synch Customize which attributes to synchronize with Microsoft Entra ID

Use attribute mapping to map Directory Extensions

If you have extended Active Directory to include custom attributes, you can add these attributes and map them to users.

To discover and map attributes, select Add attribute mapping. The attributes will automatically be discovered and will be available in the drop-down under source attribute. Fill in the type of mapping you want and select Apply. Custom attribute mapping

For information on new attributes that are added and updated in Microsoft Entra ID see the user resource type and consider subscribing to change notifications.

For more information on extension attributes, see Syncing extension attributes for Microsoft Entra Application Provisioning.

Additional resources