Azure AD B2C Custom Claims for Advanced Security

Adding Custom Claims to Azure AD B2C Tokens

Enhancing security and providing richer user context in your applications often requires including specific, custom information within the authentication tokens issued by Azure Active Directory B2C (Azure AD B2C). This guide will walk you through the process of defining and including custom claims in your ID and Access tokens.

Why Use Custom Claims?

Standard claims like user ID, name, and email are fundamental. However, you might need to send additional data to your application for various purposes:

Authorization: Include user roles, group memberships, or specific permissions.
User Preferences: Pass on user-defined settings or preferences.
Tenant-Specific Data: Include information relevant to a particular tenant or organization the user belongs to.
Application-Specific Data: Embed any data your application logic relies on for personalization or feature enablement.

Important: Custom claims are embedded directly into the token. Be mindful of token size limitations and the sensitivity of the data you are including. Avoid storing highly sensitive personal information that doesn't need to be readily available in the token.

Steps to Add Custom Claims

1. Define Custom Attributes

Before you can add custom claims to tokens, you need to define them as custom attributes in your Azure AD B2C directory. These attributes will store the data associated with your users.

Navigate to your Azure AD B2C tenant in the Azure portal.
Under "User attributes", select "Add".
Provide a descriptive name for your attribute (e.g., extension_userRoles, extension_tenantId). Azure AD B2C automatically prefixes custom attributes with extension_.
Choose the data type (e.g., String, Boolean, Integer).
Click "Create".

2. Populate Custom Attributes

You can populate these custom attributes in several ways:

During User Registration: Modify your user flows or custom policies to include fields for these attributes on the sign-up page.
Profile Editing: Allow users to update their custom attributes through a profile editing experience.
Programmatically: Use the Microsoft Graph API to update user attributes for existing users.

3. Configure Token Claims in User Flows or Custom Policies

The method for adding custom claims to tokens depends on whether you are using Azure AD B2C's built-in user flows or custom policies.

Using User Flows (Recommended for simplicity)

User flows offer a straightforward way to configure token claims.

In your Azure AD B2C tenant, navigate to "User flows".
Select the user flow you want to configure (e.g., your sign-up/sign-in flow).
Under "Settings", click on "Properties".
Scroll down to the "Token customization" section.
Click "Edit".
Under "User attributes", select the custom attributes you wish to include in the token.
Click "Save".

Example: If you created an attribute named extension_userRoles, select it from the list. It will appear in the token as userRoles.

Using Custom Policies (For advanced scenarios)

Custom policies provide maximum flexibility but involve editing XML files.

You'll need to define a TechnicalProfile that represents the claims you want to output. This typically involves referencing your custom attributes.

In your Relying Party (RP) file, within the OutputClaims section of your token issuing TechnicalProfile, add a new OutputClaim element:

<OutputClaim ClaimType="userRoles" PartnerClaimType="roles" Required="true" />

Here:

ClaimType: This is the name of the claim as it will appear in your technical profile's claims schema.
PartnerClaimType: This is the name that will appear in the actual token issued to your application. It's good practice to use a shorter, more application-friendly name.
Required="true": Indicates if the claim must be present.

You will also need to ensure that the custom attribute itself is correctly referenced and claims-transformed within your custom policy's identity provider or technical profiles. For instance, mapping the user's data from Azure AD B2C to this claim type.

Referencing Custom Attributes in Custom Policies: When using custom policies, ensure that the TechnicalProfile that reads user data (e.g., an Active Directory technical profile) correctly includes the custom attribute you wish to expose. You might need to add it to the OutputClaims of that technical profile and then map it to the desired ClaimType in your RP file.

4. Verify Custom Claims

After configuring your user flow or custom policy, test your sign-up or sign-in process. You can inspect the generated ID or Access tokens using browser developer tools or online JWT token decoders to verify that your custom claims are present and populated correctly.

Best Practices

Name Conventions: Use clear and consistent naming conventions for your custom attributes (e.g., extension_userRole, extension_department).
Token Size: Be mindful of the total size of the token. Adding too many claims can lead to performance issues or exceed token size limits, especially for custom policies.
Sensitivity: Only include data that is necessary for your application's functionality. Avoid embedding highly sensitive personal identifiable information (PII) if it's not strictly required in the token. Consider other Azure AD B2C features for secure data retrieval.
Documentation: Keep thorough documentation of your custom attributes and how they are used in tokens.

By effectively leveraging custom claims, you can build more secure, personalized, and context-aware applications with Azure AD B2C.