@microsoft/agents-hosting 1.6.1 → 1.7.0-beta.5.g67b2005119

package/src/auth/MemoryCache.ts

@@ -6,7 +6,7 @@ const CACHE_PURGE_INTERVAL = 60000 // 60 seconds
 
 /**
  * Simple in-memory cache with TTL support.
- * This is used to store authentication tokens for Agentic Identity scenarios only!
+ * This is used to store authentication tokens.
  */
 export class MemoryCache<T> {
   private cache = new Map<string, { value: T; validUntil: number }>()
@@ -22,11 +22,17 @@ export class MemoryCache<T> {
     }
   }
 
+  clear (): void {
+    this.cache.clear()
+    this.destroy()
+  }
+
   set (key: string, value: T, ttlSeconds: number): void {
     const validUntil = Date.now() + (ttlSeconds * 1000)
     this.cache.set(key, { value, validUntil })
     if (!this.purgeInterval) {
       this.purgeInterval = setInterval(() => this.purge(), CACHE_PURGE_INTERVAL)
+      this.purgeInterval.unref?.()
     }
   }
 

package/src/auth/authConfiguration.ts

@@ -3,12 +3,13 @@
  * Licensed under the MIT License.
  */
 
-import type { ConnectionMapItem } from './msalConnectionManager'
 import { debug, redactString, redactScopes, redactUrl } from '@microsoft/agents-telemetry'
-import { loadEnvSettings, AuthConfiguration, envParser, envParserUtils, LoadEnv, applyDefaultSettings, DEFAULT_CONNECTION_MAP, ConnectionKeys, ConnectionMapKeys } from './settings'
+import { loadEnvSettings, AuthConfiguration, envParser, envParserUtils, LoadEnv, applyDefaultSettings, DEFAULT_CONNECTION_MAP, ConnectionKeys, ConnectionMapKeys, ConnectionMapItem } from './settings'
 
-export { type AuthConfiguration, AuthType, resolveAuthority } from './settings'
+export { type AuthConfiguration, type ConnectionSettings, type ConnectionSettingsBase, type MsalConnectionSettings, type SidecarConnectionSettings, AuthType, resolveAuthority, type ConnectionMapItem, resolveAuthType } from './settings'
 import { prune } from '../utils'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
 
 const logger = debug('agents:authConfiguration')
 
@@ -36,8 +37,15 @@ function summarizeAuthConfiguration (authConfig: AuthConfiguration) {
       idpmResource: config.idpmResource ? redactUrl(config.idpmResource) : undefined,
       connectionName: config.connectionName,
       altBlueprintConnectionName: config.altBlueprintConnectionName,
+      alternateBlueprintConnectionName: undefined, // Alias of altBlueprintConnectionName, avoid logging duplicate info
       azureRegion: config.azureRegion,
       sendX5C: config.sendX5C,
+      sidecarBaseUrl: config.sidecarBaseUrl ? redactUrl(config.sidecarBaseUrl) : undefined,
+      serviceName: config.serviceName,
+      blueprintServiceName: config.blueprintServiceName,
+      bypassLocalNetworkRestriction: config.bypassLocalNetworkRestriction,
+      requestTimeout: config.requestTimeout,
+      retryCount: config.retryCount,
       // Don't log the following properties
       authority: undefined, // Deprecated, same as authorityEndpoint, avoid logging duplicate info
       FICClientId: undefined, // Deprecated, same as federatedClientId, avoid logging duplicate info
@@ -82,11 +90,24 @@ const connectionsEnv = {
       return { key: 'scopes', value: this.scopes(value)?.value } // redirect with single scope
     },
     altBlueprintConnectionName: envParserUtils.bypass,
+    alternateBlueprintConnectionName: (value) => ({ key: 'altBlueprintConnectionName', value }), // .NET parity alias
     WIDAssertionFile: envParserUtils.bypass,
     federatedTokenFile: envParserUtils.bypass,
     idpmResource: envParserUtils.bypass,
     azureRegion: envParserUtils.bypass,
     sendX5C: (value) => ({ value: value === 'true' }),
+    sidecarBaseUrl: envParserUtils.bypass,
+    serviceName: envParserUtils.bypass,
+    blueprintServiceName: envParserUtils.bypass,
+    bypassLocalNetworkRestriction: (value) => ({ value: value === 'true' }),
+    requestTimeout: (value) => {
+      const n = parseInt(value, 10)
+      return { value: Number.isFinite(n) && n > 0 ? n : undefined }
+    },
+    retryCount: (value) => {
+      const n = parseInt(value, 10)
+      return { value: Number.isFinite(n) && n >= 0 ? n : undefined }
+    },
     issuers (value) {
       if (value.includes(',')) {
         return { value: value.split(',').map(s => s.trim()).filter(Boolean) }
@@ -99,12 +120,12 @@ const connectionsEnv = {
     const map = connectionsMap ?? connectionsMapEnv.connectionsMap
     const name = map?.find((item) => item.serviceUrl === '*')?.connection
     if (!name) {
-      throw new Error('No default connection found in environment connections.')
+      throw ExceptionHelper.generateException(Error, Errors.NoDefaultConnectionFound)
     }
 
     const connection = conn?.get(name ?? '')
     if (!connection) {
-      throw new Error(`Connection "${name}" not found in environment connections.`)
+      throw ExceptionHelper.generateException(Error, Errors.ConnectionNotFoundInEnvironment, undefined, { connectionName: name })
     }
 
     return applyDefaultSettings({ ...connection, connections: conn, connectionsMap: map })
@@ -205,12 +226,19 @@ const legacyBotFrameworkEnv = {
     authorityEndpoint: envParserUtils.redirect(connectionsEnv.parser, 'authorityEndpoint'),
     scope: envParserUtils.redirect(connectionsEnv.parser, 'scopes'),
     altBlueprintConnectionName: envParserUtils.redirect(connectionsEnv.parser, 'altBlueprintConnectionName'),
+    alternateBlueprintConnectionName: envParserUtils.redirect(connectionsEnv.parser, 'altBlueprintConnectionName'),
     WIDAssertionFile: envParserUtils.redirect(connectionsEnv.parser, 'WIDAssertionFile'),
     azureRegion: envParserUtils.redirect(connectionsEnv.parser, 'azureRegion'),
     sendX5C: envParserUtils.redirect(connectionsEnv.parser, 'sendX5C'),
     authType: envParserUtils.redirect(connectionsEnv.parser, 'authType'),
     federatedTokenFile: envParserUtils.redirect(connectionsEnv.parser, 'federatedTokenFile'),
     idpmResource: envParserUtils.redirect(connectionsEnv.parser, 'idpmResource'),
+    sidecarBaseUrl: envParserUtils.redirect(connectionsEnv.parser, 'sidecarBaseUrl'),
+    serviceName: envParserUtils.redirect(connectionsEnv.parser, 'serviceName'),
+    blueprintServiceName: envParserUtils.redirect(connectionsEnv.parser, 'blueprintServiceName'),
+    bypassLocalNetworkRestriction: envParserUtils.redirect(connectionsEnv.parser, 'bypassLocalNetworkRestriction'),
+    requestTimeout: envParserUtils.redirect(connectionsEnv.parser, 'requestTimeout'),
+    retryCount: envParserUtils.redirect(connectionsEnv.parser, 'retryCount'),
   }),
   process (env: LoadEnv) {
     return legacyPrefixEnv.process.call(this, env)
@@ -233,12 +261,19 @@ const legacyPrefixEnv = {
     authorityEndpoint: envParserUtils.redirect(connectionsEnv.parser, 'authorityEndpoint'),
     scope: envParserUtils.redirect(connectionsEnv.parser, 'scopes'),
     altBlueprintConnectionName: envParserUtils.redirect(connectionsEnv.parser, 'altBlueprintConnectionName'),
+    alternateBlueprintConnectionName: envParserUtils.redirect(connectionsEnv.parser, 'altBlueprintConnectionName'),
     WIDAssertionFile: envParserUtils.redirect(connectionsEnv.parser, 'WIDAssertionFile'),
     azureRegion: envParserUtils.redirect(connectionsEnv.parser, 'azureRegion'),
     sendX5C: envParserUtils.redirect(connectionsEnv.parser, 'sendX5C'),
     authType: envParserUtils.redirect(connectionsEnv.parser, 'authType'),
     federatedTokenFile: envParserUtils.redirect(connectionsEnv.parser, 'federatedTokenFile'),
     idpmResource: envParserUtils.redirect(connectionsEnv.parser, 'idpmResource'),
+    sidecarBaseUrl: envParserUtils.redirect(connectionsEnv.parser, 'sidecarBaseUrl'),
+    serviceName: envParserUtils.redirect(connectionsEnv.parser, 'serviceName'),
+    blueprintServiceName: envParserUtils.redirect(connectionsEnv.parser, 'blueprintServiceName'),
+    bypassLocalNetworkRestriction: envParserUtils.redirect(connectionsEnv.parser, 'bypassLocalNetworkRestriction'),
+    requestTimeout: envParserUtils.redirect(connectionsEnv.parser, 'requestTimeout'),
+    retryCount: envParserUtils.redirect(connectionsEnv.parser, 'retryCount'),
   }),
   process (env: LoadEnv, prefix?: string) {
     const settings: Partial<AuthConfiguration> = {}
@@ -326,7 +361,7 @@ export const loadAuthConfigFromEnv = (cnxName?: string): AuthConfiguration => {
   // No connections provided, we need to populate the connections map with the old config settings
   const result = applyDefaultSettings(cnxName?.trim() ? legacyPrefixEnv.process(globalEnv.env, cnxName) : globalEnv.legacyPrefixSettings)
   if (cnxName && !result.clientId) {
-    throw new Error(`ClientId not found for connection: ${cnxName}`)
+    throw ExceptionHelper.generateException(Error, Errors.ClientIdNotFoundForConnection, undefined, { connectionName: cnxName })
   }
 
   logger.info('Auth settings loaded from environment', {

package/src/auth/authConstants.ts

@@ -2,10 +2,10 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */
-export const ApxLocalScope = 'c16e153d-5d2b-4c21-b7f4-b05ee5d516f1/.default'
-export const ApxDevScope = '0d94caae-b412-4943-8a68-83135ad6d35f/.default'
-export const ApxProductionScope = '5a807f24-c9de-44ee-a3a7-329e88a00ffc/.default'
-export const ApxGCCScope = 'c9475445-9789-4fef-9ec5-cde4a9bcd446/.default'
-export const ApxGCCHScope = '6f669b9e-7701-4e2b-b624-82c9207fde26/.default'
-export const ApxDoDScope = '0a069c81-8c7c-4712-886b-9c542d673ffb/.default'
-export const ApxGallatinScope = 'bd004c8e-5acf-4c48-8570-4e7d46b2f63b/.default'
+export const ApxLocalScope: string = 'c16e153d-5d2b-4c21-b7f4-b05ee5d516f1/.default'
+export const ApxDevScope: string = '0d94caae-b412-4943-8a68-83135ad6d35f/.default'
+export const ApxProductionScope: string = '5a807f24-c9de-44ee-a3a7-329e88a00ffc/.default'
+export const ApxGCCScope: string = 'c9475445-9789-4fef-9ec5-cde4a9bcd446/.default'
+export const ApxGCCHScope: string = '6f669b9e-7701-4e2b-b624-82c9207fde26/.default'
+export const ApxDoDScope: string = '0a069c81-8c7c-4712-886b-9c542d673ffb/.default'
+export const ApxGallatinScope: string = 'bd004c8e-5acf-4c48-8570-4e7d46b2f63b/.default'

package/src/auth/{msalConnectionManager.ts → connectionManager.ts}

@@ -3,28 +3,58 @@
  * Licensed under the MIT License.
  */
 
-import { Activity, RoleTypes } from '@microsoft/agents-activity'
-import { debug } from '@microsoft/agents-telemetry'
-import { AuthConfiguration, AuthType, resolveAuthority } from './authConfiguration'
+import { Activity, ExceptionHelper, RoleTypes } from '@microsoft/agents-activity'
+import { debug, redactString } from '@microsoft/agents-telemetry'
+import { AuthConfiguration, AuthType, resolveAuthType } from './authConfiguration'
 import { Connections } from './connections'
-import { MsalTokenProvider } from './msalTokenProvider'
+import { AuthProvider } from './authProvider'
+import { MsalTokenProvider } from './msal/msalTokenProvider'
+import { SidecarAuthProvider } from './sidecar/sidecarAuthProvider'
 import { JwtPayload } from 'jsonwebtoken'
+import { Errors } from '../errorHelper'
+import type { ConnectionMapItem } from './settings'
 
 const logger = debug('agents:authorization:connections')
 
-export interface ConnectionMapItem {
-  audience?: string
-  serviceUrl: string
-  connection: string
-}
+/**
+ * Factory function that creates an {@link AuthProvider} instance from a connection's
+ * {@link AuthConfiguration}.
+ */
+export type AuthProviderFactory = (config: AuthConfiguration) => AuthProvider
+
+/**
+ * Default {@link AuthProviderFactory} that dispatches per-connection by `authType`: connections with
+ * `authType` set to `EntraAuthSideCar` use {@link SidecarAuthProvider}; all others use
+ * {@link MsalTokenProvider}.
+ * @param config The connection authentication configuration.
+ * @returns The auth provider for the connection.
+ */
+export const defaultAuthProviderFactory: AuthProviderFactory = (config: AuthConfiguration): AuthProvider =>
+  config?.authType === AuthType.EntraAuthSideCar
+    ? new SidecarAuthProvider(config)
+    : new MsalTokenProvider(config)
 
-export class MsalConnectionManager implements Connections {
-  private _connections: Map<string, MsalTokenProvider>
-  private _connectionsMap: ConnectionMapItem[]
-  private _serviceConnectionConfiguration: AuthConfiguration
-  private static readonly DEFAULT_CONNECTION = 'serviceConnection'
+/**
+ * Generic, provider-agnostic connection manager. Dispatches connections to any {@link AuthProvider}
+ * implementation produced by the supplied {@link AuthProviderFactory}, while owning the
+ * provider-independent connection routing logic (audience matching, service URL dispatch,
+ * `altBlueprintConnectionName` handling, default connection resolution).
+ */
+export class ConnectionManager implements Connections {
+  protected _connections: Map<string, AuthProvider>
+  protected _connectionsMap: ConnectionMapItem[]
+  protected _serviceConnectionConfiguration: AuthConfiguration
+  protected static readonly DEFAULT_CONNECTION = 'serviceConnection'
 
+  /**
+   * Creates a new {@link ConnectionManager}.
+   * @param providerFactory Factory used to instantiate an {@link AuthProvider} for each connection.
+   * @param connectionsConfigurations Map of connection names to their authentication configurations.
+   * @param connectionsMap Map items used to route activities to connections.
+   * @param configuration Fallback authentication configuration (used when the above are empty).
+   */
   constructor (
+    providerFactory: AuthProviderFactory = defaultAuthProviderFactory,
     connectionsConfigurations: Map<string, AuthConfiguration> = new Map(),
     connectionsMap: ConnectionMapItem[] = [],
     configuration: AuthConfiguration = {}) {
@@ -35,26 +65,16 @@ export class MsalConnectionManager implements Connections {
     const providedConnections = connectionsConfigurations.size > 0 ? connectionsConfigurations : (configuration.connections || new Map())
 
     for (const [name, config] of providedConnections) {
-      // Instantiate MsalTokenProvider for each connection
-      this._connections.set(name, new MsalTokenProvider(config))
-      if (name === MsalConnectionManager.DEFAULT_CONNECTION) {
+      this._connections.set(name, providerFactory(config))
+      if (name === ConnectionManager.DEFAULT_CONNECTION) {
         this._serviceConnectionConfiguration = config
       }
     }
 
     for (const [name, provider] of this._connections.entries()) {
       const cfg = provider.connectionSettings
-      const authType = cfg?.authType ??
-        (cfg?.certPemFile
-          ? AuthType.Certificate
-          : cfg?.clientSecret
-            ? AuthType.ClientSecret
-            : cfg?.WIDAssertionFile
-              ? AuthType.WorkloadIdentity
-              : cfg?.federatedClientId || cfg?.FICClientId
-                ? AuthType.FederatedCredentials
-                : 'none')
-      logger.debug('connection "%s" clientId=%s tenantId=%s authType=%s', name, cfg?.clientId ?? '<none>', cfg?.tenantId ?? '<none>', authType)
+      const authType = resolveAuthType(cfg)
+      logger.debug('connection "%s" clientId=%s tenantId=%s authType=%s', name, redactString(cfg?.clientId, true) ?? '<none>', redactString(cfg?.tenantId, true) ?? '<none>', authType)
     }
 
     for (const item of this._connectionsMap) {
@@ -67,10 +87,10 @@ export class MsalConnectionManager implements Connections {
    * @param connectionName The name of the connection.
    * @returns The OAuth connection for the agent.
    */
-  getConnection (connectionName: string): MsalTokenProvider {
+  getConnection (connectionName: string): AuthProvider {
     const conn = this._connections.get(connectionName)
     if (!conn) {
-      throw new Error(`Connection not found: ${connectionName}`)
+      throw ExceptionHelper.generateException(Error, Errors.ConnectionNotFound, undefined, { connectionName })
     }
     return this.applyConnectionDefaults(conn)
   }
@@ -79,9 +99,9 @@ export class MsalConnectionManager implements Connections {
    * Get the default OAuth connection for the agent.
    * @returns The default OAuth connection for the agent.
    */
-  getDefaultConnection (): MsalTokenProvider {
+  getDefaultConnection (): AuthProvider {
     if (this._connections.size === 0) {
-      throw new Error('No connections found for this Agent in the Connections Configuration.')
+      throw ExceptionHelper.generateException(Error, Errors.NoConnectionsFoundInConfiguration)
     }
 
     // Return the wildcard map item instance.
@@ -91,7 +111,7 @@ export class MsalConnectionManager implements Connections {
       }
     }
 
-    const conn = this._connections.values().next().value as MsalTokenProvider
+    const conn = this._connections.values().next().value as AuthProvider
 
     return this.applyConnectionDefaults(conn)
   }
@@ -114,9 +134,9 @@ export class MsalConnectionManager implements Connections {
    * ServiceUrl is:  A regex to match with, or "*" for any serviceUrl value.
    * Connection is: A name in the 'Connections' list.
    */
-  getTokenProvider (identity: JwtPayload, serviceUrl: string): MsalTokenProvider {
+  getTokenProvider (identity: JwtPayload, serviceUrl: string): AuthProvider {
     if (!identity) {
-      throw new Error('Identity is required to get the token provider.')
+      throw ExceptionHelper.generateException(Error, Errors.IdentityRequiredForTokenProvider)
     }
 
     let audience
@@ -126,7 +146,7 @@ export class MsalConnectionManager implements Connections {
       audience = identity.aud
     }
 
-    if (!audience || !serviceUrl) throw new Error('Audience and Service URL are required to get the token provider.')
+    if (!audience || !serviceUrl) throw ExceptionHelper.generateException(Error, Errors.AudienceAndServiceUrlRequiredForTokenProvider)
 
     if (this._connectionsMap.length === 0) {
       logger.debug('no connectionsMap, using default connection for serviceUrl=%s', serviceUrl)
@@ -154,7 +174,7 @@ export class MsalConnectionManager implements Connections {
         }
       }
     }
-    throw new Error(`No connection found for audience: ${audience} and serviceUrl: ${serviceUrl}`)
+    throw ExceptionHelper.generateException(Error, Errors.NoConnectionForAudienceAndServiceUrl, undefined, { audience: String(audience), serviceUrl })
   }
 
   /**
@@ -163,7 +183,7 @@ export class MsalConnectionManager implements Connections {
    * @param activity The activity.
    * @returns The TokenProvider for the connection.
    */
-  getTokenProviderFromActivity (identity: JwtPayload, activity: Activity): MsalTokenProvider {
+  getTokenProviderFromActivity (identity: JwtPayload, activity: Activity): AuthProvider {
     let connection = this.getTokenProvider(identity, activity.serviceUrl || '')
 
     // This is for the case where the Agentic BlueprintId is not the same as the AppId
@@ -186,29 +206,13 @@ export class MsalConnectionManager implements Connections {
     return this._serviceConnectionConfiguration
   }
 
-  private applyConnectionDefaults (conn: MsalTokenProvider): MsalTokenProvider {
-    if (conn.connectionSettings) {
-      conn.connectionSettings.authorityEndpoint ??= conn.connectionSettings.authority || 'https://login.microsoftonline.com'
-      conn.connectionSettings.authority ??= conn.connectionSettings.authorityEndpoint
-      conn.connectionSettings.issuers ??= [
-        'https://api.botframework.com',
-        `${resolveAuthority('https://sts.windows.net', conn.connectionSettings.tenantId)}/`,
-        `${resolveAuthority(conn.connectionSettings.authorityEndpoint, conn.connectionSettings.tenantId)}/v2.0`
-      ]
-      // For backward compatibility
-      if (conn.connectionSettings.federatedClientId) {
-        conn.connectionSettings.FICClientId = conn.connectionSettings.federatedClientId
-      }
-
-      if (conn.connectionSettings.scopes?.length) {
-        conn.connectionSettings.scope = conn.connectionSettings.scopes?.[0]
-      }
-
-      if (conn.connectionSettings.authorityEndpoint) {
-        conn.connectionSettings.authority = conn.connectionSettings.authorityEndpoint
-      }
-    }
-
+  /**
+   * Applies provider-specific defaults to a resolved connection before returning it. The generic
+   * base performs no mutation; provider-specific managers may override this.
+   * @param conn The resolved auth provider.
+   * @returns The auth provider, possibly with defaults applied.
+   */
+  protected applyConnectionDefaults (conn: AuthProvider): AuthProvider {
     return conn
   }
 }

package/src/auth/index.ts

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

package/src/auth/jwt-middleware.ts

@@ -4,13 +4,24 @@
  */
 
 import { AuthConfiguration, resolveAuthority } from './authConfiguration'
-import { Response, NextFunction } from 'express'
 import { Request } from './request'
+import { WebResponse, NextFunction } from '../interfaces/webResponse'
+import { Errors } from '../errorHelper'
+import { ExceptionHelper } from '@microsoft/agents-activity'
 import jwksRsa, { JwksClient, SigningKey } from 'jwks-rsa'
 import jwt, { JwtHeader, JwtPayload, SignCallback, GetPublicKeyOrSecret } from 'jsonwebtoken'
 import { debug } from '@microsoft/agents-telemetry'
 
 const logger = debug('agents:jwt-middleware')
+const jwksClients = new Map<string, JwksClient>()
+const maxJwksClients = 100
+
+/**
+ * Clears process-wide JWKS clients.
+ */
+export function clearJwksClients (): void {
+  jwksClients.clear()
+}
 
 /**
  * Builds the JWKS URI for the given token issuer and auth configuration.
@@ -24,6 +35,26 @@ export function buildJwksUri (iss: string, authConfig: AuthConfiguration): strin
     : `${resolveAuthority(authConfig.authorityEndpoint ?? authConfig.authority, authConfig.tenantId)}/discovery/v2.0/keys`
 }
 
+export function getJwksClient (jwksUri: string): JwksClient {
+  // Check if a client for this JWKS URI already exists in the cache.
+  let client = jwksClients.get(jwksUri)
+  if (!client) {
+    client = jwksRsa({ jwksUri })
+    jwksClients.set(jwksUri, client)
+    while (jwksClients.size > maxJwksClients) {
+      const oldestKey = jwksClients.keys().next().value
+      if (oldestKey === undefined) {
+        break
+      }
+      jwksClients.delete(oldestKey)
+    }
+  } else {
+    jwksClients.delete(jwksUri)
+    jwksClients.set(jwksUri, client)
+  }
+  return client
+}
+
 /**
  * Verifies the JWT token.
  * @param raw The raw JWT token.
@@ -35,7 +66,7 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
   logger.debug('jwt.decode ', JSON.stringify(payload))
 
   if (!payload) {
-    throw new Error('invalid token')
+    throw ExceptionHelper.generateException(Error, Errors.InvalidJwtToken)
   }
   const audience = payload.aud
 
@@ -44,7 +75,7 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
     : undefined
 
   if (!matchingEntry) {
-    const err = new Error('Audience mismatch')
+    const err = ExceptionHelper.generateException(Error, Errors.JwtAudienceMismatch)
     logger.error(err.message, audience)
     throw err
   }
@@ -55,9 +86,10 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
   const jwksUri = buildJwksUri(payload.iss as string, authConfig)
 
   logger.debug(`fetching keys from ${jwksUri}`)
-  const jwksClient: JwksClient = jwksRsa({ jwksUri })
+  const jwksClient = getJwksClient(jwksUri)
 
   const getKey: GetPublicKeyOrSecret = (header: JwtHeader, callback: SignCallback) => {
+    // Retrieve the public, issuer-wide signing key from the JWKS endpoint using the kid from the token header.
     jwksClient.getSigningKey(header.kid, (err: Error | null, key: SigningKey | undefined): void => {
       if (err) {
         logger.error('jwksClient.getSigningKey ', JSON.stringify(err))
@@ -89,13 +121,78 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
   })
 }
 
+/**
+ * Determines whether an `Authorization` header value is present (non-empty).
+ *
+ * The {@link Request} contract allows `string | string[] | undefined` because
+ * different web frameworks surface headers differently. This treats an empty
+ * string or empty array as "absent" so callers can distinguish a missing header
+ * (anonymous / 401) from a present-but-malformed one (always 401).
+ * @param authorization The raw `Authorization` header value.
+ * @returns `true` when a non-empty header value is present.
+ */
+function hasAuthorizationHeader (authorization: string | string[] | undefined): boolean {
+  if (Array.isArray(authorization)) {
+    return authorization.some((value) => typeof value === 'string' && value.trim().length > 0)
+  }
+  return typeof authorization === 'string' && authorization.trim().length > 0
+}
+
+/**
+ * Parses a single `Authorization` header value and returns its bearer token.
+ *
+ * Validates the `Bearer <token>` scheme, returning `undefined` for anything
+ * malformed (wrong scheme, missing token, or extra whitespace-delimited parts).
+ * @param headerValue A single `Authorization` header value.
+ * @returns The bearer token, or `undefined` if the value is absent or malformed.
+ */
+function parseBearerValue (headerValue: string | undefined): string | undefined {
+  if (typeof headerValue !== 'string') {
+    return undefined
+  }
+  const parts = headerValue.trim().split(/\s+/)
+  if (parts.length !== 2) {
+    return undefined
+  }
+  const [scheme, token] = parts
+  if (scheme.toLowerCase() !== 'bearer' || !token) {
+    return undefined
+  }
+  return token
+}
+
+/**
+ * Extracts the bearer token from a raw `Authorization` header value.
+ *
+ * On Node's core HTTP parser (which both Express and Fastify use) `Authorization`
+ * is always surfaced as a single string holding the *first* header line —
+ * duplicate `Authorization` headers are discarded, not comma-joined. The
+ * `string[]` case is handled only because the {@link Request} contract permits
+ * it for non-Node frameworks; when an array is supplied, every entry is inspected
+ * and the first valid `Bearer <token>` is returned (the bearer value is not
+ * assumed to be first). Returns `undefined` for anything malformed so the caller
+ * can emit a consistent 401 instead of throwing.
+ * @param authorization The raw `Authorization` header value.
+ * @returns The bearer token, or `undefined` if the header is absent or malformed.
+ */
+function extractBearerToken (authorization: string | string[] | undefined): string | undefined {
+  const values = Array.isArray(authorization) ? authorization : [authorization]
+  for (const value of values) {
+    const token = parseBearerValue(value)
+    if (token) {
+      return token
+    }
+  }
+  return undefined
+}
+
 /**
  * Middleware to authorize JWT tokens.
  * @param authConfig The authentication configuration.
  * @returns An Express middleware function.
  */
 export const authorizeJWT = (authConfig: AuthConfiguration) => {
-  return async function (req: Request, res: Response, next: NextFunction) {
+  return async function (req: Request, res: WebResponse, next: NextFunction) {
     let failed = false
     logger.debug('authorizing jwt')
     if (req.method !== 'POST' && req.method !== 'GET') {
@@ -103,9 +200,8 @@ export const authorizeJWT = (authConfig: AuthConfiguration) => {
       logger.warn('Method not allowed', req.method)
       res.status(405).send({ 'jwt-auth-error': 'Method not allowed' })
     } else {
-      const authHeader = req.headers.authorization as string
-      if (authHeader) {
-        const token: string = authHeader.split(' ')[1] // Extract the token from the Bearer string
+      const token = extractBearerToken(req.headers.authorization)
+      if (token) {
         try {
           const user = await verifyToken(token, authConfig)
           logger.debug('token verified for ', user)
@@ -113,8 +209,21 @@ export const authorizeJWT = (authConfig: AuthConfiguration) => {
         } catch (err: Error | any) {
           failed = true
           logger.error(err)
-          res.status(401).send({ 'jwt-auth-error': err.message })
+          // Emit only the human-readable description rather than the
+          // ExceptionHelper-formatted "[code] - description - helplink" string,
+          // so the wire format does not leak internal error codes or help links.
+          // Fall back to a stable string so a thrown non-Error (no description/
+          // message) never serializes to an empty `{}` and drops the detail.
+          const wireMessage: string = err?.description ?? err?.message ?? 'unauthorized'
+          res.status(401).send({ 'jwt-auth-error': wireMessage })
         }
+      } else if (hasAuthorizationHeader(req.headers.authorization)) {
+        // Header is present but not a well-formed `Bearer <token>` (e.g. wrong
+        // scheme, missing token, or an array value). Respond with a consistent
+        // 401 rather than letting malformed input throw before authorization.
+        failed = true
+        logger.warn('malformed authorization header')
+        res.status(401).send({ 'jwt-auth-error': 'invalid authorization header' })
       } else {
         if (!authConfig.clientId && process.env.NODE_ENV !== 'production') {
           logger.info('using anonymous auth')

package/src/auth/msal/msalConnectionManager.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthConfiguration, resolveAuthority } from '../authConfiguration'
+import type { ConnectionMapItem } from '../settings'
+import { AuthProvider } from '../authProvider'
+import { ConnectionManager, defaultAuthProviderFactory } from '../connectionManager'
+
+/**
+ * Connection manager backed by MSAL (and, for `EntraAuthSideCar` connections, the Entra sidecar
+ * provider). A thin convenience subclass of {@link ConnectionManager} that supplies the default
+ * provider factory and applies MSAL-specific connection defaults.
+ */
+export class MsalConnectionManager extends ConnectionManager {
+  constructor (
+    connectionsConfigurations: Map<string, AuthConfiguration> = new Map(),
+    connectionsMap: ConnectionMapItem[] = [],
+    configuration: AuthConfiguration = {}) {
+    super(defaultAuthProviderFactory, connectionsConfigurations, connectionsMap, configuration)
+  }
+
+  protected applyConnectionDefaults (conn: AuthProvider): AuthProvider {
+    if (conn.connectionSettings) {
+      conn.connectionSettings.authorityEndpoint ??= conn.connectionSettings.authority || 'https://login.microsoftonline.com'
+      conn.connectionSettings.authority ??= conn.connectionSettings.authorityEndpoint
+      conn.connectionSettings.issuers ??= [
+        'https://api.botframework.com',
+        `${resolveAuthority('https://sts.windows.net', conn.connectionSettings.tenantId)}/`,
+        `${resolveAuthority(conn.connectionSettings.authorityEndpoint, conn.connectionSettings.tenantId)}/v2.0`
+      ]
+      // For backward compatibility
+      if (conn.connectionSettings.federatedClientId) {
+        conn.connectionSettings.FICClientId = conn.connectionSettings.federatedClientId
+      }
+
+      if (conn.connectionSettings.scopes?.length) {
+        conn.connectionSettings.scope = conn.connectionSettings.scopes?.[0]
+      }
+
+      if (conn.connectionSettings.authorityEndpoint) {
+        conn.connectionSettings.authority = conn.connectionSettings.authorityEndpoint
+      }
+
+      // .NET parity alias: keep altBlueprintConnectionName and alternateBlueprintConnectionName in sync.
+      conn.connectionSettings.altBlueprintConnectionName ??= conn.connectionSettings.alternateBlueprintConnectionName
+      if (conn.connectionSettings.altBlueprintConnectionName) {
+        conn.connectionSettings.alternateBlueprintConnectionName = conn.connectionSettings.altBlueprintConnectionName
+      }
+    }
+
+    return conn
+  }
+}