Cloud Sync directory extensions and custom attribute mapping
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.
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
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
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
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
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.
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
Feedback
Submit and view feedback for