@microsoft/agents-hosting 1.6.0-beta.9.gce9d8facd2 → 1.7.0-beta.1.g8bcd4f11a7

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, 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
 
-export class MsalConnectionManager implements Connections {
-  private _connections: Map<string, MsalTokenProvider>
-  private _connectionsMap: ConnectionMapItem[]
-  private _serviceConnectionConfiguration: AuthConfiguration
-  private static readonly DEFAULT_CONNECTION = 'serviceConnection'
+/**
+ * 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)
 
+/**
+ * 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,23 +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?.certPemFile
-        ? 'certificate'
-        : cfg?.clientSecret
-          ? 'clientSecret'
-          : cfg?.WIDAssertionFile || cfg?.FICClientId
-            ? 'workloadIdentity'
-            : '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) {
@@ -64,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)
   }
@@ -76,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.
@@ -88,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)
   }
@@ -111,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
@@ -123,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)
@@ -151,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 })
   }
 
   /**
@@ -160,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
@@ -183,15 +206,13 @@ export class MsalConnectionManager implements Connections {
     return this._serviceConnectionConfiguration
   }
 
-  private applyConnectionDefaults (conn: MsalTokenProvider): MsalTokenProvider {
-    if (conn.connectionSettings) {
-      conn.connectionSettings.authority ??= 'https://login.microsoftonline.com'
-      conn.connectionSettings.issuers ??= [
-        'https://api.botframework.com',
-        `${resolveAuthority('https://sts.windows.net', conn.connectionSettings.tenantId)}/`,
-        `${resolveAuthority(conn.connectionSettings.authority, conn.connectionSettings.tenantId)}/v2.0`
-      ]
-    }
+  /**
+   * 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

@@ -11,6 +11,15 @@ import jwt, { JwtHeader, JwtPayload, SignCallback, GetPublicKeyOrSecret } from '
 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.
@@ -21,7 +30,27 @@ const logger = debug('agents:jwt-middleware')
 export function buildJwksUri (iss: string, authConfig: AuthConfiguration): string {
   return iss === 'https://api.botframework.com'
     ? 'https://login.botframework.com/v1/.well-known/keys'
-    : `${resolveAuthority(authConfig.authority, authConfig.tenantId)}/discovery/v2.0/keys`
+    : `${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
 }
 
 /**
@@ -55,9 +84,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))

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

package/src/auth/msal/msalConnectionSettings.ts

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ConnectionSettingsBase } from '../settings'
+
+/**
+ * Connection settings for the MSAL-backed authentication providers (the default providers used for
+ * every {@link AuthType} except `EntraAuthSideCar`).
+ *
+ * @remarks
+ * Mirrors the .NET `Microsoft.Agents.Authentication.Msal.Model.ConnectionSettings` class. Node.js uses
+ * PEM certificate files (`certPemFile`/`certKeyFile`) rather than the Windows certificate store, so the
+ * .NET `CertThumbprint`/`CertSubjectName`/`CertStoreName`/`ValidCertificateOnly` settings have no JS
+ * equivalent; all other MSAL properties map one-to-one.
+ */
+export interface MsalConnectionSettings extends ConnectionSettingsBase {
+  /**
+   * The client secret for the authentication configuration.
+   */
+  clientSecret?: string
+
+  /**
+   * The path to the certificate PEM file.
+   */
+  certPemFile?: string
+
+  /**
+   * The path to the certificate key file.
+   */
+  certKeyFile?: string
+
+  /**
+   * Indicates whether to send the X5C param or not (for SNI authentication).
+   */
+  sendX5C?: boolean
+
+  /**
+   * @deprecated Use federatedClientId instead.
+   *
+   * The FIC (First-Party Integration Channel) client ID.
+   */
+  FICClientId?: string
+
+  /**
+   * @deprecated Use `authType` set to `'WorkloadIdentity'` and `federatedTokenFile` instead.
+   *
+   * The path to K8s provided token.
+   */
+  WIDAssertionFile?: string
+
+  /**
+   * The Azure region for ESTS-R regional token acquisition (e.g. 'westus', 'eastus').
+   * When set, MSAL routes token requests to the specified regional endpoint.
+   * See https://learn.microsoft.com/en-us/entra/msal/javascript/node/regional-authorities for details.
+   */
+  azureRegion?: string
+
+  /**
+   * The path to the federated token file used for Workload Identity authentication.
+   */
+  federatedTokenFile?: string
+
+  /**
+   * Sets the resource URL for Identity Proxy Manager (IDPM).
+   *
+   * @remarks
+   * Set this to the appropriate resource identifier when the application is running in an environment,
+   * such as a Foundry container, that exposes Managed Identity through a container-specific IMDS endpoint.
+   * This setting is only meaningful when using Identity Proxy Manager (AuthType.IdentityProxyManager) for authentication.
+   */
+  idpmResource?: string
+
+  /**
+   * The federated client ID for the authentication configuration, used for workload identity federation scenarios.
+   */
+  federatedClientId?: string
+}

package/src/auth/{msalTokenCredential.ts → msal/msalTokenCredential.ts}

@@ -1,5 +1,6 @@
 import { GetTokenOptions, TokenCredential } from '@azure/core-auth'
-import { AuthConfiguration, MsalTokenProvider } from './'
+import { AuthConfiguration } from '../authConfiguration'
+import { MsalTokenProvider } from './msalTokenProvider'
 import { debug } from '@microsoft/agents-telemetry'
 
 const logger = debug('agents:msal')