Service URL Validation

The Teams SDK validates that incoming serviceUrl values belong to known domains before using them for outbound API calls. This prevents the bot's credentials from being sent to unauthorized endpoints.

How it works

When your bot receives an activity from the Bot Framework Channel Service, the activity includes a serviceUrl field that tells the SDK where to send responses. The SDK validates this URL against allowed hostnames from the configured cloud environment before making any outbound requests.

Allowed hostnames by cloud

Each cloud environment preset includes the allowed service URL hostnames for that cloud:

Cloud	Allowed hostnames
Public (default)	smba.trafficmanager.net, smba.onyx.prod.teams.trafficmanager.net, smba.infra.gcc.teams.microsoft.com
US Gov (GCCH)	smba.infra.gov.teams.microsoft.us
US Gov DoD	smba.infra.dod.teams.microsoft.us
China (21Vianet)	frontend.botapi.msg.infra.teams.microsoftonline.cn
localhost / 127.0.0.1	Always allowed for local development

If your bot is configured for a sovereign cloud, only that cloud's hostnames are allowed by default.

Adding custom domains

If your bot receives activities from a service URL outside the cloud preset's allowlist (e.g., sovereign clouds without presets, non-Teams channels, or custom environments), you can add additional hostnames.

Sovereign cloud FQDNs that require additionalAllowedDomains:

Environment	FQDN
France (Bleu)	smba.teams.sovcloud-core.fr
EagleX	frontend.botapi.msg.infra.teams.eaglex.ic.gov
SCloud	frontend.botapi.msg.infra.teams.microsoft.scloud

Via appsettings.json:

{
  "Teams": {
    "AdditionalAllowedDomains": ["api.my-custom-channel.com"]
  }
}

Disabling validation

warning

Disabling service URL validation removes a security protection that prevents your bot's credentials from being sent to unauthorized endpoints. Only disable this if you understand the security implications.

If you have a non-standard setup where domain-based validation does not work, you can disable it by passing * as an additional domain:

Via appsettings.json:

{
  "Teams": {
    "AdditionalAllowedDomains": ["*"]
  }
}

Proactive messaging

info

Service URL validation runs on incoming activities. If you store a ConversationReference for proactive messaging, the serviceUrl was validated when the original activity was received. Only store conversation references from validated inbound activities -- never from untrusted external sources.