`AuthenticationRequiredError` drops the `claims` field from MSAL's `InteractionRequiredAuthError`, blocking OBO middle-tier claims propagation

[localden]

• Package Name: @azure/identity
• Package Version: 4.13.1 (latest stable; same code on main at 4.14.0-beta.4)
• Operating system: any
• nodejs version: any
• Is the bug related to documentation? no

When OnBehalfOfCredential.getToken() fails because Entra ID applies a Conditional Access policy at the OBO /token exchange, MSAL throws InteractionRequiredAuthError with a populated .claims field (the JSON the upstream client must send on its next /authorize to satisfy the policy). @azure/identity catches that error in msalClient.ts and runs it through handleMsalError, which wraps it in a fresh AuthenticationRequiredError({ scopes, getTokenOptions, message: error.message }). The .claims field is dropped and there is no cause chain, so the caller has no way to recover the directive.

This blocks the documented OBO Conditional Access pattern (docs): the middle-tier service is supposed to surface claims back to the calling client so the client can re-run interactive auth with ?claims=.... Without .claims on the thrown error, a middle-tier built on OnBehalfOfCredential can only show a generic "authentication required" failure.

To Reproduce

import { OnBehalfOfCredential } from "@azure/identity";

const cred = new OnBehalfOfCredential({
  tenantId, clientId, clientSecret,
  userAssertionToken: incomingAccessToken,
});

try {
  await cred.getToken(["https://graph.microsoft.com/.default"], { enableCae: true });
} catch (e) {
  // Tenant has "Require MFA for Office 365" CA policy.
  // MSAL threw InteractionRequiredAuthError with
  //   .claims = '{"access_token":{"capolids":{"essential":true,"values":["..."]}}}'
  // but e is AuthenticationRequiredError with only { scopes, getTokenOptions, message }.
  console.log((e as any).claims);  // undefined
  console.log((e as any).cause);   // undefined
}

Expected behavior

AuthenticationRequiredError should carry claims (or chain the original MSAL error via cause) so a middle-tier service can propagate the directive to its caller.

Relevant code

• msalClient.ts getTokenOnBehalfOf catch: catch (err: any) { throw handleMsalError(scopes, err, options); }
• utils.ts handleMsalError: InteractionRequiredAuthError has .name === "InteractionRequiredAuthError", which matches none of the checked names, so it falls through to return new AuthenticationRequiredError({ scopes, getTokenOptions, message: error.message }); claims and cause are not passed
• errors.ts AuthenticationRequiredError: options interface is { scopes, getTokenOptions?, message?, cause? }; cause is already supported but no claims field exists

Proposed fix

Either of these would work:

1. Add claims?: string to AuthenticationRequiredErrorOptions and AuthenticationRequiredError, and have handleMsalError pass claims: (error as InteractionRequiredAuthError).claims when present.
2. Pass cause: error to the AuthenticationRequiredError constructor (the class already accepts options.cause, handleMsalError just doesn't supply it). Callers can then read (e.cause as InteractionRequiredAuthError).claims.

Additional context

The SDK already supports the resource-server side of CAE (#31501 in bearerTokenAuthenticationPolicy, and getToken({ claims, enableCae }) forwarding in msalClient.ts). This issue is specifically the authorization-server side: surfacing claims when the credential's own /token call fails. Workaround today is to bypass @azure/identity and use @azure/msal-node ConfidentialClientApplication.acquireTokenOnBehalfOf directly, which throws the InteractionRequiredAuthError raw, but that loses the IdentityClient retry policy.

[github-actions]

🎯 Agentic Issue Triage

Summary: AuthenticationRequiredError silently drops the .claims field from MSAL's InteractionRequiredAuthError when OnBehalfOfCredential.getToken() fails due to a Conditional Access policy, preventing OBO middle-tier services from propagating the claims challenge back to the calling client.

📋 Issue Details

Package: @azure/identity v4.13.1 (also reproduced on main at 4.14.0-beta.4)
Affected API: OnBehalfOfCredential.getToken() → handleMsalError() in msalClient.ts / utils.ts
Scenarios:

• OBO credential fails because Entra ID Conditional Access policy (e.g., "Require MFA") applies to the /token exchange
• MSAL throws InteractionRequiredAuthError with a populated .claims field containing the CAE/CA challenge JSON
• handleMsalError wraps this into AuthenticationRequiredError but discards .claims and does not set cause
• Middle-tier service has no way to surface the claims challenge to its upstream caller

Root ask: AuthenticationRequiredError should expose claims (either as a first-class field or via cause) so middle-tier services using OnBehalfOfCredential can implement the documented OBO Conditional Access pattern.

🔎 Debugging / Reproduction Notes

The issue is well-localized by the reporter. The flow is:

1. OnBehalfOfCredential.getToken() → msalClient.ts getTokenOnBehalfOf()
2. MSAL call throws InteractionRequiredAuthError with .claims populated
3. catch (err: any) { throw handleMsalError(scopes, err, options); } in msalClient.ts
4. handleMsalError in utils.ts checks error.name against a list; InteractionRequiredAuthError doesn't match any case, so falls through to return new AuthenticationRequiredError({ scopes, getTokenOptions, message: error.message }) — .claims and cause are not forwarded

Suggested investigation steps:

1. Confirm InteractionRequiredAuthError name value in @azure/msal-node to ensure the name check in handleMsalError could be extended or that the fallthrough path is the right place to fix
2. Evaluate Option 1 (add claims?: string to AuthenticationRequiredErrorOptions and pass it from handleMsalError) vs Option 2 (pass cause: error unconditionally, letting callers read .cause.claims) for API surface impact and semver implications
3. Check if the same issue affects other OBO-style flows (e.g., AzureApplicationCredential delegation scenarios) that also route through handleMsalError
4. Verify that adding claims to AuthenticationRequiredError does not conflict with the existing getToken({ claims }) input path used on the resource-server side (CAE support added in [Core] Add CAE Support #31501)
5. Add a unit test simulating InteractionRequiredAuthError with .claims and assert the field survives through handleMsalError and is accessible on the thrown AuthenticationRequiredError

🏷️ Label Confidence

• Category: Client — @azure/identity is a client-plane library under sdk/identity/, not a management (arm-) package
• Service: Azure.Identity — the issue explicitly names @azure/identity and references files in sdk/identity/identity/src/
• Confidence: High — single unambiguous package named in the issue, category is clear, service matches the well-known Azure.Identity label

👥 Owner Routing

• Matched CODEOWNERS entry: # ServiceLabel: %Azure.Identity (line 95) — only %Azure.Identity is required and the issue's predicted service label matches directly
• AzureSdkOwners: @KarishmaGhiya, @maorleger, @minhanh-phan
• ServiceOwners: none listed
• Routing action: Assigned @maorleger (randomly selected from 3 AzureSdkOwners); added needs-team-attention label (issue is customer-reported); @mentioned all three AzureSdkOwners in routing comment
• Scan notes: Scanned from end of file upward. No %Azure.Identity %Service Attention multi-label override entry was found later in the file. First match was the %Azure.Identity entry at line 95.

Generated by Agentic Triage for issue #38707 · ● 4.5M · ◷

[github-actions]

Thank you for your feedback. Tagging and routing to the team member(s) best able to assist.

//cc: @KarishmaGhiya @maorleger @minhanh-phan

[minhanh-phan]

Hi @localden, thank you for raising this issue. I can confirm I can reproduce this issue and will get back to you soon when we have a fix out! Thank you for your patience.