Add sso-setup-typescript plugin (Entra SSO for ui-widget agents) + expand authentication.md

[nayanaramakanth]

Summary

Adds a setup-sso-ui-widget skill to the microsoft-365-agents-toolkit plugin: one-command Microsoft Entra SSO (single sign-on, no OBO) for a Microsoft 365 Copilot declarative agent whose tools are served by an MCP server. It supports both widget standards — MCP Apps (Express) and OAI Apps (raw-http) — and defaults to MCP Apps. Also expands declarative-agent-developer/references/authentication.md and adds an SSO hand-off to ui-widget-developer.

What's included

New skill — setup-sso-ui-widget/

• scripts/*.ps1 (14) — the phases as real, testable PowerShell (detect → register Entra app → ATK OAuth → wire manifest → inject guard → write env → build/sideload → verify 401 → cleanup), plus resync-tunnel-url.ps1 and _lib.ps1. The .md files invoke the scripts (deterministic — works well with smaller models, not just Opus).
• references/ — wire-and-guard.md, detect-and-inputs.md, register-app.md, build-verify-cleanup.md, auth.ts (hardened JWKS guard), sso-explained.md (token-flow deep dive).

Dual-layout support

• Auto-detects the layout: MCP Apps (readiness_plugin.json + Express main.ts) vs OAI Apps (mcpPlugin.json + raw-http). Defaults to MCP Apps when ambiguous.
• Patches the resolved manifest's runtimes[] auth → OAuthPluginVault (filename-agnostic).
• Injects the same hardened auth.ts guard, wired per layout: an Express middleware for MCP Apps, or a raw-http handler edit for OAI Apps (no express-jwt, no server rewrite).

Updated

• ui-widget-developer/SKILL.md — required "Add SSO" hand-off at completion.
• declarative-agent-developer/references/authentication.md — expanded from OAuth-only to a full auth guide (Entra SSO S1–S6, auth-pattern chooser, 401-vs-403 consent-UX guidance).

Security

Single-tenant JWKS bearer-token guard: validates signature / aud / iss / exp via jose, and additionally enforces scp = access_as_user, tenant match, and rejects app-only tokens. Accepts every aud form Entra emits (bare client-id GUID + api://…) to avoid the endless consent loop, while still rejecting tokens minted for a different app. Includes an Azure Easy Auth deployment note (the custom guard is for local dev).

Tunnel resilience

Reuses the existing named devtunnel (never creates a second). If the tunnel URL later changes, resync-tunnel-url.ps1 (+ a Phase-2 drift check) re-aligns the OAuth base URL / App ID URI so auth doesn't break.

Tenant handling

No hardcoded tenant IDs or internal portals. Defaults to the standard single-tenant registration; managed-enterprise steps (--service-management-reference, co-owners, admin-consent portal) trigger reactively only if app creation requires them.

Testing

Validated on a public Microsoft Entra tenant across both layouts:

• OAI Apps / raw-http — detect + wire + guard in src/ + 401 enforcement.
• MCP Apps / Express — detect + wire + guard at root + 401 + valid Copilot SSO tokens accepted ([auth] Valid SSO token accepted).

Notes

• SSO only (no OBO). For Microsoft Graph / downstream APIs, a separate OBO flow is out of scope.
• Gap (toolkit, not this skill): create-mcp-app emits a standalone MCP server with no M365 agent wrapping; this skill assumes the project is already wrapped as a declarative agent. A clean "create-mcp-app → M365 agent" wrap step is a follow-up.
• Copilot tool selection (match vs execute) is orchestration/model-dependent — independent of SSO wiring.

[sebastienlevert]

Thorough review — sso-setup-typescript + expanded authentication.md

Nice work — this is a genuinely useful, well-documented plugin, and the write-ups (sso-explained.md, the expanded authentication.md) are excellent. I reviewed the full diff in depth and cross-checked with multiple models (a security-focused pass and a correctness/library pass) to reduce blind spots. Findings are grouped by severity; the security items in the injected auth.ts guard are the ones I'd want addressed before this leaves draft.

I've also included the explicit duplication verdict that was requested.

---

🔴 Security (the injected auth.ts is the only runtime enforcement — worth scrutiny)

1. [High] The token guard never validates scp / rejects app‑only tokens.
setup-sso-ui-widget/SKILL.md → Phase 7a validateBearerToken calls jwtVerify with only { audience, issuer, algorithms }. It verifies signature/aud/iss/exp but does not check that scp contains access_as_user, nor does it distinguish delegated vs app‑only tokens. sso-explained.md §3 itself states "scp must contain access_as_user" — but the code doesn't enforce it. Any token minted for this app's audience (including a client‑credentials token with roles/no scp) would be accepted, and downstream tools reading claims.oid would get undefined.
Fix: after jwtVerify, assert String(payload.scp ?? "").split(" ").includes("access_as_user") (and optionally reject idtyp: "app"), throwing otherwise.

2. [High] Multi‑tenant registration vs single‑tenant issuer pinning.
The shared entra-app-registration.md offers AzureADMultipleOrgs, but auth.ts hard‑pins both the JWKS URL and issuer allowlist to a single TENANT_ID (https://login.microsoftonline.com/${tenantId}/v2.0). A user from any other tenant would present iss = .../<theirTenant>/v2.0 and get a 401 → the exact endless sign‑in loop the docs warn about.
Fix: either force single‑tenant for the SSO path, or implement tid‑aware issuer validation (validate iss matches .../<payload.tid>/v2.0) with the appropriate common/organizations JWKS strategy. At minimum, document that this skill only supports single‑tenant.

3. [Medium] Base setup-sso skill — "validation illusion".
Unlike the ui‑widget skill (which injects a jose guard), the base setup-sso skill only checks that express-jwt is a dependency (Phase 0) and writes .env audience values (Phase 7c). It never inspects or injects the actual /mcp auth middleware. So SSO can be fully "configured" on the Copilot side while the server still accepts unauthenticated requests if the template's middleware is missing/misconfigured. The Phase 9 401 probe only runs for local MCP backends and merely prints a warning.
Fix: inject/verify route protection deterministically (as the ui‑widget path does), or hard‑gate success on the 401 probe with an explicit failure rather than a soft warning.

4. [Medium] Auth error text leaked to the caller.
Phase 7b returns "Authentication failed: " + (err as Error).message to the client, exposing verifier internals (e.g. "unexpected audience", key‑id issues).
Fix: return a generic 401 message to the caller; log the detailed reason server‑side only.

5. [Low] Accepting the bare client‑id GUID aud is fine — once #1 lands. The [clientId, api://clientId, appIdUri] audience list is the correct workaround for real Copilot tokens and is safe because the issuer is tenant‑scoped. I only flag it to note it must be paired with the scp check (#1) so audience acceptance isn't the only gate.

6. [Low] v1 issuer accepted despite requiring v2 tokens. auth.ts also allows https://sts.windows.net/${tenantId}/, but S5 / requestedAccessTokenVersion=2 guarantees v2 tokens. Dropping the v1 issuer tightens the surface without cost.

7. [Low] Least privilege — User.Read + admin consent added unconditionally. entra-app-update.md Step 4 always adds Graph User.Read and requests admin consent, even though pure SSO identity validation (no OBO) needs no Graph permission. Consider making the Graph permission opt‑in for the downstream/OBO case.

8. [Nit] Claims logged on every call. console.log("[auth] Valid SSO token accepted:", { sid, aud, tid, iss }) logs identifiers on each request. Fine as a dev proof signal (and it's not the raw token), but worth a note to gate/remove for production.

---

📚 Common‑library usage

• jose is used correctly and idiomatically — createRemoteJWKSet (with key caching, so no per‑request Entra call) + jwtVerify with explicit algorithms: ["RS256"] (good — blocks alg‑confusion/none). ✅
• AsyncLocalStorage (claimsStore) is the right pattern for per‑request identity and correctly avoids the cross‑request leakage a module‑level global would cause. The lazy ensureConfig() note (avoiding a top‑level process.env read before dotenv loads) is a nice touch. ✅
• Inconsistency: the two skills use different validation stacks — jose (ui‑widget, injected) vs express-jwt/jwks-rsa (base, assumed but never injected — see Adding Microsoft SECURITY.MD #3). Worth calling out so users of the base skill know the security‑critical piece is on them.

---

🧭 Correctness / robustness

• [Medium] YAML patched with regex/string ops. Both setup-sso Phase 5a and setup-sso-ui-widget Phase 4a locate/insert oauth/register via -match/IndexOf and grab the first configurationId:/applicationIdUri:. This can bind to the wrong block, and the provision:‑insertion path breaks if provision: is the file's last line with no trailing newline (IndexOf("\n", …) → -1 → inserts at offset 0, corrupting the file). Prefer structural YAML parse, or guard the -1 case.
• [Low] az ... 2>$null swallows creation errors. In entra-app-registration.md Step 4, a failed az ad app create yields a null $app/empty $ClientId, and downstream steps fail with confusing errors instead of a clear message.

---

🧩 Documentation consistency

• [Medium] authentication.md contradicts itself on the redirect URI. S1 correctly uses oAuthConsentRedirect, but the pre‑existing troubleshooting row still says "Ensure redirect URI is exactly …/oAuthRedirect". Update the troubleshooting row to oAuthConsentRedirect.
• [Low] Env‑var naming drift. authentication.md documents <PREFIX>_SSO_AUTH_ID / <PREFIX>_SSO_APP_ID_URI, but both skills hardcode MCP_DA_OAUTH_AUTH_ID / MCP_DA_OAUTH_APP_ID_URI. Align the doc and the automation.

---

✅ Duplication verdict — sso-explained.md vs authentication.md

Not a duplicate. They serve distinct purposes and cross‑reference each other:

• authentication.md (declarative‑agent‑developer) = procedural registration/wiring reference spanning Entra SSO and third‑party OAuth, for both MCP and API‑plugin agents (the auth‑pattern chooser, S1–S6, oauth/register).
• sso-explained.md = conceptual/runtime deep dive tied to the ui‑widget layout (end‑to‑end token flow, a decoded token anatomy, claimsStore, failure‑mode table, OBO next steps).

However, two sections are near‑verbatim in both files: the "audience = bare client‑id GUID" rule and the "401 vs 403 consent loop" table/behavior. That's a maintenance/drift risk. Recommendation: keep one canonical copy (I'd vote authentication.md) and have sso-explained.md link to it for those two topics, rather than restating them.

---

Overall

Solid, ship‑worthy direction with great docs. I'd treat #1 (scp enforcement) and #2 (multi‑tenant issuer) as blocking for the injected guard, #3/#4 as strong follow‑ups, and the doc/robustness items as quick cleanups. Happy to pair on the auth.ts hardening if useful.

_{Reviewed with multiple models (security pass + correctness/library pass) cross‑checked against a manual read of the full diff.}

[nayanaramakanth]

@microsoft-github-policy-service agree company="Microsoft"