[Tomasz Naumowicz (tnaum-ms)]

What changed

Microsoft Entra ID connections to Azure DocumentDB now work with the Azure cloud VS Code is signed in to (Azure US Government, Azure China, custom clouds), and sign-in failures get actionable explanations.

• Cloud-aware token audience. The extension used to always request the public-cloud resource https://ossrdbms-aad.database.windows.net. It now requests the open-source database resource of the selected cloud (microsoft-sovereign-cloud.environment): …usgovcloudapi.net for US Government, …chinacloudapi.cn for China. Public-cloud behavior is unchanged (tests pin the scope string).
• Custom clouds resolve the resource from the new documentDB.customEnvironment.ossrdbmsEndpoint setting, the custom cloud's sign-in host, or its ARM metadata (/metadata/endpoints?api-version=2022-09-01), and fail clearly otherwise. They never fall back to the public audience.
• Cloud mismatch check. If the cluster's domain (azure.com, azure.us, azure.cn) belongs to another cloud than the one VS Code is signed in to, the extension stops before sign-in and names the setting to change.
• Managed identity takes the cloud from the override, the cluster host, then the VM's instance metadata, not from the VS Code sign-in setting.
• Shell and playground resolve the scope on the main thread; the worker no longer chooses it. Copy Connection String writes the matching TOKEN_RESOURCE.
• Entra error classifier. One rule table (src/documentdb/auth/entraErrors/entraErrorRules.ts) maps AADSTS codes and the opaque Windows broker error to messages that say who can fix the problem. It plugs into ConnectionDiagnosticsService, so every surface that already explains connection errors gets it.
• Support tracing. Every Entra connection logs entraCloud.resolved (cloud, sign-in provider, broker mode, host cloud, chosen token resource and why), with no tenant, account, host, or connection-string values.
• Docs. New user-manual page docs/user-manual/sovereign-clouds.md.

Why

A reported issue: in Azure US Government, listing resources works but connecting with Entra ID fails with AADSTS65002. Two causes:

1. VS Code's client is not yet preauthorized for the OSS RDBMS resource in that cloud. This is a service-side configuration change outside this repository, and it is in progress. Precedents: [Bug]: Sovereign Cloud Universal with MFA Support auth error vscode-mssql#22296, VS Code Could not login to Azure vscode#244689.
2. The extension always requested the public-cloud audience. This PR fixes that part and makes the first one diagnosable.

Rejected alternatives (own client ID, falling back to the public audience, buttons on diagnostics) and the reasoning are in decisions.md.

Scope

Not in this PR: the service-side preauthorization; buttons on diagnostic messages (Report issue, Switch cloud); an ask-once prompt for custom clouds.

Validation

• npm run build and targeted Vitest (auth, shell, playground, services, copy connection string, settings) pass.
• Not verified end to end: nobody on the team has sovereign-cloud access. US Government sign-in cannot succeed until the service-side configuration rolls out. A preview build will be shared with the reporter then.
• Before shipping (D11): check telemetry for successful Entra connections to *.azure.cn hosts, so the switch to the China audience cannot break existing users.
• Draft: the full Case 2 checks (l10n, prettier-fix, lint, typecheck:tests, full Vitest, package) are deferred until ready for review. The AI pre-review has not run yet.

Links

• Feature docs: docs/ai-and-plans/features/sovereign-clouds/
• Related: Revisit: OIDC ALLOWED_HOSTS hardcoded to *.azure.com blocks sovereign clouds and custom domains #639, OIDC ALLOWED_HOSTS suffix recognition accepts any azure.<tld>, including non-Microsoft TLDs open for public registration #934

[github-actions]

✅ CI passed: full tier (full run requested by Tomasz Naumowicz (@tnaum-ms) for 7f2a288)

Commit 7f2a288, workflow run.

Layer	Result	Ran or skipped because
Static checks	✅ passed	every push
Unit tests	✅ passed	every push
npm packages: verify tarballs	✅ passed	full run requested
VSIX: inspect contents	✅ passed	full run requested
VSIX: self-test of the checks	✅ passed	full run requested
VSIX: activate in VS Code	✅ passed	full run requested
VSIX: self-test of the activation check	✅ passed	full run requested
Webview host in unbundled extensions	✅ passed	full run requested
E2E	⏭️ not available yet	arrives with the E2E iteration (full tier)

Code quality

Check	Status	How to fix
Localization (l10n)	✅ Passed	Nothing to fix
ESLint	✅ Passed	Nothing to fix
Prettier formatting	✅ Passed	Nothing to fix

Build size

No page, activation, VSIX or other bundle size changed by 5% or 50 KiB or more against main. VSIX: 8.5 MiB.

Artifacts: VSIX | Bundle-reports-40388721389 | L1-manifest-report-40388721389

All graphs (exact bytes)

Graph	PR bytes	Base bytes	Delta bytes	Delta %
Collection View page (collectionView)	6,036,286	6,036,286	✅ 0	0.0%
Document View page (documentView)	4,808,762	4,808,762	✅ 0	0.0%
Local Quick Start page (localQuickStart)	1,551,408	1,551,408	✅ 0	0.0%
Atlas Credentials page (atlasCredentials)	1,504,612	1,504,612	✅ 0	0.0%
Cluster Dashboard page (clusterDashboard)	1,550,863	1,550,863	✅ 0	0.0%
Activation (mainStartup)	3,472,062	3,448,763	⬆️ +23,299	+0.7%
Extension host (main)	9,998,788	9,975,455	⬆️ +23,333	+0.2%
Playground worker (playgroundWorker)	5,385,471	5,384,556	⬆️ +915	+0.0%
VSIX (vsix)	8,948,779	8,941,533	⬆️ +7,246	+0.1%
playgroundTsPlugin	6,175	6,175	✅ 0	0.0%
viewsEntry	1,456,593	1,456,593	✅ 0	0.0%
viewsAssets	80,340	80,340	✅ 0	0.0%
editorWorker	259,528	259,528	✅ 0	0.0%
jsonWorker	389,389	389,389	✅ 0	0.0%

Packaged bytes. Shared chunks count in every graph that loads them, so rows do not add up.

Updated in place on every run.