Add token-validation and operational guidance to Entra SSO article - #117
Draft
ericsche wants to merge 5 commits into
Draft
Add token-validation and operational guidance to Entra SSO article#117ericsche wants to merge 5 commits into
ericsche wants to merge 5 commits into
Conversation
Backport hard-won SSO guidance to plugin-authentication-entra-sso.md: - Step 3: set requestedAccessTokenVersion=2 (v2.0 tokens) + issuer note. - Step 4: clarify the v2.0 audience is the client ID GUID (not the api:// URI); reject app-only tokens and require the delegated scope. - New subsection: how 401 vs 403 responses affect the sign-in experience (avoiding repeated sign-in prompts from audience mismatches). - New section: validate tokens with Azure App Service Easy Auth, including the allowed-client-applications gotcha and authN-vs-authZ scope. Add "idtyp" to cspell.json. markdownlint and cspell pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 11b3a75e-3ae3-4287-ac57-f082dd3ee24c
Address review feedback on the Entra SSO article: - Rewrite the Teams developer portal **Scope** field description: it's the delegated permissions Copilot requests and presents for consent (not just generic "OAuth scope values"), including downstream permissions for OBO. - Add "Access downstream APIs with the on-behalf-of flow" subsection: the SSO token is access_as_user for your API only; downstream access requires OBO; and consent needs the Scope declaration plus a 401 response, working together. - Remove the Azure App Service Easy Auth section - out of scope for this article. markdownlint and cspell pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 11b3a75e-3ae3-4287-ac57-f082dd3ee24c
Revise per review feedback to state the M365 Copilot SSO consent model crisply: - Scope field: frame it as requesting consent for the extra permissions the API needs to enable an on-behalf-of flow. - Add an IMPORTANT: SSO only issues access_as_user tokens; acquiring more privileged access is the API/MCP server's job via OBO; use Scope to declare the permissions and 401 to trigger a consent request. - 401/403 section: be explicit that a 401 from the API triggers a consent prompt, and that authentication/authorization failures should return 403 to avoid a repeating consent loop. - Clarify that the consent prompt only records consent - it does not change the access_as_user token that Copilot SSO issues; the retry uses the same token. markdownlint and cspell pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 11b3a75e-3ae3-4287-ac57-f082dd3ee24c
The note under identifierUris incorrectly described a display quirk. Replace it with the actionable guidance: the Expose an API UI can't configure multiple Application ID URIs; add the new URI in the Manifest section to keep existing ones. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 11b3a75e-3ae3-4287-ac57-f082dd3ee24c
Reword the "consent doesn't change the token" note: after consent, Copilot calls back your API/MCP server with the same access_as_user token, which the backend should use for an on-behalf-of request. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 11b3a75e-3ae3-4287-ac57-f082dd3ee24c
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
1 participant
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 token-validation and operational guidance to Configure Microsoft Entra SSO authentication (
docs/plugin-authentication-entra-sso.md). The article covers registration and wiring well, but stops short of the token-validation and runtime behavior that developers hit once their MCP server or API starts receiving Copilot SSO tokens. These additions fill that gap.What's added
requestedAccessTokenVersionto2(v2.0 tokens), with a note on the v2.0 vs v1.0 issuer format.audclaim is the app's client ID (a GUID), not theapi://Application ID URI; adds delegated-scope (scp) and app-only (idtyp) validation guidance.access_as_user) and doesn't grant downstream access; calling Microsoft Graph or another API requires OBO, and prompting the user for downstream consent requires both the Scope declaration and a 401 response.Provenance
Backported from hands-on experience building declarative-agent MCP servers with Entra SSO. The v2.0
aud/issclaims are verified against Access token claims reference; the OBO consent behavior aligns with the existing Microsoft Entra SSO consent isn't prompted troubleshooting guidance.Validation
markdownlint docs --config .markdownlint.jsonpasses.cspellpasses (addedidtyptocspell.json).Opened as a draft for maintainer review.