Add sovereign cloud support (GCCH, DoD, China)

[rajan-chari]

Summary

• Introduces CloudEnvironment class (Microsoft.Teams.Api.Auth) bundling all cloud-specific service endpoints with predefined static instances: Public, USGov (GCCH), USGovDoD, and China (21Vianet)
• Threads cloud environment through ClientCredentials, BotTokenClient, UserTokenClient, BotSignInClient, App, TeamsValidationSettings, and DI host builders so all previously hardcoded endpoints are configurable per cloud
• Adds Cloud property to AppOptions (programmatic) and TeamsSettings (appsettings.json) for easy configuration
• Adds individual endpoint override properties to TeamsSettings for scenarios requiring per-endpoint customization
• Adds GraphScope to CloudEnvironment for cloud-aware Microsoft Graph token acquisition
• Adds ActiveBotScope and ActiveGraphScope instance properties on BotTokenClient (static BotScope and GraphScope preserved for backwards compatibility)
• Adds AppBuilder.AddCloud() for the AppBuilder host builder path
• Syncs ClientCredentials.Cloud when credentials are provided programmatically
• Input validation: TrimEnd('/') on base URLs, null/whitespace guards on FromName() and ResolveCloud()

Note

graphBaseUrl (Graph API endpoint per cloud) is intentionally deferred. This PR focuses on auth/token acquisition. Graph API routing is a separate concern and the Graph client already accepts a baseUrlRoot override.

Sources

• Bot Framework GCCH/DoD endpoints: https://learn.microsoft.com/en-us/azure/bot-service/how-to-deploy-gov-cloud-high
• Bot Framework China endpoints: https://learn.microsoft.com/en-us/azure/bot-service/how-to-deploy-china-cloud
• OAuth URLs: https://learn.microsoft.com/en-us/azure/bot-service/ref-oauth-redirect-urls
• Graph national cloud deployments: https://learn.microsoft.com/en-us/graph/deployments

Test plan

• dotnet build -- 0 errors
• dotnet test -- 625 tests pass
• E2E: Echo bot with Cloud: USGov against real GCCH tenant -- JWT validated, echo reply sent
• Copilot review feedback addressed

🤖 Generated with Claude Code

[rajan-chari]

Manual Test Results

Tested locally by linking a scaffolded C# echo bot to this branch via ProjectReference (all 7 SDK library projects).

Environment

• Windows 11, .NET 9, PowerShell 7
• Bot registered in Azure with Teams channel + DevTunnel
• SDK linked from local checkout of this branch

Tests

#	Test	Result
1	Negative test — invalid cloud name	Pass. Set "Cloud": "Narnia" in appsettings.json under Teams. Bot crashed on startup with: ArgumentException: Unknown cloud environment: 'Narnia'. Valid values are: Public, USGov, USGovDoD, China. — clear, actionable error message.
2	Default behavior (no Cloud key)	Pass. Without "Cloud" in config, bot starts normally and echoes messages in Teams. Defaults to CloudEnvironment.Public as expected.
3	Config-driven preset	Pass. Setting "Cloud": "Public" in config starts the bot normally — CloudEnvironment.FromName resolves correctly.

Observation

The config path (appsettings.json → TeamsSettings.Cloud) supports only the 4 named presets. Custom endpoints (arbitrary LoginEndpoint, TokenServiceUrl, etc.) are only available via the code path (new CloudEnvironment(...)). This seems fine for the target scenario but worth noting.

Tested with teams-sdk-dev tooling.

[rajan-chari]

Updated Test Results (after e0b56f6 — individual endpoint overrides)

Re-tested with the new WithOverrides / ResolveCloud / per-endpoint config support.

Tests

#	Test	Result
1	Invalid cloud name ("Cloud": "Narnia")	Pass. Crashes with: Unknown cloud environment: 'Narnia'. Valid values are: Public, USGov, USGovDoD, China.
2	Default behavior (no Cloud key)	Pass. Bot starts, echoes messages. Defaults to CloudEnvironment.Public.
3	Named preset ("Cloud": "Public")	Pass. Starts normally.
4	Single endpoint override ("TokenServiceUrl": "https://bogus.example.com/token")	Pass. Bot starts (override accepted at startup, used at runtime). Proves individual override is wired through ResolveCloud → WithOverrides.
5	Preset + override ("Cloud": "USGov" + "LoginEndpoint": "https://custom-login.example.com")	Pass. Bot starts with USGov as base and the custom LoginEndpoint applied on top.
6	Unit tests (CloudEnvironmentTests)	Pass. All 21 tests pass, including 4 new WithOverrides tests (all-nulls, single, multiple, all overrides).

Design Notes

• WithOverrides returns this when all overrides are null — nice zero-allocation fast path.
• ResolveCloud chains cleanly: programmatic AppOptions.Cloud → config "Cloud" preset → Public fallback → per-endpoint overrides. Priority order is clear.
• All 8 endpoint properties are individually overridable from appsettings.json under the Teams section.

[rajan-chari]

URL Verification: CloudEnvironment presets vs Bot Framework docs

Cross-referenced all CloudEnvironment preset URLs against the official Bot Framework sovereign cloud docs.

USGov (GCCH)

Property	PR value	BF Docs value	Match
LoginEndpoint	https://login.microsoftonline.us	https://login.microsoftonline.us	Yes
LoginTenant	MicrosoftServices.onmicrosoft.us	MicrosoftServices.onmicrosoft.us	Yes
BotScope	https://api.botframework.us/.default	https://api.botframework.us	Yes*
TokenServiceUrl	https://tokengcch.botframework.azure.us	https://tokengcch.botframework.azure.us/	Yes*
OpenIdMetadataUrl	https://login.botframework.azure.us/v1/.well-known/openidconfiguration	https://login.botframework.azure.us/v1/.well-known/openidconfiguration	Yes
TokenIssuer	https://api.botframework.us	https://api.botframework.us	Yes
ChannelService	https://botframework.azure.us	https://botframework.azure.us	Yes
OAuthRedirectUrl	https://tokengcch.botframework.azure.us/.auth/web/redirect	https://tokengcch.botframework.azure.us/.auth/web/redirect	Yes

USGovDoD

Property	PR value	BF Docs value	Match
LoginEndpoint	https://login.microsoftonline.us	https://login.microsoftonline.us	Yes
LoginTenant	MicrosoftServices.onmicrosoft.us	MicrosoftServices.onmicrosoft.us	Yes
BotScope	https://api.botframework.us/.default	https://api.botframework.us	Yes*
TokenServiceUrl	https://apiDoD.botframework.azure.us	https://apiDoD.botframework.azure.us	Yes
OpenIdMetadataUrl	https://login.botframework.azure.us/v1/.well-known/openidconfiguration	https://login.botframework.azure.us/v1/.well-known/openidconfiguration	Yes
TokenIssuer	https://api.botframework.us	https://api.botframework.us	Yes
ChannelService	https://botframework.azure.us	https://botframework.azure.us	Yes
OAuthRedirectUrl	https://apiDoD.botframework.azure.us/.auth/web/redirect	(not in docs, consistent with OAuthUrl pattern)	Yes

Notes on the two * items

• BotScope /.default suffix: The PR uses https://api.botframework.us/.default — this is the standard MSAL/OAuth2 scope format. The docs show the resource identifier (https://api.botframework.us), but /.default is the correct programmatic form. This is intentional and correct.
• TokenServiceUrl trailing slash: Docs show a trailing / on GCCH (https://tokengcch.botframework.azure.us/), PR omits it. Functionally equivalent.

All URLs match. Source: Deploy Bots to Azure Government and Office 365 GCC High

[rido-min]

Thank you for addressing sovereign cloud support - this is an important capability for government and regional customers.

I have some architectural concerns about the current approach that I'd like to discuss before we proceed:

1. Hard-coded endpoint presets create a maintenance burden

The CloudEnvironment class embeds specific URLs for each sovereign cloud (GCCH, DoD, China). These endpoints have historically changed over time - when Microsoft updates them, this requires an SDK release
and forces all consumers to update their SDK version, even though their application logic hasn't changed. This couples deployment cycles unnecessarily.

The MSAL library itself avoids this pattern - it relies on well-known discovery documents (OpenID configuration endpoints) to resolve the actual service URLs at runtime. This approach is more resilient to
endpoint changes.

2. Configuration-only approach is more flexible

Rather than providing presets, consider allowing sovereign cloud configuration entirely through settings:

{
"Teams": {
"LoginEndpoint": "https://login.microsoftonline.us",
"TokenServiceUrl": "https://tokengcch.botframework.azure.us",
...
}
}

This puts control in the hands of the deploying organization (who often have specific requirements in sovereign environments) rather than requiring SDK changes.

3. Scattered client configuration

The current implementation adds TokenServiceUrl properties to individual clients (BotSignInClient, UserTokenClient, BotTokenClient). This means each client must be configured separately, which is error-prone
and harder to maintain than a centralized configuration that flows through to all clients.

Alternative approach to consider:

• Use the OpenID discovery document (already referenced as OpenIdMetadataUrl) to dynamically resolve endpoints where possible
• If presets are valuable for developer convenience, consider shipping them as a separate configuration file or NuGet package that can be updated independently of the core SDK
• Centralize cloud configuration in one place that all clients consume, rather than scattering it across multiple client classes

Would it be worth discussing these trade-offs before proceeding?

[rido-min]

• If presets are valuable for developer convenience, consider shipping them as a separate configuration file or NuGet package that can be updated independently of the core SDK

I dont think presets are valuable, we dont own the Entra URLs, and we should not hardcode those URLs in our codebase.

@copilot what do you think about the comments in #352 (review)

[Copilot]

@rido-min I've opened a new pull request, #357, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

Pull request overview

Adds sovereign cloud (GCCH, DoD, China/21Vianet) configurability to the Teams SDK by introducing a CloudEnvironment abstraction and threading it through auth/token clients, app construction, and configuration/hosting extensions so previously hardcoded endpoints can be selected or overridden.

Changes:

• Introduces CloudEnvironment presets (Public, USGov, USGovDoD, China) plus FromName() and WithOverrides() to centralize cloud-specific endpoints.
• Updates auth/token flows to use cloud-specific endpoints/scopes (e.g., configurable Bot Framework scope and token service base URL).
• Adds configuration + hosting resolution (TeamsSettings.ResolveCloud()) and new tests covering cloud-specific behavior.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
Libraries/Microsoft.Teams.Api/Auth/CloudEnvironment.cs	New centralized cloud endpoint bundle with presets + name resolution + overrides.
Libraries/Microsoft.Teams.Api/Auth/ClientCredentials.cs	Uses cloud login endpoint + tenant for client-credentials token acquisition.
Libraries/Microsoft.Teams.Api/Clients/BotTokenClient.cs	Adds overridable bot scope (ActiveBotScope) used for token acquisition.
Libraries/Microsoft.Teams.Api/Clients/UserTokenClient.cs	Makes token service base URL configurable via TokenServiceUrl.
Libraries/Microsoft.Teams.Api/Clients/BotSignInClient.cs	Makes token service base URL configurable via TokenServiceUrl.
Libraries/Microsoft.Teams.Apps/AppOptions.cs	Adds Cloud option to pass cloud environment programmatically.
Libraries/Microsoft.Teams.Apps/App.cs	Applies cloud settings to API sub-clients (bot scope + token service URLs).
Libraries/Microsoft.Teams.Extensions.Configuration/Microsoft.Teams.Apps.Extensions/TeamsSettings.cs	Adds Cloud + per-endpoint overrides and resolves to a CloudEnvironment.
Libraries/Microsoft.Teams.Extensions.Hosting/Microsoft.Teams.Apps.Extensions/HostApplicationBuilder.cs	Resolves cloud from config/programmatic options and wires into credentials/options.
Libraries/Microsoft.Teams.Plugins/Microsoft.Teams.Plugins.AspNetCore/Extensions/HostApplicationBuilder.cs	Resolves cloud from config for token validation setup.
Libraries/Microsoft.Teams.Plugins/Microsoft.Teams.Plugins.AspNetCore/Extensions/TeamsValidationSettings.cs	Makes validation settings cloud-aware (OpenID metadata URL, issuers, Entra issuer derivation).
Tests/Microsoft.Teams.Api.Tests/Auth/CloudEnvironmentTests.cs	New unit tests validating presets, overrides, and name resolution.
Tests/Microsoft.Teams.Api.Tests/Clients/BotTokenClientTests.cs	Adds coverage for ActiveBotScope behavior and usage.
Tests/Microsoft.Teams.Plugins.AspNetCore.Tests/Extensions/TeamsValidationSettingsTests.cs	New tests validating cloud-aware token validation settings behavior.

Comments suppressed due to low confidence (1)

Libraries/Microsoft.Teams.Apps/App.cs:60

• AppOptions.Cloud is applied to the API clients (bot scope + token service URLs), but it isn’t applied to ClientCredentials. In the programmatic usage shown in the PR description (Cloud = CloudEnvironment.USGov + Credentials = new ClientCredentials(...)), ClientCredentials.Cloud will remain Public and token acquisition will still hit login.microsoftonline.com. Consider propagating cloud into ClientCredentials when Credentials is a ClientCredentials instance (or otherwise document/guard against this mismatch).

        var cloud = options?.Cloud ?? CloudEnvironment.Public;

        Logger = options?.Logger ?? new ConsoleLogger();
        Storage = options?.Storage ?? new LocalStorage<object>();
        Credentials = options?.Credentials;
        Plugins = options?.Plugins ?? [];
        OAuth = options?.OAuth ?? new OAuthSettings();

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rajan-chari]

Review: Missing Graph scope in CloudEnvironment + merge recommendation

Missing GraphScope property

The CloudEnvironment class bundles 8 cloud-specific URLs but is missing the Microsoft Graph token scope, which varies per sovereign cloud. The current code in BotTokenClient still hardcodes https://graph.microsoft.com/.default.

Microsoft docs state:

"Any permission scope value (including the .default scope) that contains the Microsoft Graph domain MUST use the domain of the Microsoft Graph service root endpoint for the national cloud deployment."

Source: Access national cloud deployments with the Microsoft Graph SDKs

Correct Graph scopes per cloud (from Microsoft Graph national cloud deployments):

Preset	Graph scope
Public	https://graph.microsoft.com/.default
USGov (GCC High)	https://graph.microsoft.us/.default
USGovDoD	https://dod-graph.microsoft.us/.default
China	https://microsoftgraph.chinacloudapi.cn/.default

Note: DoD uses a different Graph host than GCC High (dod-graph.microsoft.us vs graph.microsoft.us), so this cannot be derived from LoginEndpoint alone.

Suggested fix: Add a GraphScope property to CloudEnvironment, set it correctly in all 4 presets, and update BotTokenClient to use it.

Merge path recommendation

This PR (#352) is the Libraries-layer foundation that #413 (next/core) depends on. Since the next version ships from core/:

1. Add GraphScope to this PR, then merge
2. Then Add sovereign cloud support to next/core (GCCH, DoD, China) #413 can land on top of it
3. PR Replace CloudEnvironment with MSAL-aligned Instance property for sovereign cloud support #357 (Instance-only approach) should be closed — see comment on that PR for reasoning
4. PR Use MSAL to mint tokens #203 (MSAL) is not needed since core/ already uses Microsoft.Identity.Web

The CloudEnvironment approach in this PR is the correct pattern — it works with or without MSAL, and covers the 6 URL categories that MSAL does not handle (bot scope, graph scope, token service, OpenID metadata, token issuer, channel service).

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.