Microsoft guide to issuing custom SSO claims with Entra ID directory extensions

Integrating custom Security Assertion Markup Language (SAML) claims with Microsoft Entra ID (formerly Azure Active Directory) can significantly enhance security and user experience for single sign-on (SSO) applications. This process allows organizations to tailor the information sent in a SAML token to meet the specific requirements of their applications, moving beyond the standard attributes provided by default. By leveraging Entra ID directory extensions, administrators can enrich user objects with custom data and then expose this data as claims within SAML assertions, enabling more granular access control and personalized application experiences.

This capability is particularly valuable in scenarios where applications rely on specific user attributes for authorization, user provisioning, or displaying user-specific content. For instance, an application might need to know a user’s department, cost center, or a custom role identifier that isn’t part of the default Entra ID schema. By mapping these custom attributes to SAML claims, applications can directly consume this information during the SSO process, simplifying integration and reducing the need for post-authentication lookups or custom logic within the application itself. This guide delves into the practical steps and considerations for implementing custom SSO claims using Entra ID directory extensions.

Understanding SAML Claims and Entra ID Directory Extensions

SAML claims are statements about a subject (usually a user) that are asserted by an identity provider, in this case, Microsoft Entra ID. These claims are embedded within a SAML token and transmitted to a service provider (the application) during the authentication process. Standard claims often include user identifiers like the User Principal Name (UPN) or object ID, but custom claims allow for the inclusion of any attribute associated with the user object.

Entra ID directory extensions provide a mechanism to extend the user object schema with custom attributes. These extensions can store additional information about users that is not covered by the standard Entra ID attributes. Once these custom attributes are populated with data, they can be referenced and emitted as custom claims in SAML tokens issued by Entra ID.

The process involves defining the directory extension, populating it with data for your users, and then configuring Entra ID to include these extended attributes as claims in the SAML assertion sent to your application. This offers a powerful way to customize the information flow and integrate applications more tightly with your identity management system.

Defining and Creating Directory Extensions

Before you can issue custom SAML claims, you need to define the custom attributes that will store your unique user data. These are known as directory extensions in Entra ID. The creation of directory extensions is typically handled using the Microsoft Graph API or PowerShell modules designed for Entra ID management.

When creating a directory extension, you specify its name and data type. For example, you might create an extension to store a user’s “employeeType” or “internalProjectCode.” These extensions are associated with the user object type. It’s crucial to choose descriptive names for your extensions to ensure clarity and maintainability. A common naming convention is to prefix custom extensions, such as `extension_YourAppPrefix_AttributeName`, to avoid conflicts and clearly identify them as custom attributes.

For instance, to create an extension for an employee type, you might define an attribute named `extension_Contoso_employeeType` with a string data type. This attribute will then be available on the user object in Entra ID. The process requires appropriate administrative permissions within your Entra ID tenant.

Populating Directory Extensions with User Data

Once directory extensions are defined, the next step is to populate them with relevant data for your users. This data can be synchronized from on-premises Active Directory using Entra ID Connect, imported in bulk, or updated individually through administrative tools or automated processes.

For on-premises synchronized users, you can map attributes from your on-premises AD schema to the corresponding Entra ID directory extensions. This synchronization ensures that custom user data, such as department or employee ID, flows seamlessly to Entra ID. For cloud-only users or to manage custom attributes directly within Entra ID, bulk import using CSV files or individual updates via the Microsoft Graph API or PowerShell are effective methods.

For example, if you created the `extension_Contoso_employeeType` extension, you would update user objects with values like “Full-time,” “Contractor,” or “Intern.” This population step is critical; without data in the extension attributes, there will be no custom claims to emit.

Configuring SAML Application SSO with Custom Claims

The core of issuing custom SSO claims lies in configuring your SAML application within Entra ID to emit these attributes. This is done within the Entra ID application registration, specifically in the Single sign-on settings for the SAML-based application. You will need to access the “Attributes & Claims” section for the enterprise application representing your SAML application.

Here, you can define new claims to be included in the SAML token. For each custom claim, you specify the “Name” (which is how the claim will appear in the SAML assertion, often referred to as the claim type or URI) and the “Namespace” (an optional URI that helps qualify the claim name). The “Source” of the claim will be set to “Attribute,” and you will select the specific directory extension attribute you want to emit from the dropdown list.

For example, to emit the `extension_Contoso_employeeType` as a custom claim named `http://schemas.contoso.com/claims/employeetype`, you would configure a new claim. The “Name” would be `http://schemas.contoso.com/claims/employeetype`, the “Namespace” might be `http://schemas.contoso.com/claims/`, and the “Source” would be “Attribute,” with the source attribute being `user.extension_Contoso_employeeType`.

Advanced Claim Transformation and Customization

Entra ID offers powerful capabilities for transforming the values of claims before they are emitted. This is essential when the data stored in a directory extension needs to be presented in a different format or mapped to a specific value expected by the service provider.

Claim transformations allow you to modify the claim value based on rules. Common transformations include converting string values, extracting specific parts of a string, or replacing values with different ones. For instance, if your `extension_Contoso_employeeType` stores values like “FT” for full-time and “CT” for contractor, you might use a transformation to convert these to “Full-time” and “Contractor” respectively, matching the application’s expected format.

You can also define conditional claims, where a claim is only emitted if a certain condition is met, or if the attribute has a specific value. This provides fine-grained control over the information sent to the application, enhancing security and reducing the size of the SAML token. These transformations are configured within the “Attributes & Claims” section of the SAML application’s SSO settings, under the “Transformations” tab for a specific claim.

Testing and Troubleshooting Custom Claims

Thorough testing is paramount after configuring custom SAML claims. The best way to verify that your claims are being issued correctly is to initiate an SSO login to your SAML application and inspect the SAML token. Browser extensions like “SAML-tracer” or “SAML Chrome Panel” are invaluable tools for capturing and analyzing the SAML assertion sent to the service provider.

Examine the captured SAML assertion to confirm that your custom claims are present, correctly named, and contain the expected values. Pay close attention to the claim names, namespaces, and the data within the claim values. If a custom claim is missing or incorrect, revisit the configuration in Entra ID’s “Attributes & Claims” section and verify the directory extension attribute, its value, and any applied transformations.

Common issues include typos in claim names or namespaces, incorrect mapping of directory extension attributes, or problems with claim transformations. Ensure that the user you are testing with actually has a value populated in the relevant directory extension attribute. If the attribute is empty for a user, the claim will not be emitted for that user.

Security Considerations for Custom Claims

While custom claims offer flexibility, they also introduce security considerations that must be carefully managed. Emitting sensitive information as claims increases the attack surface if the SAML token is intercepted or if the service provider mishandles the data.

Always adhere to the principle of least privilege when defining and emitting custom claims. Only include attributes that are strictly necessary for the application’s functionality. Avoid embedding highly sensitive personal identifiable information (PII) or credentials directly as claims unless absolutely required and adequately protected.

Furthermore, ensure that your SAML application is configured to validate incoming SAML tokens properly and that it handles the received claims securely. The security of the custom claims is a shared responsibility between Entra ID (as the identity provider) and the service provider (the application).

Managing Directory Extensions at Scale

For large organizations, managing directory extensions and their associated user data requires a scalable approach. Relying on manual updates for hundreds or thousands of users is impractical and prone to errors.

Leverage Entra ID Connect for synchronizing custom attributes from on-premises Active Directory. This is often the most efficient method for maintaining consistency between on-premises and cloud identities. For cloud-only scenarios, explore bulk update capabilities through PowerShell or the Microsoft Graph API for initial population and ongoing management.

Automating the population and update processes can significantly reduce administrative overhead and improve data accuracy. Consider developing scripts or integrating with HR systems to ensure custom attributes are kept up-to-date as user roles or project assignments change.

Using Custom Claims for Application Authorization

Custom SAML claims can be powerful tools for implementing fine-grained authorization within your applications. Instead of relying solely on user roles managed within the application itself, you can push authorization-related attributes directly from Entra ID.

For example, a custom claim could represent a user’s access level, project membership, or security clearance. The application can then read this claim upon successful authentication and dynamically adjust the user’s permissions or the features they can access. This simplifies user management, especially in complex environments with many applications and varying access requirements.

This approach centralizes authorization logic within Entra ID, making it easier to manage and audit access policies across your organization. When a user’s role or project assignment changes in Entra ID, the corresponding claim is updated, and the application automatically reflects these changes during the next SSO session.

Integrating with Graph API for Dynamic Claims

While directory extensions are the primary method for custom claims, more dynamic scenarios might require retrieving information not directly stored as an attribute. The Microsoft Graph API can be leveraged to fetch additional user information or related data that can then be dynamically included as claims.

This advanced technique involves using custom logic, potentially within an Azure Function or a middleware service, that intercepts the SAML authentication flow. This logic can call the Graph API to gather specific data based on the authenticated user and then construct a custom claim with that data before the SAML token is finalized.

This approach is more complex but offers unparalleled flexibility for scenarios where data is not static or is spread across multiple Microsoft 365 services. It allows for the creation of highly personalized and context-aware SSO experiences by enriching the SAML token with real-time information.

Best Practices for Naming and Namespaces

Consistent and well-defined naming conventions for custom claims and their namespaces are critical for maintainability and avoiding conflicts. Use clear, descriptive names that indicate the purpose of the claim.

For namespaces, it is recommended to use URIs that represent your organization or a specific application domain. For example, `http://schemas.yourcompany.com/claims/` or `https://your-application.com/claims/`. This helps to ensure that your custom claims do not clash with standard SAML claims or claims defined by other organizations.

When configuring claims in Entra ID, the “Name” field typically uses the full URI, including the namespace. For instance, `http://schemas.yourcompany.com/claims/department`. The “Namespace” field itself might be a separate input in some configurations, or it might be implicitly part of the “Name” field.

Handling Different Data Types in Claims

Directory extensions can support various data types, including strings, integers, booleans, and more. When configuring these as SAML claims, Entra ID typically serializes them into string format within the SAML assertion. It’s important for the consuming application to be able to parse these string representations correctly.

For example, a boolean attribute stored as `true` or `false` in Entra ID will be sent as the string “true” or “false” in the SAML token. Similarly, numerical values will be sent as their string representations. Ensure that your application’s logic can convert these string values back to their appropriate data types if needed for processing.

Some SAML implementations also support different claim formats, such as XML-based structures within a claim value. However, for most common SSO scenarios, string-based representations of attribute values are standard and widely supported.

User Consent and Privacy Implications

When introducing new directory extensions and custom claims, it’s important to consider user consent and privacy. Users should be aware of what additional information is being collected about them and how it will be used and shared with applications.

Organizations should have clear privacy policies that outline the use of custom attributes and claims. For sensitive data, obtaining explicit user consent might be necessary, depending on your organization’s data privacy regulations and internal policies. Transparency is key to building trust with your users.

Entra ID provides mechanisms for managing user consent for application permissions, but the data itself being stored and emitted as claims is primarily an organizational policy and data governance matter. Ensure that your data handling practices comply with relevant regulations like GDPR or CCPA.

Delegating Directory Extension Management

For very large organizations, it might be beneficial to delegate the management of specific directory extensions or the population of their attributes to different teams or departments. Entra ID offers role-based access control (RBAC) that can be used to grant permissions for managing custom attributes.

You can create custom administrative roles in Entra ID that grant permissions to manage specific types of directory extensions or to update attributes on user objects. This allows for distributed management of user data without giving broad administrative privileges.

For example, a Human Resources department might be granted permission to manage the `extension_Contoso_employeeType` and `extension_Contoso_department` attributes for all users, while a project management office could manage project-specific extension attributes. This delegation streamlines operations and improves efficiency.

Monitoring and Auditing Custom Claims Usage

Regular monitoring and auditing of custom claims usage are essential for security and compliance. Entra ID provides audit logs that record various activities, including changes to application configurations and the issuance of SAML tokens.

By reviewing these logs, administrators can track when custom claims were added or modified, which users are authenticating with which claims, and identify any suspicious activity. This information is crucial for troubleshooting, security investigations, and demonstrating compliance with internal policies and external regulations.

Focus on auditing changes to the “Attributes & Claims” configuration for your SAML applications and monitor sign-in logs for any anomalies related to custom claim issuance. This proactive approach helps maintain a secure and well-governed identity environment.