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

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

package/src/auth/msal/msalTokenProvider.ts

@@ -15,6 +15,7 @@ import crypto from 'crypto'
 import { AuthenticationTraceDefinitions } from '../../observability'
 import { ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../../errorHelper'
+import { MsalHttpRetryHandlerHelper, normalizeMsalRetryCount } from './msalHttpRetryHandlerHelper'
 
 const audience = 'api://AzureADTokenExchange'
 const logger = debug('agents:msal')
@@ -203,12 +204,14 @@ export class MsalTokenProvider implements AuthProvider {
   }
 
   private getClientSecretClient (authConfig: AuthConfiguration): ConfidentialClientApplication {
+    const retryCount = normalizeMsalRetryCount(authConfig.msalRetryCount)
     const cacheKey = MsalTokenProvider.cacheKey(
       'confidential-client',
       AuthType.ClientSecret,
       authConfig.clientId,
       resolveAuthorityUtil(authConfig.authorityEndpoint ?? authConfig.authority, authConfig.tenantId),
-      MsalTokenProvider.digest(authConfig.clientSecret)
+      MsalTokenProvider.digest(authConfig.clientSecret),
+      retryCount
     )
 
     return this.getOrCreateConfidentialClient(cacheKey, () => new ConfidentialClientApplication({
@@ -217,11 +220,12 @@ export class MsalTokenProvider implements AuthProvider {
         authority: resolveAuthorityUtil(authConfig.authorityEndpoint ?? authConfig.authority, authConfig.tenantId),
         clientSecret: authConfig.clientSecret
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     }))
   }
 
   private getCertificateClient (authConfig: AuthConfiguration): ConfidentialClientApplication {
+    const retryCount = normalizeMsalRetryCount(authConfig.msalRetryCount)
     const cacheKey = MsalTokenProvider.cacheKey(
       'confidential-client',
       authConfig.authType ?? AuthType.Certificate,
@@ -229,7 +233,8 @@ export class MsalTokenProvider implements AuthProvider {
       resolveAuthorityUtil(authConfig.authorityEndpoint ?? authConfig.authority, authConfig.tenantId),
       this.getFileCacheIdentity(authConfig.certPemFile),
       this.getFileCacheIdentity(authConfig.certKeyFile),
-      authConfig.sendX5C
+      authConfig.sendX5C,
+      retryCount
     )
 
     return this.getOrCreateConfidentialClient(cacheKey, () => {
@@ -258,7 +263,7 @@ export class MsalTokenProvider implements AuthProvider {
             x5c: pemFile.toString()
           }
         },
-        system: this.sysOptions
+        system: this.getSystemOptions(authConfig)
       })
     })
   }
@@ -434,7 +439,7 @@ export class MsalTokenProvider implements AuthProvider {
           clientAssertion: appToken,
           authority: this.resolveAuthority(tenantId),
         },
-        system: this.sysOptions
+        system: this.getSystemOptions(this.connectionSettings)
       })
 
       const token = await cca.acquireTokenByClientCredential({
@@ -613,7 +618,7 @@ export class MsalTokenProvider implements AuthProvider {
         managedIdentityIdParams: {
           userAssignedClientId: this.connectionSettings.clientId
         },
-        system: this.sysOptions
+        system: this.getSystemOptions(this.connectionSettings)
       })
       const tokenResult = await msiApp.acquireToken({ resource })
       if (!tokenResult?.accessToken) {
@@ -638,7 +643,10 @@ export class MsalTokenProvider implements AuthProvider {
         if (!this.connectionSettings.federatedClientId && !this.connectionSettings.FICClientId) {
           throw ExceptionHelper.generateException(Error, Errors.FICClientIdRequired)
         }
-        clientAssertion = await this.fetchExternalToken(this.connectionSettings.federatedClientId as string || this.connectionSettings.FICClientId as string)
+        clientAssertion = await this.fetchExternalToken(
+          this.connectionSettings.federatedClientId as string || this.connectionSettings.FICClientId as string,
+          this.connectionSettings
+        )
         break
       case AuthType.Certificate:
       case AuthType.CertificateSubjectName:
@@ -688,6 +696,13 @@ export class MsalTokenProvider implements AuthProvider {
     }
   }
 
+  private getSystemOptions (authConfig?: AuthConfiguration): NodeSystemOptions {
+    return {
+      ...this.sysOptions,
+      networkClient: new MsalHttpRetryHandlerHelper(undefined, normalizeMsalRetryCount(authConfig?.msalRetryCount))
+    }
+  }
+
   /**
    * Generates the client assertion using the provided certificate.
    * @param authConfig The authentication configuration.
@@ -742,7 +757,7 @@ export class MsalTokenProvider implements AuthProvider {
       managedIdentityIdParams: {
         userAssignedClientId: authConfig.clientId || ''
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     })
     const token = await mia.acquireToken({
       resource: scope
@@ -758,7 +773,7 @@ export class MsalTokenProvider implements AuthProvider {
    */
   private async acquireTokenWithSystemAssignedIdentity (authConfig: AuthConfiguration, scope: string) {
     const mia = new ManagedIdentityApplication({
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     })
     const token = await mia.acquireToken({
       resource: scope
@@ -812,14 +827,17 @@ export class MsalTokenProvider implements AuthProvider {
    */
   private async acquireAccessTokenViaFIC (authConfig: AuthConfiguration, scope: string) : Promise<string> {
     const scopes = [`${scope}/.default`]
-    const clientAssertion = await this.fetchExternalToken(authConfig.federatedClientId as string || authConfig.FICClientId as string)
+    const clientAssertion = await this.fetchExternalToken(
+      authConfig.federatedClientId as string || authConfig.FICClientId as string,
+      authConfig
+    )
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId as string,
         authority: `${authConfig.authorityEndpoint ?? authConfig.authority}/${authConfig.tenantId}`,
         clientAssertion
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     })
     const token = await cca.acquireTokenByClientCredential({ scopes, azureRegion: authConfig.azureRegion })
     logger.debug('got token using FIC client assertion')
@@ -845,7 +863,7 @@ export class MsalTokenProvider implements AuthProvider {
         authority: `https://login.microsoftonline.com/${authConfig.tenantId}`,
         clientAssertion
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     })
     const token = await cca.acquireTokenByClientCredential({ scopes, azureRegion: authConfig.azureRegion })
     logger.debug('got token using WID client assertion')
@@ -860,12 +878,12 @@ export class MsalTokenProvider implements AuthProvider {
    * @param FICClientId The FIC client ID.
    * @returns A promise that resolves to the external token.
    */
-  private async fetchExternalToken (FICClientId: string) : Promise<string> {
+  private async fetchExternalToken (FICClientId: string, authConfig?: AuthConfiguration) : Promise<string> {
     const managedIdentityClientAssertion = new ManagedIdentityApplication({
       managedIdentityIdParams: {
         userAssignedClientId: FICClientId
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig ?? this.connectionSettings)
     }
     )
     const response = await managedIdentityClientAssertion.acquireToken({

package/src/auth/settings.ts

@@ -170,6 +170,12 @@ export function resolveAuthority (authority?: string, tenantId?: string): string
   return `${base}/${tenantId ?? 'botframework.com'}`
 }
 
+function getEffectiveTenant (tenantId: string | undefined, authority: string): string | undefined {
+  const resolvedAuthority = new URL(trimTrailingSlashes(authority))
+  const embeddedTenant = resolvedAuthority.pathname.split('/').filter(Boolean).pop()
+  return embeddedTenant ?? tenantId
+}
+
 function trimTrailingSlashes (value: string): string {
   let end = value.length
   while (end > 0 && value.charCodeAt(end - 1) === 47) {
@@ -179,14 +185,14 @@ function trimTrailingSlashes (value: string): string {
   return end === value.length ? value : value.slice(0, end)
 }
 
-function getDefaultIssuers (tenantId: string, authority: string) : string[] {
+export function getDefaultIssuers (tenantId: string, authority: string) : string[] {
   // Convert empty string to undefined so resolveAuthority applies its 'botframework.com' default
-  const t = tenantId || undefined
+  const t = getEffectiveTenant(tenantId || undefined, authority)
   if (!t) {
     logger.warn('tenantId is not configured, defaulting to botframework.com')
   }
   return [
-    'https://api.botframework.com',
+    /login\.microsoftonline\.us/i.test(authority) ? 'https://api.botframework.us' : 'https://api.botframework.com',
     `${resolveAuthority('https://sts.windows.net', t)}/`,
     `${resolveAuthority(authority, t)}/v2.0`
   ]
@@ -223,6 +229,15 @@ export interface ConnectionSettingsBase {
    */
   issuers?: string[]
 
+  /**
+   * Whether to validate the token issuer against {@link issuers}.
+   *
+   * @remarks
+   * Disabled by default for backward compatibility. Tenant-to-issuer binding is always applied
+   * independently when both claims contain comparable tenant GUIDs.
+   */
+  validateIssuer?: boolean
+
   /**
    * The connection name for the authentication configuration.
    */

package/src/cloudAdapter.ts

@@ -7,7 +7,7 @@ import { AgentHandler, INVOKE_RESPONSE_KEY } from './activityHandler'
 import { BaseAdapter } from './baseAdapter'
 import { TurnContext } from './turnContext'
 import { Request } from './auth/request'
-import { WebResponse } from './interfaces/webResponse'
+import { NextFunction, WebResponse } from './interfaces/webResponse'
 import { ConnectorClient } from './connector-client/connectorClient'
 import { AuthConfiguration, getAuthConfigWithDefaults } from './auth/authConfiguration'
 import { AuthProvider } from './auth/authProvider'
@@ -32,6 +32,8 @@ import { parseBooleanEnv, suggestClosest } from './utils/env'
 import { trace } from '@microsoft/agents-telemetry'
 import { AdapterTraceDefinitions } from './observability'
 import { applyAgenticHeaders } from './getProductInfo'
+import { createOutboundHostValidator, OutboundUrlPolicy } from './outboundHostValidator'
+import { authorizeJWT } from './auth/jwt-middleware'
 
 const logger = debug('agents:cloud-adapter')
 
@@ -80,6 +82,9 @@ export interface CloudAdapterOptions {
    * for one service URL tries to send activities targeting a different one.
    *
    * Env var: `CloudAdapterOptions__validateServiceUrl`.
+   *
+   * @deprecated Configure {@link OutboundUrlPolicy} instead. This option
+   * remains available for backward compatibility with claim-only validation.
    */
   validateServiceUrl?: boolean
 }
@@ -238,6 +243,7 @@ function truncateActivityForLog (activity: unknown, max = 1024): string {
 
 export class CloudAdapter extends BaseAdapter {
   protected readonly authConfig: AuthConfiguration
+  private readonly jwtMiddleware: ReturnType<typeof authorizeJWT>
   protected _agentName?: string
 
   /**
@@ -246,6 +252,7 @@ export class CloudAdapter extends BaseAdapter {
   connectionManager: Connections
 
   private readonly _options: Required<CloudAdapterOptions>
+  private readonly _hostValidator: OutboundUrlPolicy
 
   /**
    * Creates an instance of CloudAdapter.
@@ -253,12 +260,17 @@ export class CloudAdapter extends BaseAdapter {
    * @param authProvider - No longer used.
    * @param userTokenClient - No longer used.
    * @param options - Optional runtime behavior overrides. See {@link CloudAdapterOptions}.
+   * @param outboundHostValidator - Optional policy for validating outbound `Activity.serviceUrl` hosts.
+   * When omitted, the policy is loaded from `OutboundHostValidator__*` environment variables
+   * and remains disabled by default.
    */
-  constructor (authConfig?: AuthConfiguration, authProvider?: AuthProvider, userTokenClient?: UserTokenClient, options?: CloudAdapterOptions) {
+  constructor (authConfig?: AuthConfiguration, authProvider?: AuthProvider, userTokenClient?: UserTokenClient, options?: CloudAdapterOptions, outboundHostValidator?: OutboundUrlPolicy) {
     super()
     this.authConfig = authConfig = getAuthConfigWithDefaults(authConfig)
+    this.jwtMiddleware = authorizeJWT(authConfig)
     this.connectionManager = new MsalConnectionManager(undefined, undefined, authConfig)
     this._options = resolveCloudAdapterOptions(options)
+    this._hostValidator = outboundHostValidator ?? createOutboundHostValidator()
 
     // Install a CloudAdapter-aware default `onTurnError` that honors
     // `emitStackTrace`. The base class default only logs the message; we
@@ -321,6 +333,8 @@ export class CloudAdapter extends BaseAdapter {
     identity: JwtPayload,
     headers?: HeaderPropagationCollection
   ): Promise<ConnectorClient> {
+    this.ensureOutboundServiceUrlAllowed(serviceUrl)
+
     return trace(AdapterTraceDefinitions.createConnectorClient, async ({ record }) => {
       record({ serviceUrl, scopes: [scope] })
 
@@ -349,6 +363,8 @@ export class CloudAdapter extends BaseAdapter {
     identity: JwtPayload,
     activity: Activity,
     headers?: HeaderPropagationCollection) {
+    this.ensureOutboundServiceUrlAllowed(activity.serviceUrl)
+
     return trace(AdapterTraceDefinitions.createConnectorClient, async ({ record }) => {
       if (!identity?.aud) {
         // anonymous
@@ -425,6 +441,24 @@ export class CloudAdapter extends BaseAdapter {
     } as JwtPayload
   }
 
+  /**
+   * Authorizes an incoming web request using this adapter's resolved authentication configuration.
+   * @param req The incoming request.
+   * @param res The outgoing response.
+   * @param next Callback invoked after successful authorization.
+   */
+  public async authorizeRequest (req: Request, res: WebResponse, next: NextFunction): Promise<void> {
+    await this.jwtMiddleware(req, res, next)
+  }
+
+  /**
+   * Gets the client ID used by this adapter's default authentication connection.
+   * @returns The configured client ID, or `undefined` for anonymous development configuration.
+   */
+  public getClientId (): string | undefined {
+    return this.authConfig.clientId
+  }
+
   /**
    * Sets the agent name for M365 agent header propagation.
    * @param agentName The human-friendly agent name to set for header propagation.
@@ -692,6 +726,8 @@ export class CloudAdapter extends BaseAdapter {
    * should be rejected with a 400.
    */
   private validateServiceUrl (identity: JwtPayload | undefined, activity: Activity): boolean {
+    if (!this.isOutboundServiceUrlAllowed(activity.serviceUrl)) return false
+
     if (!identity) return true
     if (!activity.serviceUrl) return true
 
@@ -709,7 +745,7 @@ export class CloudAdapter extends BaseAdapter {
 
     const safeClaim = sanitizeForLog(claimValue)
     const safeServiceUrl = sanitizeForLog(activity.serviceUrl)
-    if (this._options.validateServiceUrl) {
+    if (this._hostValidator.enabled || this._options.validateServiceUrl) {
       logger.error(`Invalid service URL Claim='${safeClaim}', ServiceUrl='${safeServiceUrl}'`)
       return false
     }
@@ -717,6 +753,23 @@ export class CloudAdapter extends BaseAdapter {
     return true
   }
 
+  /**
+   * Applies the shared outbound host policy.
+   */
+  private isOutboundServiceUrlAllowed (serviceUrl: string | undefined): boolean {
+    if (!this._hostValidator.enabled || !serviceUrl || this._hostValidator.isAllowed(serviceUrl)) return true
+
+    logger.warn(`ServiceUrl host is not in the configured allowed hosts. ServiceUrl='${sanitizeForLog(serviceUrl)}'`)
+    return false
+  }
+
+  /** Ensures connector-client creation cannot bypass the outbound host policy. */
+  private ensureOutboundServiceUrlAllowed (serviceUrl: string | undefined): void {
+    if (!this.isOutboundServiceUrlAllowed(serviceUrl)) {
+      throw ExceptionHelper.generateException(Error, Errors.OutboundServiceUrlNotAllowed)
+    }
+  }
+
   /**
    * Updates an activity.
    * @param context - The TurnContext for the current turn.