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 (e.g. LoginEndpoint, LoginTenant) for scenarios requiring per-endpoint customization — such as China single-tenant bots that need a tenant-specific login URL

Usage

Named cloud preset (appsettings.json):

{
  "Teams": {
    "ClientId": "...",
    "ClientSecret": "...",
    "Cloud": "USGov"
  }
}

Per-endpoint overrides (appsettings.json):

{
  "Teams": {
    "ClientId": "...",
    "ClientSecret": "...",
    "TenantId": "your-tenant",
    "Cloud": "China",
    "LoginTenant": "your-tenant-id"
  }
}

Programmatic:

var app = new App(new AppOptions
{
    Cloud = CloudEnvironment.USGov,
    Credentials = new ClientCredentials("id", "secret")
});

// Or with per-endpoint overrides:
var cloud = CloudEnvironment.China.WithOverrides(loginTenant: "my-tenant-id");

Valid cloud names: Public (default), USGov, USGovDoD, China

Override properties: LoginEndpoint, LoginTenant, BotScope, TokenServiceUrl, OpenIdMetadataUrl, TokenIssuer, ChannelService, OAuthRedirectUrl

Files changed

Action	File
New	Libraries/Microsoft.Teams.Api/Auth/CloudEnvironment.cs
New	Tests/Microsoft.Teams.Api.Tests/Auth/CloudEnvironmentTests.cs
Modified	Libraries/Microsoft.Teams.Api/Auth/ClientCredentials.cs
Modified	Libraries/Microsoft.Teams.Api/Clients/BotTokenClient.cs
Modified	Libraries/Microsoft.Teams.Api/Clients/UserTokenClient.cs
Modified	Libraries/Microsoft.Teams.Api/Clients/BotSignInClient.cs
Modified	Libraries/Microsoft.Teams.Apps/AppOptions.cs
Modified	Libraries/Microsoft.Teams.Apps/App.cs
Modified	TeamsSettings.cs (Extensions.Configuration) — endpoint override properties + ResolveCloud()
Modified	HostApplicationBuilder.cs (Extensions.Hosting) — unified cloud resolution via ResolveCloud()
Modified	HostApplicationBuilder.cs (Plugins.AspNetCore) — unified cloud resolution via ResolveCloud()
Modified	TeamsValidationSettings.cs (Plugins.AspNetCore)

Test plan

• dotnet build — 0 errors
• dotnet test — all existing + new tests pass
• CloudEnvironment.Public URLs match current hardcoded values (backward compat)
• WithOverrides() with all nulls returns same instance (no allocation)
• Individual and multiple endpoint overrides replace correct properties while preserving others
• Verify CloudEnvironment.USGov URLs match BF GCCH docs
• Verify CloudEnvironment.China URLs match BF China docs
• Test sample app (Samples.Echo) starts correctly with no cloud config (defaults to Public)

🤖 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.