Background

Recently I was engaged to assist a customer with an interesting issue. This customer follows the guideline at https://docs.microsoft.com/en-us/previous-versions/azure/ad/graph/howto/azure-ad-graph-api-directory-schema-extensions to create a custom User attribute as a Directory schema extension and then assigns a value to the attribute. As an example, I have a few custom attributes created this way as can be seen by Microsoft Graph Explorer:

The customer wants to have this custom attribute returned as a claim in a SAML token when using an Enterprise Application to sign users in.

Note: By default, Azure AD only returns the claim if its value is not null.

Resolution

After spending some time researching, the only way to achieve this is by using claims mapping policy as detailed below. It’s important to note that custom attributes created this way do not show up in the Enterprise Application’s Single Sign-on User Attributes & claims customization wizard.

  1. Run the following Azure AD Powershell (must use AzureAD-Preview module) command to log in with an organizational admin account

    Connect-AzureAD

  2. Create a new claims mapping policy similar to the following. In this example, I want to include the customer attribute ‘extension_a5c236591f3f48b39a63d962d7364ad2_ClaimsxrayAttrib’ in my SAML token:

    New-AzureADPolicy -Definition @(‘{“ClaimsMappingPolicy”:{“Version”:1,”IncludeBasicClaimSet”:”true”, “ClaimsSchema”: [{“Source”:”user”,”ExtensionID”:”extension_a5c236591f3f48b39a63d962d7364ad2_ClaimsxrayAttrib”,”SamlClaimType”:”http://schemas.xmlsoap.org/ws/2005/05/identity/claims/extension_a5c236591f3f48b39a63d962d7364ad2_ClaimsxrayAttrib”}]}}’) -DisplayName “ClaimsxrayPolicy3” -Type “ClaimsMappingPolicy

  3. Assign the policy to the Enterprise Application:

    Add-AzureADServicePrincipalPolicy -Id <Enterprise App objectID> -RefObjectId <Policy ID>

    To find the Enterprise App Object ID, look at the Object ID field from the ‘Properties’ blade for the Enterprise Application:

If configured properly you should see desired claim in the AttributeStatement section of the SAML token:

<AttributeStatement>
…
     <Attribute  Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/extension_a5c236591f3f48b39a63d962d7364ad2_ClaimsxrayAttrib">
	<AttributeValue>My Cool claims</AttributeValue>
     </Attribute>
</AttributeStatement>

4 Thoughts to “How to customize SAML token claims to include custom attribute created as Directory Schema Extension in Azure AD”

  1. Bryn Richards

    Is it possible to set extension claims against a service principal (authenticating with a client_id and client_secret) and source these inside an access token ? I’ve been able to source claims with an “application” source from the service principal, but only for the “tags” and “displayname” properties… it didn’t look possible to add an Application extension property that targets a service principal.

    1. Bac Hoang [MSFT]

      Interesting idea. I honestly don’t know if this is possible. Can you open a support case with us and we can investigate?

    2. Steve Cleynen

      Hi, Did you ever figured this out. I’m struggling with the same issue?

      1. Bac Hoang [MSFT]

        Based on the claims schema docs at https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-claims-mapping#table-3-valid-id-values-per-source you can only use these IDs: displayName, ObjectID, and tags for the Application source.

Leave a Reply to Bac Hoang [MSFT] Cancel reply