Docs: layered trust model for JWT validation#2850
Open
corinagum wants to merge 1 commit into
Open
Conversation
Documents the layered authentication model: the SDK validates inbound JWTs at the HTTP boundary, downstream handlers operate on already-validated tokens via typed accessors, and bots are responsible for authenticating custom surfaces (MCP, callbacks, webhooks). Resolves the documentation gap raised by security finding #6, which flagged the JsonWebToken accessor class for not performing signature verification. Verification is intentionally separated from the accessor; this page makes the architectural invariant explicit for SDK consumers.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new documentation page under Essentials → App Configuration explaining the SDK’s layered authentication/trust model for inbound JWTs, clarifying that signature/issuer/audience/lifetime checks happen at the HTTP boundary and downstream accessors are “validated-payload views”.
Changes:
- New “Trust Model” page documenting what
/api/messagesvalidates and what downstream code can assume. - Guidance on extending the same trust posture to custom HTTP surfaces (MCP/callbacks/webhooks) and anti-patterns to avoid.
Comment on lines
+1
to
+6
| --- | ||
| sidebar_position: 2 | ||
| title: Trust Model | ||
| summary: How the Teams SDK validates inbound tokens and what you can rely on downstream | ||
| languages: ['typescript','python','csharp'] | ||
| --- |
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
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
Adds a Trust Model page under Essentials → App Configuration documenting the layered authentication model the SDK uses for inbound JSON Web Tokens.
Why
A scanner flagged the SDK's
JsonWebTokenaccessor class because it does not perform signature verification at the point of token parsing. A cross-SDK audit confirmed this is intentional architecture: signature verification runs at the HTTP boundary (via the activity pipeline's token validator), and the accessor class is a typed view over already-validated payloads. Every consumer of decoded claims is downstream of a validator pass.This page makes the architectural invariant explicit for SDK consumers, reviewers, and future contributors.
What's covered
/api/messages(signature, issuer, audience, lifetime, algorithm)requireAuthhook recently added in Security hardening: MCP server auth teams.ts#540 / Security hardening: MCP server auth teams.net#448Build verified
npm run buildclean.Related PRs