docs: WithClientClaims API design for NSP claims support#5982
Open
Robbie-Microsoft wants to merge 5 commits into
Open
docs: WithClientClaims API design for NSP claims support#5982Robbie-Microsoft wants to merge 5 commits into
Robbie-Microsoft wants to merge 5 commits into
Conversation
Captures the proposed approach for supporting client-originated claims (NSP/Network Security Perimeter) across MSIv1, MSIv2, cert-based, and FIC auth flows. Documents the current state of each flow, the gap in the existing WithClaims() API, and the design for a new WithClientClaims() API with proper cache keying. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
HarishRane
reviewed
May 6, 2026
HarishRane
reviewed
May 6, 2026
- Clarify that the new WithClientClaims(string) request-level API coexists without conflict with the existing obsolete app-level WithClientClaims (X509Certificate2, IDictionary) — different classes, different signatures - Add NSP SDK call-site code snippet showing claims sourced at request time, making the request-level design concrete and demonstrating why app-level placement would not support dynamic enforcement-mode changes - Add explanation of why per-request placement is correct: enforcement mode changes produce new claims; request-level avoids needing to recreate the app Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
trwalke
approved these changes
May 20, 2026
…pe restriction, and MSIv1 claim allowlist - Clarify CCA transport: WithClientClaims sends claims as ESTS request body parameter, NOT embedded in the client assertion JWT. This resolves Bogdan's concern. - Add Scope section: MIRP-gated, Redis Cache only, delegated identities only initially. - Add MSIv1 claim restriction: only xms_az_nwperimid is accepted; MSAL validates upfront to avoid opaque HTTP 400 from IMDS. - Add ETAs table: CCA done; MSIv1 (Raghu) canary by June 30; MSIv2 blocked on IMDS design. - Add E2E testing plan: Redis Cache team's help needed for MSI; existing test tenant for CCA. - Move resolved questions from Open Questions to a Resolved Questions table. - Update remaining open questions to only the two still unresolved items. - Add link to POC implementation PR #5999. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…cision Addresses Bogdan's feedback on PR #5982 + #5999: - Rename the proposed API throughout from `WithClientClaims` to `WithClaimsFromClient` (Bogdan's suggestion). The historical reference to the unrelated obsolete `ConfidentialClientApplicationBuilder.WithClientClaims(X509Certificate2, ...)` overload is left intact in the Naming Note for clarity. - Document the no-normalization design decision in Key Behaviors and add it to the Resolved Questions table. MSAL uses the raw claims string verbatim as part of the cache key. The application is responsible for passing a consistent string. Quote: "We will not penalize the 99% who already do that for the cost of normalizing for the 1% who would not." Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Design doc for
WithClaimsFromClient(string claimsJson)— a new per-request MSAL API that lets clients forward a JSON claims payload (e.g., NSPxms_az_nwperimid) to ESTS / IMDS. POC implementation in #5999.Latest update
WithClientClaims→WithClaimsFromClientthroughout, per Bogdan's suggestion. This avoids any clash with the obsoleteConfidentialClientApplicationBuilder.WithClientClaims(X509Certificate2, ...)overload. The historical reference to that obsolete API is preserved in the Naming Note for context.Resolved questions (now in the doc)
WithClaimsFromClientclaimsquery parameter, percent-encodedETAs (per Nidhi)
E2E testing
Open question — Nidhi confirming test environment availability with Redis Cache team. Likely requires a test VM with MSI inside an NSP; CCA path testable in existing MSAL test tenant.
Related