@microsoft/agents-hosting 1.7.1 → 1.8.0-beta.34.g5d543f96c0

package/src/app/attachmentDownloader.ts

@@ -11,6 +11,8 @@ import { Attachment } from '@microsoft/agents-activity'
 import { AuthProvider } from '../auth/authProvider'
 import { debug } from '@microsoft/agents-telemetry'
 import { loadAuthConfigFromEnv, MsalTokenProvider } from '../auth'
+import { createOutboundHostValidator, OutboundUrlPolicy } from '../outboundHostValidator'
+import { Connections } from '../auth/connections'
 
 const logger = debug('agents:attachmentDownloader')
 
@@ -27,16 +29,19 @@ const logger = debug('agents:attachmentDownloader')
 export class AttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
   private _httpClient: HttpClient
   private _stateKey: string
+  private readonly _hostValidator: OutboundUrlPolicy
 
   /**
    * Creates an instance of AttachmentDownloader.
    * This class is responsible for downloading input files from attachments.
    *
    * @param stateKey The key to store files in state. Defaults to 'inputFiles'.
+   * @param outboundHostValidator Optional shared policy used to validate outbound attachment URLs.
    */
-  public constructor (stateKey: string = 'inputFiles') {
+  public constructor (stateKey: string = 'inputFiles', outboundHostValidator?: OutboundUrlPolicy) {
     this._httpClient = new HttpClient()
     this._stateKey = stateKey
+    this._hostValidator = outboundHostValidator ?? createOutboundHostValidator()
   }
 
   /**
@@ -52,10 +57,18 @@ export class AttachmentDownloader<TState extends TurnState = TurnState> implemen
       return Promise.resolve([])
     }
 
-    // TODO: from adapter
-    const authProvider: AuthProvider = new MsalTokenProvider()
-
-    const accessToken = await authProvider.getAccessToken(loadAuthConfigFromEnv(), 'https://api.botframework.com')
+    let accessToken = ''
+    const connectionManager = (context.adapter as { connectionManager?: Connections })?.connectionManager
+    const identity = context.identity
+    if (connectionManager && identity) {
+      const scope = identity.azp ?? identity.appid ?? 'https://api.botframework.com'
+      logger.debug(`Using adapter connection manager token provider for attachment downloads with scope ${scope}`)
+      accessToken = await connectionManager.getTokenProviderFromActivity(identity, context.activity).getAccessToken(scope)
+    } else {
+      logger.debug('Using MsalTokenProvider fallback for attachment downloads')
+      const authProvider: AuthProvider = new MsalTokenProvider()
+      accessToken = await authProvider.getAccessToken(loadAuthConfigFromEnv(), 'https://api.botframework.com')
+    }
 
     const files: InputFile[] = []
     for (const attachment of attachments) {
@@ -90,6 +103,13 @@ export class AttachmentDownloader<TState extends TurnState = TurnState> implemen
       if (accessToken.length > 0) {
         headers.Authorization = `Bearer ${accessToken}`
       }
+      if (!this._hostValidator.isAllowed(attachment.contentUrl)) {
+        let host = '[invalid-url]'
+        try { host = new URL(attachment.contentUrl).hostname } catch { /* invalid */ }
+        logger.warn(`Attachment contentUrl host is not in the configured allowed hosts. Host='${host}'`)
+        return undefined
+      }
+
       const response = await this._httpClient.get(attachment.contentUrl, {
         headers,
         responseType: 'arraybuffer'

package/src/app/auth/handlers/agenticAuthorization.ts

@@ -22,7 +22,7 @@ const logger = debug('agents:authorization:agentic')
  * where `{handlerId}` is the handler's unique identifier and `{propertyName}` matches the property name.
  *
  * @example
- * ```env
+ * ```
  * # For a handler with id "myAuth":
  * AgentApplication__UserAuthorization__handlers__myAuth__settings__type=AgenticUserAuthorization
  * AgentApplication__UserAuthorization__handlers__myAuth__settings__scopes=api://scope1 api://scope2

package/src/app/auth/handlers/azureBotAuthorization.ts

@@ -48,7 +48,7 @@ interface AzureBotActiveHandler extends ActiveAuthorizationHandler {
  * where `{handlerId}` is the handler's unique identifier and `{propertyName}` matches the property name.
  *
  * @example
- * ```env
+ * ```
  * # For a handler with id "myAuth":
  * AgentApplication__UserAuthorization__handlers__myAuth__settings__azureBotOAuthConnectionName=MyConnection
  * AgentApplication__UserAuthorization__handlers__myAuth__settings__oboScopes=api://scope1 api://scope2

package/src/app/auth/types.ts

@@ -126,7 +126,7 @@ export interface AuthorizationHandlerTokenOptions {
  * where `{handlerId}` is the handler's unique identifier and `{propertyName}` matches the property name.
  *
  * @example
- * ```env
+ * ```
  * # For a handler with id "myAuth":
  * AgentApplication__UserAuthorization__handlers__myAuth__settings__azureBotOAuthConnectionName=MyConnection
  * AgentApplication__UserAuthorization__handlers__myAuth__settings__oboScopes=api://scope1 api://scope2
@@ -170,7 +170,7 @@ export interface AzureBotAuthorizationOptionsLegacy {
  * @deprecated
  * Messages configuration for the AzureBotAuthorization handler.
  */
-interface AzureBotAuthorizationOptionsMessages {
+export interface AzureBotAuthorizationOptionsMessages {
   /**
    * @deprecated Use `invalidSignInRetryMessage` instead.
    * Message displayed when an invalid code is entered.
@@ -198,7 +198,7 @@ interface AzureBotAuthorizationOptionsMessages {
  * @deprecated
  * Settings for on-behalf-of token acquisition.
  */
-interface AzureBotAuthorizationOptionsOBO {
+export interface AzureBotAuthorizationOptionsOBO {
   /**
    * @deprecated Use `oboConnectionName` instead.
    * Connection name to use for on-behalf-of token acquisition.

package/src/app/index.ts

@@ -3,6 +3,14 @@ export * from './agentApplicationBuilder'
 export * from './agentApplicationOptions'
 export * from './appRoute'
 export { Authorization } from './auth/authorization'
+export type { AgenticAuthorizationOptions, AzureBotAuthorizationOptions } from './auth/handlers'
+export type {
+  AuthorizationOptions,
+  AuthorizationHandlerTokenOptions,
+  AzureBotAuthorizationOptionsLegacy,
+  AzureBotAuthorizationOptionsMessages,
+  AzureBotAuthorizationOptionsOBO
+} from './auth/types'
 export * from './routeHandler'
 export * from './routeList'
 export * from './routeRank'

package/src/app/streaming/streamingResponse.ts

@@ -537,14 +537,8 @@ export class StreamingResponse {
     if (activity.deliveryMode === DeliveryModes.ExpectReplies) {
       this._isStreamingChannel = false
     } else if (Channels.Msteams === activity.channelIdChannel) {
-      if (activity.isAgenticRequest()) {
-        // Agentic requests do not support streaming responses at this time.
-        // TODO: Enable streaming for agentic requests when supported.
-        this._isStreamingChannel = false
-      } else {
-        this._isStreamingChannel = true
-        this._delayInMs = 1000
-      }
+      this._isStreamingChannel = true
+      this._delayInMs = 1000
     } else if (Channels.Webchat === activity.channelId || Channels.Directline === activity.channelId || Channels.Emulator === activity.channelId) {
       this._isStreamingChannel = true
       this._delayInMs = 500

package/src/app/teamsAttachmentDownloader.ts

@@ -11,6 +11,7 @@ import { TurnContext } from '../turnContext'
 import { TurnState } from './turnState'
 import { HttpClient } from '../httpClient'
 import { z } from 'zod'
+import { createOutboundHostValidator, OutboundUrlPolicy } from '../outboundHostValidator'
 
 const logger = debug('agents:M365AttachmentDownloader')
 
@@ -20,10 +21,12 @@ const logger = debug('agents:M365AttachmentDownloader')
 export class M365AttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
   private _httpClient: HttpClient
   private _stateKey: string
+  private readonly _hostValidator: OutboundUrlPolicy
 
-  public constructor (stateKey: string = 'inputFiles') {
+  public constructor (stateKey: string = 'inputFiles', outboundHostValidator?: OutboundUrlPolicy) {
     this._httpClient = new HttpClient()
     this._stateKey = stateKey
+    this._hostValidator = outboundHostValidator ?? createOutboundHostValidator()
   }
 
   /**
@@ -69,6 +72,13 @@ export class M365AttachmentDownloader<TState extends TurnState = TurnState> impl
         const contentSchema = z.object({ downloadUrl: z.string().url() })
         const parsed = contentSchema.safeParse(attachment.content)
         const downloadUrl = parsed.success ? parsed.data.downloadUrl : attachment.contentUrl
+        if (!this._hostValidator.isAllowed(downloadUrl)) {
+          let host = '[invalid-url]'
+          try { host = new URL(downloadUrl).hostname } catch { /* invalid */ }
+          logger.warn(`Attachment downloadUrl host is not in the configured allowed hosts. Host='${host}'`)
+          return undefined
+        }
+
         const response = await this._httpClient.get(downloadUrl, { responseType: 'arraybuffer' })
 
         const content = Buffer.from(response.data as ArrayBuffer)

package/src/auth/authConfiguration.ts

@@ -8,6 +8,7 @@ import { loadEnvSettings, AuthConfiguration, envParser, envParserUtils, LoadEnv,
 
 export { type AuthConfiguration, type ConnectionSettings, type ConnectionSettingsBase, type MsalConnectionSettings, type SidecarConnectionSettings, AuthType, resolveAuthority, type ConnectionMapItem, resolveAuthType } from './settings'
 import { prune } from '../utils'
+import { parseBooleanEnv } from '../utils/env'
 import { ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../errorHelper'
 
@@ -28,6 +29,7 @@ function summarizeAuthConfiguration (authConfig: AuthConfiguration) {
       authorityEndpoint: config.authorityEndpoint ? redactUrl(config.authorityEndpoint) : undefined,
       scopes: (config.scopes ? redactScopes(config.scopes) : undefined) as any,
       issuers: config.issuers?.map(redactUrl).filter(e => e !== undefined),
+      validateIssuer: config.validateIssuer,
       federatedClientId: redactString(config.federatedClientId, true),
       certPemFile: redactString(config.certPemFile),
       certKeyFile: redactString(config.certKeyFile),
@@ -40,6 +42,7 @@ function summarizeAuthConfiguration (authConfig: AuthConfiguration) {
       alternateBlueprintConnectionName: undefined, // Alias of altBlueprintConnectionName, avoid logging duplicate info
       azureRegion: config.azureRegion,
       sendX5C: config.sendX5C,
+      msalRetryCount: config.msalRetryCount,
       sidecarBaseUrl: config.sidecarBaseUrl ? redactUrl(config.sidecarBaseUrl) : undefined,
       serviceName: config.serviceName,
       blueprintServiceName: config.blueprintServiceName,
@@ -96,6 +99,10 @@ const connectionsEnv = {
     idpmResource: envParserUtils.bypass,
     azureRegion: envParserUtils.bypass,
     sendX5C: (value) => ({ value: value === 'true' }),
+    msalRetryCount: (value) => {
+      const n = parseInt(value, 10)
+      return { value: Number.isFinite(n) && n >= 0 ? n : undefined }
+    },
     sidecarBaseUrl: envParserUtils.bypass,
     serviceName: envParserUtils.bypass,
     blueprintServiceName: envParserUtils.bypass,
@@ -114,6 +121,7 @@ const connectionsEnv = {
       }
       return { value: value.split(/\s+/).filter(Boolean) }
     },
+    validateIssuer: (value) => ({ value: parseBooleanEnv(value) }),
   }),
   default (connections?: AuthConfiguration['connections'], connectionsMap?: AuthConfiguration['connectionsMap']) {
     const conn = connections ?? this.connections
@@ -230,6 +238,7 @@ const legacyBotFrameworkEnv = {
     WIDAssertionFile: envParserUtils.redirect(connectionsEnv.parser, 'WIDAssertionFile'),
     azureRegion: envParserUtils.redirect(connectionsEnv.parser, 'azureRegion'),
     sendX5C: envParserUtils.redirect(connectionsEnv.parser, 'sendX5C'),
+    msalRetryCount: envParserUtils.redirect(connectionsEnv.parser, 'msalRetryCount'),
     authType: envParserUtils.redirect(connectionsEnv.parser, 'authType'),
     federatedTokenFile: envParserUtils.redirect(connectionsEnv.parser, 'federatedTokenFile'),
     idpmResource: envParserUtils.redirect(connectionsEnv.parser, 'idpmResource'),
@@ -239,6 +248,7 @@ const legacyBotFrameworkEnv = {
     bypassLocalNetworkRestriction: envParserUtils.redirect(connectionsEnv.parser, 'bypassLocalNetworkRestriction'),
     requestTimeout: envParserUtils.redirect(connectionsEnv.parser, 'requestTimeout'),
     retryCount: envParserUtils.redirect(connectionsEnv.parser, 'retryCount'),
+    validateIssuer: envParserUtils.redirect(connectionsEnv.parser, 'validateIssuer'),
   }),
   process (env: LoadEnv) {
     return legacyPrefixEnv.process.call(this, env)
@@ -265,6 +275,7 @@ const legacyPrefixEnv = {
     WIDAssertionFile: envParserUtils.redirect(connectionsEnv.parser, 'WIDAssertionFile'),
     azureRegion: envParserUtils.redirect(connectionsEnv.parser, 'azureRegion'),
     sendX5C: envParserUtils.redirect(connectionsEnv.parser, 'sendX5C'),
+    msalRetryCount: envParserUtils.redirect(connectionsEnv.parser, 'msalRetryCount'),
     authType: envParserUtils.redirect(connectionsEnv.parser, 'authType'),
     federatedTokenFile: envParserUtils.redirect(connectionsEnv.parser, 'federatedTokenFile'),
     idpmResource: envParserUtils.redirect(connectionsEnv.parser, 'idpmResource'),
@@ -274,6 +285,7 @@ const legacyPrefixEnv = {
     bypassLocalNetworkRestriction: envParserUtils.redirect(connectionsEnv.parser, 'bypassLocalNetworkRestriction'),
     requestTimeout: envParserUtils.redirect(connectionsEnv.parser, 'requestTimeout'),
     retryCount: envParserUtils.redirect(connectionsEnv.parser, 'retryCount'),
+    validateIssuer: envParserUtils.redirect(connectionsEnv.parser, 'validateIssuer'),
   }),
   process (env: LoadEnv, prefix?: string) {
     const settings: Partial<AuthConfiguration> = {}

package/src/auth/index.ts

@@ -1,9 +1,11 @@
 export * from './authConfiguration'
 export * from './authConstants'
 export * from './authProvider'
-export * from './msal/msalTokenProvider'
+export * from './connections'
 export * from './request'
+export * from './msal/msalTokenProvider'
 export * from './msal/msalTokenCredential'
 export * from './connectionManager'
+export * from './connections'
 export * from './msal/msalConnectionManager'
 export * from './sidecar/sidecarAuthProvider'

package/src/auth/jwt-middleware.ts

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { AuthConfiguration, resolveAuthority } from './authConfiguration'
+import { AuthConfiguration } from './authConfiguration'
+import { getDefaultIssuers, resolveAuthority } from './settings'
 import { Request } from './request'
 import { WebResponse, NextFunction } from '../interfaces/webResponse'
 import { Errors } from '../errorHelper'
@@ -15,6 +16,25 @@ import { debug } from '@microsoft/agents-telemetry'
 const logger = debug('agents:jwt-middleware')
 const jwksClients = new Map<string, JwksClient>()
 const maxJwksClients = 100
+const authorizedAudience = Symbol('authorizedAudience')
+
+interface AuthorizedRequest extends Request {
+  [authorizedAudience]?: string
+}
+
+interface VerifiedToken {
+  payload: JwtPayload
+  audience: string
+}
+
+/**
+ * Gets the configured audience selected while authorizing a request.
+ * @param req The authorized request.
+ * @returns The matched configured client ID, or `undefined` for anonymous requests.
+ */
+export function getAuthorizedAudience (req: Request): string | undefined {
+  return (req as AuthorizedRequest)[authorizedAudience]
+}
 
 /**
  * Clears process-wide JWKS clients.
@@ -23,6 +43,248 @@ export function clearJwksClients (): void {
   jwksClients.clear()
 }
 
+/**
+ * Well-known Microsoft first-party token issuer tenant IDs that are always trusted,
+ * mirroring the default `ValidIssuers` set in the .NET SDK
+ * (Microsoft.Agents.Hosting.AspNetCore `AspNetExtensions.AddAgentAspNetAuthentication`).
+ *
+ * These identify Microsoft infrastructure tenants used by Azure Bot Service, Teams and
+ * skill and SDK-specific Activity callback flows. They are accepted in addition to a connection's configured
+ * issuers so that enabling issuer validation does not reject legitimate first-party traffic.
+ */
+const WELL_KNOWN_PUBLIC_TENANT_IDS = [
+  'd6d49420-f39b-4df7-a1dc-d59a935871db',
+  'f8cdef31-a31e-4b4a-93e4-5f571e91255a',
+  '69e9b82d-4842-4902-8d1e-abc5b98a55e8'
+]
+const WELL_KNOWN_GOV_TENANT_ID = 'cab8a31a-1906-4287-a0d8-4eef66b95f6e'
+
+/**
+ * Determines whether the configured authority targets the Azure US Government cloud.
+ * @param authority The configured Entra authority.
+ * @returns `true` when the authority is a US Government endpoint.
+ */
+function isGovAuthority (authority?: string): boolean {
+  return !!authority && /login\.microsoftonline\.us/i.test(authority)
+}
+
+function getAuthority (authConfig: AuthConfiguration): string | undefined {
+  return authConfig.authorityEndpoint ?? authConfig.authority
+}
+
+/**
+ * Returns the well-known Microsoft first-party issuers that are always trusted for the
+ * cloud implied by `authority` (public by default, US Government when the authority is gov).
+ * @param authority The configured Entra authority.
+ * @returns The well-known first-party issuer list.
+ */
+function getWellKnownFirstPartyIssuers (authority?: string): string[] {
+  if (isGovAuthority(authority)) {
+    return [
+      'https://api.botframework.us',
+      `https://sts.windows.net/${WELL_KNOWN_GOV_TENANT_ID}/`,
+      `https://login.microsoftonline.us/${WELL_KNOWN_GOV_TENANT_ID}/v2.0`
+    ]
+  }
+  return [
+    'https://api.botframework.com',
+    ...WELL_KNOWN_PUBLIC_TENANT_IDS.flatMap((t) => [
+      `https://sts.windows.net/${t}/`,
+      `https://login.microsoftonline.com/${t}/v2.0`
+    ])
+  ]
+}
+
+/**
+ * Computes the lowercase issuer allow-list used to validate a token's `iss` claim against a
+ * matched connection. The list is the connection's configured issuers (or a tenant-scoped
+ * default when none are configured) unioned with the always-trusted Microsoft first-party
+ * issuers. Comparison is performed case-insensitively to tolerate operator-provided tenant
+ * GUID casing while still rejecting tokens from unrelated tenants.
+ * @param authConfig The matched connection configuration.
+ * @returns A de-duplicated, lowercased list of accepted issuers.
+ */
+function getValidIssuers (authConfig: AuthConfiguration): string[] {
+  const authority = getAuthority(authConfig)
+  const configured = authConfig.issuers && authConfig.issuers.length > 0
+    ? authConfig.issuers
+    : getDefaultIssuers(authConfig.tenantId ?? '', authority ?? 'https://login.microsoftonline.com')
+  const accepted = new Set<string>()
+  for (const issuer of [...configured, ...getWellKnownFirstPartyIssuers(authority)]) {
+    accepted.add(issuer.toLowerCase())
+  }
+  return [...accepted]
+}
+
+/**
+ * Returns the effective tenant identifier for a connection: the tenant embedded in the authority
+ * path when present (which takes precedence, matching {@link resolveAuthority}), otherwise the
+ * configured `tenantId`.
+ * @param authConfig The matched connection configuration.
+ * @returns The effective tenant identifier, or `undefined` when none is configured.
+ */
+function getEffectiveTenant (authConfig: AuthConfiguration): string | undefined {
+  const authority = getAuthority(authConfig)
+  if (authority) {
+    try {
+      const segment = new URL(authority.replace(/\/+$/, '')).pathname.split('/').filter(Boolean).pop()
+      if (segment) {
+        return segment
+      }
+    } catch {
+      // Non-URL authority — fall through to the configured tenantId.
+    }
+  }
+  return authConfig.tenantId
+}
+
+/**
+ * Determines whether a connection is configured as a multi-tenant ("blueprint") agent, i.e. its
+ * effective tenant is the Entra `common` or `organizations` meta-tenant. For such agents the
+ * calling tenant is not known at configuration time, so the strict issuer allow-list cannot
+ * enumerate it and issuer validation must instead accept any canonical Entra issuer for the
+ * configured cloud (still bound to the token's `tid` by {@link validateTenantBinding} and anchored
+ * by the signature and audience checks).
+ * @param authConfig The matched connection configuration.
+ * @returns `true` when the connection targets the `common`/`organizations` meta-tenant.
+ */
+function isMultiTenant (authConfig: AuthConfiguration): boolean {
+  const tenant = getEffectiveTenant(authConfig)?.toLowerCase()
+  return tenant === 'common' || tenant === 'organizations'
+}
+
+/**
+ * Determines whether `iss` is a canonical Entra issuer that may be accepted for a multi-tenant
+ * connection. The issuer must carry a concrete tenant GUID and, for cloud-specific v2 issuers,
+ * belong to the same cloud as the configured authority (public vs US Government). The cloud-
+ * agnostic v1 `sts.windows.net` host is accepted in either cloud.
+ * @param iss The token issuer claim.
+ * @param authConfig The matched connection configuration.
+ * @returns `true` when the issuer is an acceptable Entra tenant issuer for the configured cloud.
+ */
+function isAcceptableTenantIssuer (iss: string, authConfig: AuthConfiguration): boolean {
+  const info = getEntraIssuerInfo(iss)
+  if (!info) {
+    return false
+  }
+  return info.gov === undefined || info.gov === isGovAuthority(getAuthority(authConfig))
+}
+
+/**
+ * Validates that the token's `iss` claim is present and acceptable for the matched connection.
+ * Without this check a signature-valid token from any tenant (Entra signing keys are shared across
+ * tenants in a cloud) with a matching audience would be accepted, enabling a cross-tenant
+ * authentication bypass for multi-tenant app registrations.
+ *
+ * For single-tenant connections the issuer must be in the connection's allow-list. For multi-tenant
+ * ("blueprint") connections, where the calling tenant is unknown at configuration time, any
+ * canonical Entra issuer for the configured cloud is also accepted; the token's tenant is then
+ * bound to its `tid` claim by {@link validateTenantBinding} and ultimately anchored by the
+ * signature and audience (clientId) checks.
+ * @param iss The token issuer claim (from the decoded payload).
+ * @param authConfig The matched connection configuration.
+ * @throws When the issuer is missing, non-string, or not acceptable for the connection.
+ */
+function validateIssuer (iss: unknown, authConfig: AuthConfiguration): void {
+  if (typeof iss === 'string') {
+    if (getValidIssuers(authConfig).includes(iss.toLowerCase())) {
+      return
+    }
+    if (isMultiTenant(authConfig) && isAcceptableTenantIssuer(iss, authConfig)) {
+      return
+    }
+  }
+  const err = ExceptionHelper.generateException(Error, Errors.JwtIssuerMismatch)
+  logger.error(err.message, iss)
+  throw err
+}
+
+/**
+ * Matches a tenant GUID (the format Entra uses for the `tid` claim and the tenant segment of an
+ * Entra issuer). Operator-configured issuers may instead use a tenant domain alias, which cannot
+ * be compared to the GUID `tid` claim and is therefore left unbound.
+ */
+const ENTRA_TENANT_GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * Cloud-affinity metadata for a recognised Entra issuer.
+ */
+interface EntraIssuerInfo {
+  /** The lowercased tenant GUID embedded in the issuer. */
+  tenant: string
+  /**
+   * `true` for US Government (`login.microsoftonline.us`) issuers, `false` for public
+   * (`login.microsoftonline.com`) issuers, and `undefined` for the cloud-agnostic v1
+   * `sts.windows.net` host (which is shared across the public and US Government clouds).
+   */
+  gov?: boolean
+}
+
+/**
+ * Parses a recognised public or US Government Entra issuer into its tenant GUID and cloud affinity,
+ * or returns `undefined` when the issuer is not such an Entra issuer or does not embed a tenant
+ * GUID.
+ *
+ * Only GUID tenants are recognised: the token's `tid` claim is always the tenant GUID, so an issuer
+ * whose tenant segment is a domain alias (e.g. `contoso.onmicrosoft.com`) cannot be compared to
+ * `tid` and is intentionally left unrecognised to preserve compatibility. Non-Entra issuers such as
+ * the Azure Bot Service `api.botframework.*` issuers carry no `tid` claim and are not matched here.
+ * @param iss The token issuer claim.
+ * @returns The issuer's tenant and cloud affinity, or `undefined` when not a recognised Entra issuer.
+ */
+function getEntraIssuerInfo (iss: string): EntraIssuerInfo | undefined {
+  const v1 = /^https:\/\/sts\.windows\.net\/([^/]+)\/$/i.exec(iss)
+  if (v1) {
+    return ENTRA_TENANT_GUID.test(v1[1]) ? { tenant: v1[1].toLowerCase() } : undefined
+  }
+  const v2 = /^([^:]+):\/\/([^/]+)\/([^/]+)\/v2\.0$/.exec(iss)
+  const v2Host = v2 ? /^login\.microsoftonline\.(com|us)$/i.exec(v2[2]) : undefined
+  if (v2 && v2Host && v2[1].toLowerCase() === 'https' && ENTRA_TENANT_GUID.test(v2[3])) {
+    return { tenant: v2[3].toLowerCase(), gov: v2Host[1].toLowerCase() === 'us' }
+  }
+  return undefined
+}
+
+/**
+ * Extracts the tenant GUID embedded in a recognised public or US Government Entra issuer, or
+ * `undefined` when the issuer is not such an Entra issuer or does not embed a tenant GUID.
+ * @param iss The token issuer claim.
+ * @returns The lowercased tenant GUID, or `undefined` when no bindable tenant is present.
+ */
+function getIssuerTenant (iss: string): string | undefined {
+  return getEntraIssuerInfo(iss)?.tenant
+}
+
+/**
+ * Validates that an Entra token's `tid` (tenant id) claim matches the tenant GUID embedded in its
+ * `iss` claim. This binds the accepted issuer to the token's tenant. Because
+ * Entra signing keys are shared across tenants within a cloud, requiring the issuer's tenant and
+ * the `tid` claim to agree prevents a token whose `iss` was allow-listed (for example one of the
+ * always-trusted Microsoft first-party tenants) from being accepted on behalf of a different
+ * tenant.
+ *
+ * The binding only applies when both claims are strings and the issuer is a recognised Entra
+ * issuer carrying a GUID tenant. Missing/non-string claims, Azure Bot Service issuers, and
+ * alias-based issuers are skipped for backward compatibility.
+ * @param iss The token issuer claim.
+ * @param tid The token tenant id claim.
+ * @throws When both claims are strings and the issuer embeds a tenant GUID different from `tid`.
+ */
+function validateTenantBinding (iss: unknown, tid: unknown): void {
+  if (typeof iss !== 'string' || typeof tid !== 'string') {
+    return
+  }
+  const issuerTenant = getIssuerTenant(iss)
+  if (!issuerTenant) {
+    return
+  }
+  if (tid.toLowerCase() !== issuerTenant) {
+    const err = ExceptionHelper.generateException(Error, Errors.JwtTenantMismatch)
+    logger.error(err.message, tid)
+    throw err
+  }
+}
+
 /**
  * Builds the JWKS URI for the given token issuer and auth configuration.
  * @param iss The token issuer claim.
@@ -30,9 +292,14 @@ export function clearJwksClients (): void {
  * @returns The JWKS URI string.
  */
 export function buildJwksUri (iss: string, authConfig: AuthConfiguration): string {
-  return iss === 'https://api.botframework.com'
-    ? 'https://login.botframework.com/v1/.well-known/keys'
-    : `${resolveAuthority(authConfig.authorityEndpoint ?? authConfig.authority, authConfig.tenantId)}/discovery/v2.0/keys`
+  switch (typeof iss === 'string' ? iss.toLowerCase() : '') {
+    case 'https://api.botframework.com':
+      return 'https://login.botframework.com/v1/.well-known/keys'
+    case 'https://api.botframework.us':
+      return 'https://login.botframework.azure.us/v1/.well-known/keys'
+    default:
+      return `${resolveAuthority(authConfig.authorityEndpoint ?? authConfig.authority, authConfig.tenantId)}/discovery/v2.0/keys`
+  }
 }
 
 export function getJwksClient (jwksUri: string): JwksClient {
@@ -59,31 +326,38 @@ export function getJwksClient (jwksUri: string): JwksClient {
  * Verifies the JWT token.
  * @param raw The raw JWT token.
  * @param config The authentication configuration.
- * @returns A promise that resolves to the JWT payload.
+ * @returns A promise that resolves to the verified payload and matched configured audience.
  */
-const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtPayload> => {
+const verifyToken = async (raw: string, config: AuthConfiguration): Promise<VerifiedToken> => {
   const payload = jwt.decode(raw) as JwtPayload
   logger.debug('jwt.decode ', JSON.stringify(payload))
 
   if (!payload) {
     throw ExceptionHelper.generateException(Error, Errors.InvalidJwtToken)
   }
-  const audience = payload.aud
+  const audiences = Array.isArray(payload.aud)
+    ? payload.aud
+    : typeof payload.aud === 'string'
+      ? [payload.aud]
+      : []
 
   const matchingEntry = config.connections && config.connections.size > 0
-    ? [...config.connections.entries()].find(([_, configuration]) => configuration.clientId === audience)
+    ? [...config.connections.entries()].find(([_, configuration]) =>
+        typeof configuration.clientId === 'string' && audiences.includes(configuration.clientId)
+      )
     : undefined
 
   if (!matchingEntry) {
     const err = ExceptionHelper.generateException(Error, Errors.JwtAudienceMismatch)
-    logger.error(err.message, audience)
+    logger.error(err.message, audiences)
     throw err
   }
 
   const [key, authConfig] = matchingEntry
   logger.debug(`Audience found at key: ${key}`)
 
-  const jwksUri = buildJwksUri(payload.iss as string, authConfig)
+  const issuer = typeof payload.iss === 'string' ? payload.iss : ''
+  const jwksUri = buildJwksUri(issuer, authConfig)
 
   logger.debug(`fetching keys from ${jwksUri}`)
   const jwksClient = getJwksClient(jwksUri)
@@ -109,7 +383,7 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
     clockTolerance: 300
   }
 
-  return await new Promise((resolve, reject) => {
+  const verifiedPayload = await new Promise<JwtPayload>((resolve, reject) => {
     jwt.verify(raw, getKey, verifyOptions, (err, user) => {
       if (err) {
         logger.error('jwt.verify ', JSON.stringify(err))
@@ -119,6 +393,14 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
       resolve(user as JwtPayload)
     })
   })
+  if (authConfig.validateIssuer) {
+    validateIssuer(verifiedPayload.iss, authConfig)
+  }
+  validateTenantBinding(verifiedPayload.iss, verifiedPayload.tid)
+  return {
+    payload: verifiedPayload,
+    audience: authConfig.clientId!
+  }
 }
 
 /**
@@ -203,9 +485,11 @@ export const authorizeJWT = (authConfig: AuthConfiguration) => {
       const token = extractBearerToken(req.headers.authorization)
       if (token) {
         try {
-          const user = await verifyToken(token, authConfig)
-          logger.debug('token verified for ', user)
-          req.user = user
+          const verifiedToken = await verifyToken(token, authConfig)
+          logger.debug('token verified for ', verifiedToken.payload)
+          req.user = verifiedToken.payload
+          const authorizedRequest = req as AuthorizedRequest
+          authorizedRequest[authorizedAudience] = verifiedToken.audience
         } catch (err: Error | any) {
           failed = true
           logger.error(err)

package/src/auth/msal/msalConnectionSettings.ts

@@ -76,4 +76,14 @@ export interface MsalConnectionSettings extends ConnectionSettingsBase {
    * The federated client ID for the authentication configuration, used for workload identity federation scenarios.
    */
   federatedClientId?: string
+
+  /**
+   * Maximum number of retries for an MSAL HTTP request that returns status 408.
+   *
+   * @remarks
+   * The initial request is not included in this count. Set to `0` to disable retries.
+   * Defaults to `2`.
+   */
+  msalRetryCount?: number
+
 }