|
| 1 | +--- |
| 2 | +title: 'Azure AD Connect cloud sync directory extensions and custom attribute mapping' |
| 3 | +description: This topic provides information on custom attribute mapping in cloud sync. |
| 4 | +services: active-directory |
| 5 | +author: billmath |
| 6 | +manager: amycolannino |
| 7 | +ms.service: active-directory |
| 8 | +ms.workload: identity |
| 9 | +ms.custom: ignite-2022 |
| 10 | +ms.topic: conceptual |
| 11 | +ms.date: 01/12/2023 |
| 12 | +ms.subservice: hybrid |
| 13 | +ms.author: billmath |
| 14 | +ms.collection: M365-identity-device-management |
| 15 | +--- |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | +# Cloud Sync directory extensions and custom attribute mapping |
| 20 | + |
| 21 | +## Directory extensions |
| 22 | +You can use directory extensions to extend the schema in Azure Active Directory (Azure AD) 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. |
| 23 | + |
| 24 | +For additional information on directory extensions see [Using directory extension attributes in claims](../develop/active-directory-schema-extensions.md) |
| 25 | + |
| 26 | + You can see the available attributes by using [Microsoft Graph Explorer](https://developer.microsoft.com/graph/graph-explorer). You can also use this feature to create dynamic groups in Azure AD. |
| 27 | + |
| 28 | +>[!NOTE] |
| 29 | +> 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 Azure AD extension attributes, the agent doesn't need to be restarted. |
| 30 | + |
| 31 | +## Syncing directory extensions for Azure Active Directory Connect cloud sync |
| 32 | + |
| 33 | +You can use [directory extensions](https://learn.microsoft.com/graph/api/resources/extensionproperty?view=graph-rest-1.0) to extend the synchronization schema directory definition in Azure Active Directory (Azure AD) with your own attributes. |
| 34 | + |
| 35 | +>[!Important] |
| 36 | +> Directory extension for Azure Active Directory Connect cloud sync is only supported for applications with the identifier URI “api://<tenantId>/CloudSyncCustomExtensionsApp” and the [Tenant Schema Extension App](../hybrid/how-to-connect-sync-feature-directory-extensions.md#configuration-changes-in-azure-ad-made-by-the-wizard) created by Azure AD Connect |
| 37 | +
|
| 38 | +### Create application and service principal for directory extension |
| 39 | + |
| 40 | +You need to create an [application](https://learn.microsoft.com/graph/api/resources/application?view=graph-rest-1.0) 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. |
| 41 | + |
| 42 | + |
| 43 | + 1. Check if application with the identifier URI "api://<tenantId>/CloudSyncCustomExtensionsApp" exists. |
| 44 | + |
| 45 | + - Using Microsoft Graph |
| 46 | + |
| 47 | + ``` |
| 48 | + GET /applications?$filter=identifierUris/any(uri:uri eq 'api://<tenantId>/CloudSyncCustomExtensionsApp') |
| 49 | + ``` |
| 50 | +
|
| 51 | + For more information, see [Get application](https://learn.microsoft.com/graph/api/application-get?view=graph-rest-1.0&tabs=http) |
| 52 | +
|
| 53 | + - Using PowerShell |
| 54 | + |
| 55 | + ``` |
| 56 | + Get-AzureADApplication -Filter "identifierUris/any(uri:uri eq 'api://<tenantId>/CloudSyncCustomExtensionsApp')" |
| 57 | + ``` |
| 58 | +
|
| 59 | + For more information, see [Get-AzureADApplication](https://learn.microsoft.com/powershell/module/azuread/get-azureadapplication?view=azureadps-2.0) |
| 60 | +
|
| 61 | + 2. If the application doesn't exist, create the application with identifier URI “api://<tenantId>/CloudSyncCustomExtensionsApp.” |
| 62 | +
|
| 63 | + - Using Microsoft Graph |
| 64 | + ``` |
| 65 | + POST https://graph.microsoft.com/v1.0/applications |
| 66 | + Content-type: application/json |
| 67 | +
|
| 68 | + { |
| 69 | + "displayName": "CloudSyncCustomExtensionsApp", |
| 70 | + "identifierUris": ["api://<tenant id>/CloudSyncCustomExtensionsApp"] |
| 71 | + } |
| 72 | + ``` |
| 73 | + For more information, see [create application](https://learn.microsoft.com/graph/api/application-post-applications?view=graph-rest-1.0&tabs=http) |
| 74 | +
|
| 75 | + - Using PowerShell |
| 76 | + ``` |
| 77 | + New-AzureADApplication -DisplayName "CloudSyncCustomExtensionsApp" -IdentifierUris "api://<tenant id>/CloudSyncCustomExtensionsApp" |
| 78 | + ``` |
| 79 | + For more information, see [New-AzureADApplication](https://learn.microsoft.com/powershell/module/azuread/new-azureadapplication?view=azureadps-2.0) |
| 80 | +
|
| 81 | + |
| 82 | +
|
| 83 | + 3. Check if the service principal exists for the application with identifier URI “api://<tenantId>/CloudSyncCustomExtensionsApp”. |
| 84 | +
|
| 85 | + - Using Microsoft Graph |
| 86 | + ``` |
| 87 | + GET /servicePrincipals?$filter=(appId eq '{appId}') |
| 88 | + ``` |
| 89 | + For more information, see [get service principal](https://learn.microsoft.com/graph/api/serviceprincipal-get?view=graph-rest-1.0&tabs=http) |
| 90 | +
|
| 91 | + - Using PowerShell |
| 92 | + ``` |
| 93 | + Get-AzureADServicePrincipal -ObjectId '<application objectid>' |
| 94 | + ``` |
| 95 | + For more information, see [Get-AzureADServicePrincipal](https://learn.microsoft.com/powershell/module/azuread/get-azureadserviceprincipal?view=azureadps-2.0) |
| 96 | + |
| 97 | +
|
| 98 | + 4. If a service principal doesn't exist, create a new service principal for the application with identifier URI “api://<tenantId>/CloudSyncCustomExtensionsApp” |
| 99 | +
|
| 100 | + - Using Microsoft Graph |
| 101 | + ``` |
| 102 | + POST https://graph.microsoft.com/v1.0/servicePrincipals |
| 103 | + Content-type: application/json |
| 104 | +
|
| 105 | + { |
| 106 | + "appId": |
| 107 | + "<application appId>" |
| 108 | + } |
| 109 | + ``` |
| 110 | + For more information, see [create servicePrincipal](https://learn.microsoft.com/graph/api/serviceprincipal-post-serviceprincipals?view=graph-rest-1.0&tabs=http) |
| 111 | +
|
| 112 | + - Using PowerShell |
| 113 | + |
| 114 | + ``` |
| 115 | + New-AzureADServicePrincipal -AppId '<appId>' |
| 116 | + ``` |
| 117 | + For more information, see [New-AzureADServicePrincipal](https://learn.microsoft.com/powershell/module/azuread/new-azureadserviceprincipal?view=azureadps-2.0) |
| 118 | + |
| 119 | + 5. You can create directory extensions in Azure AD in several different ways. |
| 120 | +
|
| 121 | +|Method|Description|URL| |
| 122 | +|-----|-----|-----| |
| 123 | +|MS Graph|Create extensions using GRAPH|[Create extensionProperty](https://learn.microsoft.com/graph/api/application-post-extensionproperty?view=graph-rest-1.0&tabs=http)| |
| 124 | +|PowerShell|Create extensions using PowerShell|[New-AzureADApplicationExtensionProperty](https://learn.microsoft.com/powershell/module/azuread/new-azureadapplicationextensionproperty?view=azureadps-2.0)| |
| 125 | +Using Cloud Sync and Azure AD Connect|Create extensions using Azure AD Connect|[Create an extension attribute using Azure AD Connect](https://learn.microsoft.com/azure/active-directory/app-provisioning/user-provisioning-sync-attributes-for-mapping#create-an-extension-attribute-using-azure-ad-connect)| |
| 126 | +|Customizing attributes to sync|Information on customizing which attributes to synch|[Customize which attributes to synchronize with Azure AD](https://learn.microsoft.com/azure/active-directory/hybrid/how-to-connect-sync-feature-directory-extensions#customize-which-attributes-to-synchronize-with-azure-ad) |
| 127 | +
|
| 128 | +## Use attribute mapping to map Directory Extensions |
| 129 | +If you have extended Active Directory to include custom attributes, you can add these attributes and map them to users. |
| 130 | +
|
| 131 | +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**. |
| 132 | + [](media/custom-attribute-mapping/schema-1.png#lightbox) |
| 133 | +
|
| 134 | +For information on new attributes that are added and updated in Azure AD see the [user resource type](https://docs.microsoft.com/graph/api/resources/user?view=graph-rest-1.0#properties) and consider subscribing to [change notifications](https://docs.microsoft.com/graph/webhooks). |
| 135 | +
|
| 136 | +For more information on extension attributes, see [Syncing extension attributes for Azure Active Directory Application Provisioning](../app-provisioning/user-provisioning-sync-attributes-for-mapping.md) |
| 137 | +
|
| 138 | +## Additional resources |
| 139 | +
|
| 140 | +- [Understand the Azure AD schema and custom expressions](concept-attributes.md) |
| 141 | +- [Azure AD Connect sync: Directory extensions](../hybrid/how-to-connect-sync-feature-directory-extensions.md) |
| 142 | +- [Attribute mapping in Azure AD Connect cloud sync](how-to-attribute-mapping.md) |
0 commit comments