Microsoft has outlined a practical, five-step method for issuing custom SAML and OIDC claims from Entra ID, using directory extension attributes to inject organization-specific data like sponsor IDs or regional tags directly into tokens—and only for selected user groups during sign-in. The approach, recently spotlighted by the company's documentation and community walkthroughs, gives administrators a low-friction way to deliver targeted identifiers to relying parties without polluting every user's base profile or exposing values to unintended audiences.

Why Directory Extensions for Custom Claims?

Directory extension attributes—sometimes called Microsoft Entra ID extensions—are tenant-scoped, application-owned properties defined through Microsoft Graph. Unlike the older on-premises sync-driven extension attributes (attributes 1-15), these extensions are strongly typed, filterable, and explicitly registered against an owner app. Once created, an authorized application can read or write extension values on supported directory objects, primarily users.

The canonical naming scheme—extension_{AppClientId-without-hyphens}_{extensionName}—makes them straightforward to reference in Graph queries or token claim mappings. Microsoft's extensibility documentation emphasises that directory extensions are one of the supported mechanisms for getting custom data into issued tokens, alongside schema extensions and custom claims providers.

Using directory extensions for claims offers three clear advantages:
- Precision: You can scope claim emission to users who meet specific conditions, such as membership of a particular group, so that only the right people ever see the injected data.
- Separation of concerns: Custom data lives under the owning application, rather than being mixed into the core directory schema for all apps. This prevents schema bloat and reduces accidental exposure.
- Programmatic control: Values can be set and updated via Microsoft Graph, making bulk changes and automation straightforward. You can integrate provisioning scripts, HR feeds, or on-prem sync processes with appropriate Graph permissions.

However, injecting claims into tokens is a security-sensitive operation. Microsoft requires specific controls, including the acceptMappedClaims manifest flag, and provides warnings about multi-tenant risks. Before rolling out claims mapping broadly, teams must understand these safeguards.

The Five-Step Method: A Verified Walkthrough

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 with a tool like jwt.ms—works for both SAML and OIDC flows. Each step maps to supported Graph or Entra portal actions, and the pattern is repeatable for multiple attributes or groups. Below is a refined, field-tested version with practical notes and pitfalls.

Step 1: Register Directory Extension Attributes via Microsoft Graph

First, create an extension property on the application object that will own it. Send a POST request to:

POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties

With a JSON body like:

{
  "name": "sponsorid1",
  "dataType": "String",
  "targetObjects": ["User"]
}

Microsoft Graph returns the full canonical name (e.g., extension_0123456789abcdef_sponsorid1). You must record this exact string because you'll need it when writing data to users and mapping claims. The caller needs Application.ReadWrite.All or equivalent application permissions. Note that there is a limit on the number of extension definitions an owner app can create, so plan naming carefully and avoid collisions.

Step 2: Assign Values to User Objects

Once the extension exists, write the desired value onto user objects using a PATCH request:

PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}

{
  "extension_0123456789abcdef_sponsorid1": "ABC123"
}

You can set values at user creation or update them in bulk. If your environment synchronises attributes from on-premises Active Directory via Entra Connect, verify that sync rules won't overwrite directory extension values during a sync cycle. Bulk updates should use batching or automation tooling to avoid Graph API throttling.

Step 3: Create Claims in the Enterprise Application

Navigate to the Entra admin center, open the Enterprise Application for your relying party, and go to Single Sign-On > Attributes & Claims. Add a new claim with a friendly name (e.g., sponsorClaim1).

  • Under Claim conditions, set the user type and—critically—the group(s) that should receive this claim. This conditional emission is what keeps claims targeted.
  • For Source attribute, select the directory extension attribute (the full extension_... name).

The portal supports basic transformations (ToLower/ToUpper, ExtractMailPrefix) and allows up to 50 unique groups across all claims for a single application. Design your mappings to stay within this limit, and test edge cases like guest users.

Step 4: Handling the "Custom Signing Key Required" Error

Some tenants encounter an error stating the application requires a custom signing key to customize claims. For single-tenant applications only, Microsoft documents a workaround: update the app registration manifest and set:

"acceptMappedClaims": true

This flag tells Entra ID that the app accepts claims that have been mapped without requiring a custom signing certificate. Do not set this property for multi-tenant apps, as it increases the attack surface: a malicious tenant could create claims-mapping policies that target your app. Microsoft explicitly warns about this risk in its documentation.

Step 5: Test the Configuration with jwt.ms

For OIDC flows, use a test URL like:

https://login.microsoftonline.com/{TenantId}/oauth2/v2.0/authorize?client_id={ClientId}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

After sign-in, jwt.ms decodes the token locally in the browser. Check that the custom claim appears—and with the correct value—only for users in the targeted group. Users outside the group should see no such claim. Also validate the token's signature and audience fields to ensure it still meets the relying party's expectations. For SAML applications, repeat the test using a SAML tracer or similar tool.

Common Pitfalls and How to Avoid Them

  • Using the wrong extension name: A single typo in the extension_... string will silently break claim mapping. Always copy the exact name from the Graph response.
  • Missing permissions: Automating extension registration or user updates requires proper Graph permissions. Interactive portal steps won't substitute for missing scopes in scripts.
  • Lifecycle ownership: If the application that owns the extension is deleted, the definitions are lost and data becomes undiscoverable. Establish a managed service principal with documented ownership and recovery procedures.
  • Overexposing sensitive data: Tokens often traverse networks and may be logged. Inject only internal identifiers, not raw PII. The application can then fetch sensitive details via a secured API call using that identifier.
  • Group limit violations: Remember the portal limit of 50 unique groups per app across all claims. Plan your conditional logic accordingly, or explore claims mapping policies for more complex scenarios.

Real-World Example: Two Sponsor Claims for Two Groups

A typical enterprise scenario: issue different sponsor identifiers for two partner groups.

  1. Register two extension properties on your owner app: sponsorid1 and sponsorid2. Graph returns names like extension_0123..._sponsorid1 and extension_0123..._sponsorid2.
  2. Patch user objects in Group A with extension_0123..._sponsorid1 = "SPONSOR_A".
  3. Patch Group B members with sponsorid2 = "SPONSOR_B".
  4. In the Enterprise Application, add claim sponsorClaim1 sourced from sponsorid1 for Group A, and sponsorClaim2 from sponsorid2 for Group B.
  5. Test with a member of each group and a control user who belongs to neither. Only the correct claims should appear.

This pattern keeps values isolated and avoids overloading a single extension with multi-purpose semantics.

Security and Governance: Balancing Flexibility with Control

Microsoft's approach offers several strengths:

  • Granular scoping: Directory extensions are owned by an app, reducing the risk of accidental global schema changes.
  • Conditional emission: Group and user-type conditions allow 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 SSO deployments.
  • Automation readiness: All operations can be scripted via Graph, supporting large-scale provisioning and change management.

But risks remain:

  • acceptMappedClaims abuse: Setting this flag for multi-tenant apps can open a door for malicious tenants. Mitigation: strictly limit it to single-tenant apps and document the decision.
  • Token exposure: Injected claims travel with the token and may be stored in logs. Mitigation: avoid secrets and high-sensitivity PII; use internal identifiers that the application resolves server-side.
  • Ownership drift: If the owner app is removed or its credentials rotated improperly, the extension definition can become unusable. Mitigation: assign ownership to a managed service principal with admin controls.
  • Auditing complexity: More claim mappings mean additional audit surface. Mitigation: log claim mapping changes, track which policies emit claims, and retain sign-in logs for forensic review.

Advanced Scenarios and Alternatives

For enterprises that need more than the portal UI offers, claims mapping policies can be created and assigned to service principals via Graph or PowerShell. This allows you to manage policies as code and express more intricate conditional logic. Community examples show how to create ClaimsMappingPolicy objects that reference extension properties.

If claim values must be fetched at sign-in time from an external system (like a procurement database), Microsoft supports custom claims providers that call out to an enrichment API during token issuance. This dynamic approach avoids storing transient data in the directory, but requires additional infrastructure and careful resiliency planning.

When multiple apps need to share custom attributes across the tenant, consider schema extensions instead of directory extensions. Schema extensions are not tied to a single owner app and can be made available across tenants, but they lack the same token-claims integration that directory extensions natively provide. Choose based on your reuse requirements and the need for token injection.

Implementation Checklist for IT Teams

  • Inventory: Identify apps that need custom claims and define required attributes and groups.
  • Ownership: Designate an app registration to own the extension schema, and secure its credentials.
  • Permissions: Grant Graph API permissions for extension creation and user updates.
  • Naming policy: Adopt a naming convention and document every extension_... string.
  • Provisioning: Implement bulk scripts with retry logic and throttling awareness.
  • Portal mapping: Configure claims with conditions and verify the order of evaluation.
  • Manifest validation: Evaluate acceptMappedClaims only for single-tenant, controlled apps; document the risk assessment.
  • Testing: Use jwt.ms for OIDC and a SAML tracer for SAML; validate token signing and audience.
  • Monitoring: Ensure token issuance and sign-in logs are collected for incident response.

Bottom Line

Microsoft's documented process for issuing custom SSO claims via Entra ID and directory extension attributes is a robust, supported mechanism for delivering targeted identity payloads to applications. It balances flexibility with governance: attributes are owned by an app, claims are emitted only when conditions are met, and safeguards like acceptMappedClaims warnings help contain risk.

The technique fills a clear need in many enterprises—injecting verifiable, app-specific identifiers into tokens without bloating the directory schema or exposing data broadly. When implemented with the hygiene described here, it becomes a powerful addition to the Entra ID toolkit. The immediate next steps for any team are to prototype the flow in a test tenant, run a security review on the attributes to be emitted, and document ownership and lifecycle controls for the owning application. With those measures, organizations can confidently roll out custom claims to their SSO ecosystem.