@microsoft/agents-hosting 1.7.2 → 1.8.0-beta.36.gb033f0abc1

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
+
 }

package/src/auth/msal/msalHttpRetryHandlerHelper.ts

@@ -0,0 +1,161 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { INetworkModule, NetworkRequestOptions, NetworkResponse } from '@azure/msal-node'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { debug } from '@microsoft/agents-telemetry'
+import { Errors } from '../../errorHelper'
+
+const logger = debug('agents:msal')
+const requestTimeoutStatus = 408
+
+/**
+ * The default number of retries made for an MSAL HTTP request.
+ */
+export const DEFAULT_MSAL_RETRY_COUNT = 2
+
+/**
+ * Converts a configured MSAL retry count to its effective runtime value.
+ */
+export function normalizeMsalRetryCount (retryCount: number | undefined): number {
+  if (!Number.isFinite(retryCount)) {
+    return DEFAULT_MSAL_RETRY_COUNT
+  }
+
+  return Math.max(0, Math.floor(retryCount as number))
+}
+
+/**
+ * MSAL network client that retries responses with HTTP status 408 (Request Timeout).
+ *
+ * @remarks
+ * `maxRetryCount` is the number of retries after the initial request. Responses with
+ * any other status are returned immediately and retries have no additional delay.
+ */
+export class MsalHttpRetryHandlerHelper implements INetworkModule {
+  private readonly maxRetryCount: number
+
+  public constructor (
+    private readonly networkClient: INetworkModule = new MsalHttpClient(),
+    maxRetryCount: number = DEFAULT_MSAL_RETRY_COUNT
+  ) {
+    this.maxRetryCount = normalizeMsalRetryCount(maxRetryCount)
+  }
+
+  /**
+   * Sends an HTTP GET request, retrying only Request Timeout responses.
+   */
+  public async sendGetRequestAsync<T> (
+    url: string,
+    options?: NetworkRequestOptions,
+    timeout?: number
+  ): Promise<NetworkResponse<T>> {
+    return this.sendWithRetries(() => this.networkClient.sendGetRequestAsync<T>(url, options, timeout))
+  }
+
+  /**
+   * Sends an HTTP POST request, retrying only Request Timeout responses.
+   */
+  public async sendPostRequestAsync<T> (
+    url: string,
+    options?: NetworkRequestOptions
+  ): Promise<NetworkResponse<T>> {
+    return this.sendWithRetries(() => this.networkClient.sendPostRequestAsync<T>(url, options))
+  }
+
+  private async sendWithRetries<T> (send: () => Promise<NetworkResponse<T>>): Promise<NetworkResponse<T>> {
+    let response = await send()
+    let attempt
+    for (attempt = 0; response.status === requestTimeoutStatus && attempt < this.maxRetryCount; attempt++) {
+      logger.debug('MSAL retry on request timeout (retry %d/%d)', attempt + 1, this.maxRetryCount)
+      response = await send()
+    }
+    logger.debug('MSAL request completed with status %d after %d attempt(s)', response.status, attempt + 1)
+    return response
+  }
+}
+
+/**
+ * Default MSAL-compatible network implementation. MSAL Node does not export its
+ * built-in HTTP client, so the retry handler uses the same native fetch contract.
+ */
+class MsalHttpClient implements INetworkModule {
+  public async sendGetRequestAsync<T> (
+    url: string,
+    options?: NetworkRequestOptions,
+    timeout?: number
+  ): Promise<NetworkResponse<T>> {
+    return this.sendRequest<T>(url, 'GET', options, timeout)
+  }
+
+  public async sendPostRequestAsync<T> (
+    url: string,
+    options?: NetworkRequestOptions
+  ): Promise<NetworkResponse<T>> {
+    return this.sendRequest<T>(url, 'POST', options)
+  }
+
+  private async sendRequest<T> (
+    url: string,
+    method: 'GET' | 'POST',
+    options?: NetworkRequestOptions,
+    timeout?: number
+  ): Promise<NetworkResponse<T>> {
+    const controller = new AbortController()
+    const timeoutId = timeout
+      ? setTimeout(() => controller.abort(), timeout)
+      : undefined
+
+    let response: Response
+    try {
+      response = await fetch(url, {
+        method,
+        headers: options?.headers,
+        body: method === 'POST' ? options?.body : undefined,
+        signal: controller.signal
+      })
+    } catch (error) {
+      const innerException = error instanceof Error ? error : undefined
+      if (innerException?.name === 'AbortError') {
+        throw ExceptionHelper.generateException(Error, Errors.TokenRequestTimeout, innerException, { timeoutMs: String(timeout) })
+      }
+      throw ExceptionHelper.generateException(Error, Errors.MsalHttpRequestFailed, innerException, {
+        message: innerException?.message ?? 'unknown'
+      })
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId)
+      }
+    }
+
+    const headers: Record<string, string> = {}
+    response.headers.forEach((value, key) => {
+      headers[key] = value
+    })
+
+    return {
+      headers,
+      body: await this.parseBody<T>(response),
+      status: response.status
+    }
+  }
+
+  private async parseBody<T> (response: Response): Promise<T> {
+    const text = await response.text()
+
+    try {
+      return JSON.parse(text) as T
+    } catch (error) {
+      if (response.status === requestTimeoutStatus) {
+        return {} as T
+      }
+      throw ExceptionHelper.generateException(
+        Error,
+        Errors.MsalResponseUnparsable,
+        error instanceof Error ? error : undefined
+      )
+    }
+  }
+}