Custom SSO Claims with Entra ID Directory Extensions: A Five-Step Guide

Microsoft’s recent how‑to on issuing custom SSO claims from Entra ID using directory extension attributes gives administrators a practical, low‑friction way to inject organization‑specific data into SAML and OIDC tokens — and to do so only for selected user groups during sign‑in. The documented flow walks through registering extension attributes with Microsoft Graph, assigning values to user objects, mapping those directory extensions as claims on an Enterprise Application, and validating the result with a test sign‑in (for example, using jwt.ms). This approach lets IT teams deliver targeted identifiers (things like sponsorship or partner IDs, regional tags, or entitlement flags) directly to relying parties without adding that data to every user’s base profile or exposing it to users outside the intended audience. (learn.microsoft.com) (learn.microsoft.com)

Background​

What are directory extension attributes?​

Directory extension attributes (sometimes called directory extensions or extension properties) are tenant‑scoped, application‑owned attributes you define through Microsoft Graph and attach to supported directory objects (notably users). Once defined, these attributes are discoverable, strongly typed, and can be read or written by authorized applications in the tenant. The attribute names follow a canonical format — an owner application identifier plus the attribute name — so they’re easy to reference in token configuration or Graph queries. (learn.microsoft.com)
Directory extensions differ from the older set of extension attributes often exposed by on‑premises AD; they are created and managed explicitly by an owner app registration and are intended to be filterable and programmatic across the directory. They’re also one of the supported mechanisms for getting custom data into issued tokens. (learn.microsoft.com)

Why use extension attributes for claims?​

Using directory extension attributes to surface custom claims has three primary advantages:

• Precision: Emit the custom claim only for users who meet conditions (for example, membership of a specific group).
• Separation of concerns: Keep custom data attached to an application owner rather than mixing it into core directory schema for all apps.
• Programmatic control: Set and update values through Microsoft Graph, which makes bulk changes and automation straightforward. (learn.microsoft.com)

That said, injecting claims into tokens is a security‑sensitive operation. Microsoft requires specific controls and provides safeguards (including the acceptMappedClaims manifest flag and guidance about multi‑tenant risks) to reduce the chance of token tampering or abuse. These controls should be understood before adopting claims mapping broadly. (github.com)

---

Overview of Microsoft’s recommended five‑step method​

Microsoft’s published sequence — register extension attributes, assign values to users, create claims in the Enterprise Application with group conditions, optionally update the app manifest to accept mapped claims, and test the configuration — is a pragmatic recipe that works for both SAML and OIDC flows. Each step maps directly to supported Graph or Entra portal actions, and the pattern is repeatable for multiple attributes or groups. The approach emphasizes scoping (attributes owned by a single app) and conditional emission (claims only for specified groups), which are good security and governance practices. (learn.microsoft.com)
Below is a verified, field‑tested walkthrough that refines Microsoft’s guidance with practical notes, caveats, and alternative options for larger estates.

Step‑by‑step: create and use directory extension attributes​

1. Register directory extension attributes via Microsoft Graph​

Microsoft recommends creating extension properties on an application object using the Graph API endpoint:
POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties[/url]
Request body (JSON example):
{
"name": "sponsorid1",
"dataType": "String",
"targetObjects": ["User"]
}
When created, Graph returns an attribute name in the canonical format:
extension<AppClientID><attributeName>
This exact returned name is what you must reference later when mapping claims or writing to user objects. The Graph documentation includes this request and response pattern and the naming convention. (learn.microsoft.com)
Practical tips

• Required permission: your caller must have Application.ReadWrite.All or equivalent application permissions to create extension definitions on behalf of the app owner.
• Attribute limits: observe the service limits (for example, how many extension definitions an owner can create) and plan attribute naming to avoid collisions.
• Ownership: the extension is tied to the application object (ObjectId) that created it; keep track of app ownership to prevent orphaned extensions.

2. Assign values to user objects​

Once the directory extension property exists, write its value into the user object using Graph — typically a PATCH to the user resource:
PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId[/url]}
Request body:
{
"extension_<AppClientID>_sponsorid1": "ABC123"
}
You can set values during user creation or update existing users in bulk with Graph scripts or automation tooling. If your environment synchronizes attributes from on‑prem AD via Entra Connect, make sure the attribute sync rules are compatible and that you don’t inadvertently overwrite directory extension values during sync cycles. (learn.microsoft.com, dev.to)
Operational considerations

• Bulk updates: use batching or automation tooling to avoid throttling. Update operations are subject to Graph API rate limits.
• On‑prem sync: extension properties can be populated from on‑prem sources, but synchronization must be configured correctly and is subject to service constraints.

3. Create claims in the Enterprise Application (Attributes & Claims)​

In the Entra admin center, open the Enterprise Application for the relying party and go to Single Sign‑On > Attributes & Claims. Add a new claim; when configuring the claim:

• Provide a friendly name for the claim (for example, sponsorClaim1).
• Under Claim conditions, set the user type and — critically — the group(s) that should receive this claim.
• For Source attribute, select the directory extension attribute (the extension<AppClientID>... name).

This step creates the conditional mapping so only members of the selected group receive the claim during sign‑in. The portal’s UI supports conditional logic and basic transformations (ToLower/ToUpper, ExtractMailPrefix, and a few more), and the order of condition evaluation matters for repeatable decision logic. (learn.microsoft.com)
Best practices for mapping

• Limit groups per claim: the portal allows up to 50 unique groups across all claims for a given application; design mappings to stay within limits.
• Test with Edge cases: verify for guest users and external accounts if those scenarios apply; the portal’s user‑type conditions let you treat guests differently from members. (learn.microsoft.com)

4. Handling the “Application requires custom signing key to customize claims” error​

Some tenants encounter an error when mapping claims that indicates the application requires a custom signing key to customize claims. Microsoft documents a workaround for single‑tenant applications: update the app registration manifest and set the property:
"acceptMappedClaims": true
Setting this flag allows the app to accept claims that have been mapped by Entra ID without requiring a custom signing certificate. The docs also warn not to set this property to true for multi‑tenant apps because it increases the attack surface: a malicious tenant could create claims‑mapping policies targeting your app. Always assess tenancy model and risk before using this manifest change. (github.com)
Caveats and security risks

• Multi‑tenant risk: do not set acceptMappedClaims=true for applications exposed to multiple tenants. Microsoft explicitly warns about this scenario.
• Token audience and manifest constraints: acceptMappedClaims has rules about token audience and verified domains; if these conditions aren’t satisfied Entra will reject mapped claims requests. Validate your Application ID URI and audience configuration. (github.com)

5. Test the configuration (jwt.ms or equivalent)​

To validate the flow, initiate an interactive sign‑in for a user who is a member of the targeted group. A canonical test URL for OIDC id_token issuance looks like this:
https://login.microsoftonline.com/(Tenant ID)/oauth2/v2.0/authorize?client_id=(Client ID)&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
After sign‑in, jwt.ms will display the decoded token; you should see the custom claim (for example sponsorClaim1) populated with the extension value for users in the defined group. Users who are not in any of the configured groups should not receive the sponsor claim. Microsoft’s guidance specifically cites jwt.ms as a safe test harness because token contents never leave the browser. (learn.microsoft.com)
Testing checklist

• Test both SAML and OIDC if the application supports both protocols.
• Check tokens for correct claim names and values and ensure their presence only for targeted group members.
• Validate token signing and audience fields after enabling claim mapping; tokens must still validate against the relying party’s expectations.

---

Practical examples and common pitfalls​

Example: two sponsor claims for two groups​

A common enterprise requirement is to issue different sponsorship identifiers for two partner groups.

• Register two extension properties on your owner app: sponsorid1, sponsorid2. The Graph response will produce names similar to extension_0123456789abcdef_sponsorid1.
• Patch user objects for Group A members with extension_0123..._sponsorid1 = "SPONSOR_A".
• Patch Group B members with the sponsorid2 extension set.
• In the Enterprise Application, add claim sponsorClaim1 sourced from the sponsorid1 extension for Group A; add sponsorClaim2 from sponsorid2 for Group B.
• Test sign‑ins for each group and a control user not in either group.

This pattern keeps values isolated and avoids overloading a single extension with multi‑purpose semantics. (learn.microsoft.com)

Pitfalls to avoid​

• Using the wrong extension name: always use the exact returned extension_<AppClientID>_name string from Graph; typos will silently fail to map.
• Forgetting permissions: creating extensions and writing user attributes requires appropriate Graph permissions. Running interactive portal steps won’t substitute for missing application permissions when using automated scripts.
• Failing to plan for lifecycle: who owns the app that defines the extension? If that app is deleted, the extension definitions are lost. Establish a lifecycle policy for owner registrations.
• Overexposing claims: avoid adding sensitive PII to tokens unless absolutely necessary; tokens are often logged or captured in transit, and some endpoints store token data in logs. Use conditional emission to reduce exposure. (learn.microsoft.com)

---

Security and governance analysis​

Strengths of Microsoft’s approach​

• Granular scoping: directory extensions are tied to an owner app, which reduces the chance of accidental global schema changes.
• Conditional claim emission: claim conditions (by group and user type) enable precise control over who receives what data at sign‑in.
• Standards compatibility: the mapping works for both SAML and OIDC tokens and integrates with existing enterprise SSO deployments without custom middleware.
• Graph automation: all attribute registration and user updates can be automated, supporting large‑scale provisioning and change management. (learn.microsoft.com)

Risks and mitigations​

• AcceptMappedClaims risk: setting acceptMappedClaims=true makes the application trust that Entra‑issued claims may have been modified; for multi‑tenant apps this can be dangerous. Mitigation: restrict this change to single‑tenant apps and document the decision lifecycle. (github.com)
• Token exposure: tokens frequently traverse network flows and are sometimes logged in applications or security tooling. Mitigation: avoid placing high‑sensitivity PII or long‑lived secrets in tokens; prefer an internal identifier that the application can map to sensitive data via a secured API call.
• Ownership drift: if the application that owns the extension is removed or its credentials rotated improperly, the extension definition could become unusable. Mitigation: assign ownership to a managed service principal with documented admin controls and recovery steps.
• Auditing blind spots: injecting claims increases the complexity of audits. Mitigation: log claim mapping changes, track which policies emit claims, and ensure sign‑in logs are retained for forensic review. (github.com)

---

Advanced scenarios and alternatives​

Using claims mapping policies (PowerShell / Graph)​

For enterprise scenarios that need programmatic control beyond the portal UI, claims mapping policies can be created and assigned to ServicePrincipals via Graph or PowerShell. This is especially useful when conditional logic needs to be expressed more precisely or when you want to manage policies as code. Community examples and Microsoft’s guidance show how to create and attach ClaimsMappingPolicy objects and how to reference extension properties in the policy schema. Note that policy assignment semantics and propagation must be validated in test tenants. (blogs.aaddevsup.xyz, stackoverflow.com)

Custom claims providers and enrichment​

If your claim values must be retrieved at sign‑in time from an external system (for example, a purchasing system that holds sponsorship assignments), Microsoft supports custom claims providers that call out to an enrichment API at token issuance time. This enables dynamic claims that aren’t stored in the directory but are fetched on demand, which is useful for frequently changing attributes. These flows require additional configuration and testing, and you must ensure the custom provider is resilient and secure. (learn.microsoft.com)

Schema extensions vs directory extensions​

If you need tenant‑level attributes that multiple apps own or share, consider schema extensions instead of directory extension properties tied to a single app. Schema extensions are a different model with different constraints; choose based on reuse requirements and lifecycle expectations. Microsoft’s Graph extensibility overview compares these approaches and provides guidance on which to use. (learn.microsoft.com)

---

Implementation checklist for IT teams​

• Inventory: identify apps that need custom claims and define required attributes and groups.
• Ownership: create or designate an app registration to own the extension schema; lock down its credentials and administrative access.
• Permissions: grant appropriate Graph API permissions for extension creation and user updates.
• Naming policy: adopt an attribute naming convention and document the extension_<AppClientID>_name strings.
• Provisioning: implement bulk set/update scripts for user extension attributes with retry and throttling awareness.
• Portal mapping: configure Attributes & Claims for the Enterprise Application and verify claim conditions and order.
• Manifest validation: evaluate the need for acceptMappedClaims and only enable it for single‑tenant, controlled apps; document the risk assessment.
• Testing: use jwt.ms or equivalent test apps to validate tokens for members and non‑members; test SAML assertions too.
• Monitoring: ensure token issuance and sign‑in logs are collected and retained for incident response.

---

Final assessment​

Microsoft’s documented process for issuing custom SSO claims via Entra ID and directory extension attributes is a pragmatic, supported mechanism for delivering targeted identity payloads to applications. It balances flexibility with governance controls: attributes are owned by an application, claims are emitted only when conditions are met, and Microsoft provides manifest safeguards to reduce abuse risk. For most organizations the pattern will be a sound way to deliver app‑specific identifiers without complicating the base user schema.
However, the approach is not risk‑free. The most important operational hazards are the misuse of acceptMappedClaims in a multi‑tenant context, accidental exposure of sensitive data in tokens, and lifecycle/ownership failures around the app that defines the extensions. With careful design — including minimal claim contents, single‑tenant scope where applicable, secure ownership practices, and robust testing — these risks are manageable.
For teams planning to adopt this pattern, the immediate next steps are:

• Prototype the flow in a test tenant (register extensions, patch test users, map claims, test with jwt.ms).
• Run an internal security review on the attributes to be emitted and the tenant/app tenancy model.
• Document and automate the provisioning and lifecycle controls for the owning application.

The technique fills a clear need for many enterprises: injecting targeted, verifiable identity data into SSO tokens while retaining control over who sees it. When implemented with the documented safeguards and operational hygiene described above, it is a powerful tool in the Entra ID toolkit. (learn.microsoft.com, github.com)

---

Source: Windows Report Microsoft explains how to issue custom SSO claims in Entra ID using directory extension attributes