|
| 1 | +--- |
| 2 | +title: Directory extension attributes in claims |
| 3 | +description: Describes directory extension attributes that are used for sending user data to applications in token claims. |
| 4 | +services: active-directory |
| 5 | +author: davidmu1 |
| 6 | +manager: CelesteDG |
| 7 | +ms.service: active-directory |
| 8 | +ms.subservice: develop |
| 9 | +ms.custom: aaddev, curation-claims |
| 10 | +ms.workload: identity |
| 11 | +ms.topic: conceptual |
| 12 | +ms.date: 05/26/2023 |
| 13 | +ms.author: davidmu |
| 14 | +ms.reviewer: ludwignick, rahulnagraj, alamaral |
| 15 | +--- |
| 16 | +# Directory extension attributes in claims |
| 17 | + |
| 18 | +Directory extension attributes provide a way to store more data on directory objects such as users. Only extension attributes on user objects can be used for emitting claims to applications. This article describes how to use directory extension attributes for sending user data to applications in token claims. |
| 19 | + |
| 20 | +> [!NOTE] |
| 21 | +> Microsoft Graph provides three other extension mechanisms to customize Graph objects. These are the extension attributes 1-15, open extensions, and schema extensions. See the [Microsoft Graph documentation](/graph/extensibility-overview) for details. Data stored on Microsoft Graph objects using open and schema extensions aren't available as sources for claims in tokens. |
| 22 | +
|
| 23 | +Directory extension attributes are always associated with an application in the tenant. The name of the directory attribute includes the *appId* of the application in its name. |
| 24 | + |
| 25 | +The identifier for a directory extension attribute is of the form `extension_xxxxxxxxx_AttributeName`. Where `xxxxxxxxx` is the *appId* of the application the extension was defined for, with only characters 0-9 and A-Z. |
| 26 | + |
| 27 | +## Register and use directory extensions |
| 28 | + |
| 29 | +Register directory extension attributes in one of the following ways: |
| 30 | + |
| 31 | +- Configure Azure AD Connect to create them and to sync data into them from on-premises. See [Azure AD Connect Sync Directory Extensions](../hybrid/how-to-connect-sync-feature-directory-extensions.md). |
| 32 | +- Use Microsoft Graph to register, set the values of, and read from [directory extensions](/graph/extensibility-overview#directory-azure-ad-extensions). [PowerShell cmdlets](/powershell/azure/active-directory/using-extension-attributes-sample) are also available. |
| 33 | + |
| 34 | +### Emit claims with data from Azure AD Connect |
| 35 | + |
| 36 | +Directory extension attributes created and synced using Azure AD Connect are always associated with the application ID used by Azure AD Connect. These attributes can be used as a source for claims both by configuring them as claims in **Enterprise Applications** configuration in the Portal. After a directory extension attribute is created using AD Connect, it's displayed in the SAML SSO claims configuration. |
| 37 | + |
| 38 | +### Emit claims using Graph or PowerShell |
| 39 | + |
| 40 | +If a directory extension attribute is registered for using Microsoft Graph or PowerShell, the application can be configured to receive data in that attribute when the user signs in. The application can be configured to receive data in directory extensions that are registered on the application using [optional claims](optional-claims.md) that can be set in the application manifest. |
| 41 | + |
| 42 | +Multi-tenant applications can then register directory extension attributes for their own use. When the application is provisioned into a tenant, the associated directory extensions become available and consumed for users in that tenant. After the directory extension is available, it can be used to store and retrieve data using Microsoft Graph. The directory extension can also map to claims in tokens the Microsoft identity platform emits to applications. |
| 43 | + |
| 44 | +If an application needs to send claims with data from an extension attribute that's registered on a different application, a [claims mapping policy](active-directory-claims-mapping.md) must be used to map the extension attribute to the claim. |
| 45 | + |
| 46 | +A common pattern for managing directory extension attributes is to register an application specifically for all the directory extensions that you need. When you use this type of application, all the extensions have the same appID in their name. |
| 47 | + |
| 48 | +For example, the following code shows a claims-mapping policy to emit a single claim from a directory extension attribute in an OAuth/OIDC token: |
| 49 | + |
| 50 | +```json |
| 51 | +{ |
| 52 | + "ClaimsMappingPolicy": { |
| 53 | + "Version": 1, |
| 54 | + "IncludeBasicClaimSet": "false", |
| 55 | + "ClaimsSchema": [{ |
| 56 | + "Source": "User", |
| 57 | + "ExtensionID": "extension_xxxxxxx_test", |
| 58 | + "JWTClaimType": "http://schemas.contoso.com/identity/claims/exampleclaim" |
| 59 | + }, |
| 60 | + ] |
| 61 | + } |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +Where `xxxxxxx` is the appID (or Client ID) of the application that the extension was registered with. |
| 66 | + |
| 67 | +> [!WARNING] |
| 68 | +> When you define a claims mapping policy for a directory extension attribute, use the `ExtensionID` property instead of the `ID` property within the body of the `ClaimsSchema` array, as shown in the previous example. |
| 69 | +
|
| 70 | +> [!TIP] |
| 71 | +> Case consistency is important when you set directory extension attributes on objects. Extension attribute names aren't case sensitive when being set up, but they are case sensitive when being read from the directory by the token service. If an extension attribute is set on a user object with the name "LegacyId" and on another user object with the name "legacyid", when the attribute is mapped to a claim using the name "LegacyId" the data is successfully retrieved and the claim included in the token for the first user but not the second. |
| 72 | +
|
| 73 | +## Next steps |
| 74 | +- Learn how to [customize claims emitted in tokens for a specific app](active-directory-claims-mapping.md). |
0 commit comments