How do you customise token claims for applications in Microsoft Entra ID?

What changes when you customise token claims in Microsoft Entra ID?

Customising token claims is really about shaping the contract between Entra ID and the application. The app should receive the identity attributes it needs to make decisions, but no more. That usually means deciding whether the app needs user, group, tenant, or application context, then keeping the claim set as narrow as possible so tokens stay useful without becoming a data leak.

For most applications, the practical question is not whether claims can be added, but whether they should be. Claims that are harmless in a backend API can be risky in a browser-facing app, especially when tokens are logged, forwarded to other services, or exposed through diagnostics. The more claim data you embed, the more carefully you must treat downstream handling and retention.

Token claim design also affects interoperability. Applications often assume a specific claim name, format, or presence rule, so a change that looks small in Entra ID can alter authorisation decisions, session creation, or tenant-specific logic. That is why claim customisation should be treated as an application contract change, not just an identity portal setting.

Which claims should you include, and which should you avoid?

Start from the application’s actual decision points. If the app only needs to know who the caller is, a small identity set is usually enough. If it needs group-based decisions, think carefully about whether the app truly needs group membership in the token or whether it is better to resolve access server-side at runtime. If you include too much group or directory data, you increase token size and exposure without necessarily improving control quality.

Claims should also be evaluated by sensitivity. A claim that helps with routing or display logic may still reveal organisational structure, privilege shape, or relationship data. In mixed environments, that can matter as much as a direct secret exposure because tokens often move through logs, gateways, front-end code, and support tooling. The safest pattern is to include only claims the application can justify for an immediate control decision.

When applications depend on the claim set, test the full path after every change. That includes sign-in, token issuance, token validation, and the authorisation logic that consumes the claims. OAuth 2.0 and OpenID Connect Guide for Identity Teams is useful here because it frames claims inside the broader token and client model, which helps teams avoid treating token contents as a free-form data payload.

How do you change claims without breaking access decisions?

Use a staged change process. First identify the exact relying party and token type, then document what the application expects today, and only then adjust the token configuration. After that, validate with real user and service flows, not just a decoded sample token, because the important failure is usually a broken authorisation decision rather than a malformed token.

Be especially careful with applications that mix token claims and local policy. A claim may drive role assignment, tenant routing, or access to a downstream API, so a missing or renamed claim can produce either a hard failure or silent over-permissioning. That is why changes should be paired with regression testing of the authorisation path, not just identity issuance.

If your application uses microsoft entra id as part of a wider directory and privilege model, keep the claim design aligned with the rest of the environment. Active Directory and Entra ID Hardening Guide is relevant because claim choices often interact with group design, privileged roles, and hybrid identity assumptions. Where privileged access is involved, Privileged Identity Management (PIM) Guide helps anchor the difference between durable entitlement and time-bound activation.

Risk and Threat Considerations

Custom claims can increase exposure if they add unnecessary identity detail, group membership, or privilege context to tokens that are then logged, forwarded, cached, or replayed. The risk is not only disclosure, but also trust expansion, because downstream systems may start relying on claims that were never meant to be authoritative outside one application boundary.

Failure mechanism: Over-claiming or mis-scoping token contents can expose sensitive identity data and create false authorisation assumptions in downstream services, especially when tokens are reused beyond the original relying party.

Impact: An exposed or over-broad token can reveal more about the environment than intended, and a broken claim contract can deny legitimate users or grant access where the application no longer evaluates the right condition.

Practitioner Guidance

What to verify: Check the exact claim consumers before you change the token configuration. If the app validates roles, groups, or tenant context, confirm which claim it reads, whether it tolerates absence, and whether it treats the value as advisory or authoritative.

Decision rule: If the claim is only needed for display, analytics, or convenience, keep it out of the token and resolve it elsewhere. If the claim directly drives access or privilege decisions, include only the minimum required value and test the full authorisation path immediately after the change.

Common mistake: Teams often copy a working claim set from one application to another without checking whether the second app has the same trust boundary, logging behaviour, or downstream policy model. That is how harmless-looking claim changes become exposure or outage events.

Practitioner takeaway: Treat token claim customisation as a security-bound interface design task, not a cosmetic identity tweak, and optimise for the smallest claim set that still preserves correct authorisation.

Related resources from NHI Mgmt Group

• How do you restrict user consent to applications in Microsoft Entra ID?
• How do you review permissions granted to enterprise applications in Microsoft Entra ID?
• How do you configure access token lifetimes in Microsoft Entra ID?
• How do you configure OIDC single sign-on for applications in Microsoft Entra ID?