Adding Optional Claims Using Token Configuration in Microsoft Entra ID

Gowtham K
19h
115
0
0

Article

Introduction

In many enterprise applications, user profile information such as first name and last name is required to personalize the user experience. Applications often display welcome messages, user profile pages, audit logs, or account settings using these attributes.

In my previous article, I demonstrated how to customize tokens using Claims Mapping Policies and explained the purpose of the acceptMappedClaims setting when working with customized claims. While Claims Mapping Policies provide advanced token customization capabilities, they may be unnecessary for simple scenarios where an application only needs standard user attributes such as first name and last name.

Microsoft Entra ID provides a simpler, fully supported approach called Optional Claims that allows administrators to include predefined user attributes in tokens without creating Claims Mapping Policies or modifying the application manifest.

What Are Optional Claims?

When Microsoft Entra ID issues an ID token or access token, it includes a default set of claims that identify the user and the tenant.

Some commonly issued default claims include:

{
  "aud": "application-id",
  "iss": "https://login.microsoftonline.com/{tenant-id}",
  "sub": "user-identifier",
  "oid": "object-id",
  "tid": "tenant-id"
}

However, many applications require additional user profile information, such as:

First Name (given_name)
Last Name (family_name)
Email Address

Preferred Username
Employee Information

Instead of creating a Claims Mapping Policy, Microsoft Entra ID allows you to add these predefined attributes through Optional Claims.

Optional Claims provide a straightforward way to enrich tokens with commonly used user attributes while keeping the configuration simple and easy to maintain.

Benefits of Optional Claims

Optional Claims offer several advantages:

Easy configuration through the Microsoft Entra admin center
No Claims Mapping Policy required
No Service Principal assignment required
No acceptMappedClaims configuration required

For simple token customization requirements, Optional Claims is generally preferred.

Configure Optional Claims in Microsoft Entra ID

Follow the steps below to add first name and last name claims to your application token.

Step 1 – Open App Registration

Microsoft Entra ID -> App Registration -> Select your application

Step 2 – Open Token Configuration

From the left navigation menu, select:

Token configuration -> You will see the Token Configuration page.

Step 3 – Add Optional Claims

Click: + Add optional claim

A new panel appears asking you to choose the token type.

Select: ID

The ID token is typically used by web applications to identify the authenticated user.

Step 4 – Select First Name and Last Name Claims

From the list of available claims, select:

given_name
family_name

Click Add to save the configuration.

Run the Application and Verify the Claims

Verify the claim using my sample MVC application Entra-ID-MVC-App, just by replacing with your MS Entra ID Application configuration.

Optional Claims vs Claims Mapping Policies

Many developers wonder when they should use Optional Claims instead of Claims Mapping Policies.

Feature	Optional Claims	Claims Mapping Policies
Portal-based configuration	Yes	No
Simple setup	Yes	No
Requires Service Principal assignment	No	Yes
Supports custom claim names	No	Yes
Requires acceptMappedClaims	No	Yes
Supports standard user attributes	Yes	Yes
Supports claim transformations	No	Yes

For standard user profile attributes such as first name and last name, Optional Claims are usually the best choice.

Claims Mapping Policies should be reserved for advanced token customization scenarios

Summary

Optional Claims provide a simple and supported mechanism for including additional user attributes in tokens issued by Microsoft Entra ID.

For most applications that require standard user attributes such as first name, last name, email address, or preferred username, Optional Claims offer a much simpler alternative to Claims Mapping Policies. By using Token Configuration, administrators can enrich tokens with additional information while avoiding the complexity associated with custom claim mapping and token transformation policies.