Edit

Cloud Sync directory extensions and custom attribute mapping

  • Article

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.

For additional information on directory extensions see Using directory extension attributes in claims

You can see the available attributes by using Microsoft Graph Explorer. You can also use this feature to create dynamic groups in Microsoft Entra ID.

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 Connect 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 Connect 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-AzureADApplication -Filter "identifierUris/any(uri:uri eq 'api://<tenantId>/CloudSyncCustomExtensionsApp')"

    For more information, see Get-AzureADApplication

  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-AzureADApplication -DisplayName "CloudSyncCustomExtensionsApp" -IdentifierUris "api://<tenant id>/CloudSyncCustomExtensionsApp"

    For more information, see New-AzureADApplication

  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-AzureADServicePrincipal -ObjectId  '<application objectid>'

    For more information, see Get-AzureADServicePrincipal

  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-AzureADServicePrincipal -AppId '<appId>'

    For more information, see New-AzureADServicePrincipal

  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-AzureADApplicationExtensionProperty
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, click 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 click 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