@microsoft/agents-hosting 1.1.0-alpha.2 → 1.1.0-alpha.58

package/src/auth/authConfiguration.ts

@@ -3,6 +3,13 @@
  * Licensed under the MIT License.
  */
 
+import { debug } from '@microsoft/agents-activity/logger'
+import { ConnectionMapItem } from './msalConnectionManager'
+import objectPath from 'object-path'
+
+const logger = debug('agents:authConfiguration')
+const DEFAULT_CONNECTION = 'serviceConnection'
+
 /**
  * Represents the authentication configuration.
  */
@@ -15,7 +22,7 @@ export interface AuthConfiguration {
   /**
    * The client ID for the authentication configuration. Required in production.
    */
-  clientId: string
+  clientId?: string
 
   /**
    * The client secret for the authentication configuration.
@@ -35,7 +42,7 @@ export interface AuthConfiguration {
   /**
    * A list of valid issuers for the authentication configuration.
    */
-  issuers: string[]
+  issuers?: string[]
 
   /**
    * The connection name for the authentication configuration.
@@ -56,6 +63,28 @@ export interface AuthConfiguration {
    * see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
    */
   authority?: string
+
+  scope?: string
+
+  /**
+   * A map of connection names to their respective authentication configurations.
+   */
+  connections?: Map<string, AuthConfiguration>
+
+  /**
+   * A list of connection map items to map service URLs to connection names.
+   */
+  connectionsMap?: ConnectionMapItem[],
+
+  /**
+   * An optional alternative blueprint Connection name used when constructing a connector client.
+   */
+  altBlueprintConnectionName?: string
+
+  /**
+   * The path to K8s provided token.
+   */
+  WIDAssertionFile?: string
 }
 
 /**
@@ -83,44 +112,43 @@ export interface AuthConfiguration {
  * ```
  *
  */
-export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (cnxName?: string) => {
-  if (cnxName === undefined) {
-    const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
-    if (process.env.clientId === undefined && process.env.NODE_ENV === 'production') {
-      throw new Error('ClientId required in production')
-    }
-    return {
-      tenantId: process.env.tenantId,
-      clientId: process.env.clientId!,
-      clientSecret: process.env.clientSecret,
-      certPemFile: process.env.certPemFile,
-      certKeyFile: process.env.certKeyFile,
-      connectionName: process.env.connectionName,
-      FICClientId: process.env.FICClientId,
-      authority,
-      issuers: [
-        'https://api.botframework.com',
-        `https://sts.windows.net/${process.env.tenantId}/`,
-        `${authority}/${process.env.tenantId}/v2.0`
-      ],
-    }
+export const loadAuthConfigFromEnv = (cnxName?: string): AuthConfiguration => {
+  const envConnections = loadConnectionsMapFromEnv()
+  let authConfig: AuthConfiguration
+
+  if (envConnections.connectionsMap.length === 0) {
+    // No connections provided, we need to populate the connections map with the old config settings
+    authConfig = buildLegacyAuthConfig(cnxName)
+    envConnections.connections.set(DEFAULT_CONNECTION, authConfig)
+    envConnections.connectionsMap.push({
+      serviceUrl: '*',
+      connection: DEFAULT_CONNECTION,
+    })
   } else {
-    const authority = process.env[`${cnxName}_authorityEndpoint`] ?? 'https://login.microsoftonline.com'
-    return {
-      tenantId: process.env[`${cnxName}_tenantId`],
-      clientId: process.env[`${cnxName}_clientId`] ?? (() => { throw new Error(`ClientId not found for connection: ${cnxName}`) })(),
-      clientSecret: process.env[`${cnxName}_clientSecret`],
-      certPemFile: process.env[`${cnxName}_certPemFile`],
-      certKeyFile: process.env[`${cnxName}_certKeyFile`],
-      connectionName: process.env[`${cnxName}_connectionName`],
-      FICClientId: process.env[`${cnxName}_FICClientId`],
-      authority,
-      issuers: [
-        'https://api.botframework.com',
-        `https://sts.windows.net/${process.env[`${cnxName}_tenantId`]}/`,
-        `${authority}/${process.env[`${cnxName}_tenantId`]}/v2.0`
-      ]
+    // There are connections provided, use the default or specified connection
+    if (cnxName) {
+      const entry = envConnections.connections.get(cnxName)
+      if (entry) {
+        authConfig = entry
+      } else {
+        throw new Error(`Connection "${cnxName}" not found in environment.`)
+      }
+    } else {
+      const defaultItem = envConnections.connectionsMap.find((item) => item.serviceUrl === '*')
+      const defaultConn = defaultItem ? envConnections.connections.get(defaultItem.connection) : undefined
+      if (!defaultConn) {
+        throw new Error('No default connection found in environment connections.')
+      }
+      authConfig = defaultConn
     }
+
+    authConfig.authority ??= 'https://login.microsoftonline.com'
+    authConfig.issuers ??= getDefaultIssuers(authConfig.tenantId ?? '', authConfig.authority)
+  }
+
+  return {
+    ...authConfig,
+    ...envConnections,
   }
 }
 
@@ -139,23 +167,201 @@ export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (c
  *
  */
 export const loadPrevAuthConfigFromEnv: () => AuthConfiguration = () => {
-  if (process.env.MicrosoftAppId === undefined && process.env.NODE_ENV === 'production') {
+  const envConnections = loadConnectionsMapFromEnv()
+  let authConfig: AuthConfiguration = {}
+
+  if (envConnections.connectionsMap.length === 0) {
+    // No connections provided, we need to populate the connection map with the old config settings
+    if (process.env.MicrosoftAppId === undefined && process.env.NODE_ENV === 'production') {
+      throw new Error('ClientId required in production')
+    }
+    const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
+    authConfig = {
+      tenantId: process.env.MicrosoftAppTenantId,
+      clientId: process.env.MicrosoftAppId,
+      clientSecret: process.env.MicrosoftAppPassword,
+      certPemFile: process.env.certPemFile,
+      certKeyFile: process.env.certKeyFile,
+      connectionName: process.env.connectionName,
+      FICClientId: process.env.MicrosoftAppClientId,
+      authority,
+      scope: process.env.scope,
+      issuers: getDefaultIssuers(process.env.MicrosoftAppTenantId ?? '', authority),
+      altBlueprintConnectionName: process.env.altBlueprintConnectionName,
+      WIDAssertionFile: process.env.WIDAssertionFile,
+    }
+    envConnections.connections.set(DEFAULT_CONNECTION, authConfig)
+    envConnections.connectionsMap.push({
+      serviceUrl: '*',
+      connection: DEFAULT_CONNECTION,
+    })
+  } else {
+    // There are connections provided, use the default one.
+    const defaultItem = envConnections.connectionsMap.find((item) => item.serviceUrl === '*')
+    const defaultConn = defaultItem ? envConnections.connections.get(defaultItem.connection) : undefined
+    if (!defaultConn) {
+      throw new Error('No default connection found in environment connections.')
+    }
+    authConfig = defaultConn
+  }
+
+  authConfig.authority ??= 'https://login.microsoftonline.com'
+  authConfig.issuers ??= getDefaultIssuers(authConfig.tenantId ?? '', authConfig.authority)
+
+  return { ...authConfig, ...envConnections }
+}
+
+function loadConnectionsMapFromEnv () {
+  const envVars = process.env
+  const connections = new Map<string, AuthConfiguration>()
+  const connectionsMap: ConnectionMapItem[] = []
+
+  for (const [key, value] of Object.entries(envVars)) {
+    if (key.startsWith('connections__')) {
+      const parts = key.split('__')
+      if (parts.length >= 4 && parts[2] === 'settings') {
+        const connectionName = parts[1]
+        const propertyPath = parts.slice(3).join('.') // e.g., 'issuers.0' or 'clientId'
+
+        let config = connections.get(connectionName)
+        if (!config) {
+          config = {}
+          connections.set(connectionName, config)
+        }
+
+        objectPath.set(config, propertyPath, value)
+      }
+    } else if (key.startsWith('connectionsMap__')) {
+      const parts = key.split('__')
+      if (parts.length === 3) {
+        const index = parseInt(parts[1], 10)
+        const property = parts[2]
+
+        if (!connectionsMap[index]) {
+          connectionsMap[index] = { serviceUrl: '', connection: '' }
+        }
+
+        (connectionsMap[index] as any)[property] = value
+      }
+    }
+  }
+
+  if (connections.size === 0) {
+    logger.warn('No connections found in configuration.')
+  }
+
+  if (connectionsMap.length === 0) {
+    logger.warn('No connections map found in configuration.')
+    if (connections.size > 0) {
+      const firstEntry = connections.entries().next().value
+
+      if (firstEntry) {
+        const [firstKey] = firstEntry
+        // Provide a default connection map if none is specified
+        connectionsMap.push({
+          serviceUrl: '*',
+          connection: firstKey,
+        })
+      }
+    }
+  }
+
+  return {
+    connections,
+    connectionsMap,
+  }
+}
+
+/**
+ * Loads the authentication configuration from the provided config or from the environment variables
+ * providing default values for authority and issuers.
+ *
+ * @returns The authentication configuration.
+ * @throws Will throw an error if clientId is not provided in production.
+ *
+ * @example
+ * ```
+ * tenantId=your-tenant-id
+ * clientId=your-client-id
+ * clientSecret=your-client-secret
+ *
+ * certPemFile=your-cert-pem-file
+ * certKeyFile=your-cert-key-file
+ *
+ * FICClientId=your-FIC-client-id
+ *
+ * connectionName=your-connection-name
+ * authority=your-authority-endpoint
+ * ```
+ *
+ */
+export function getAuthConfigWithDefaults (config?: AuthConfiguration): AuthConfiguration {
+  if (!config) return loadAuthConfigFromEnv()
+
+  const providedConnections = config.connections && config.connectionsMap
+    ? { connections: config.connections, connectionsMap: config.connectionsMap }
+    : undefined
+
+  const connections = providedConnections ?? loadConnectionsMapFromEnv()
+
+  let mergedConfig: AuthConfiguration
+
+  if (connections && connections.connectionsMap?.length === 0) {
+    // No connections provided, we need to populate the connections map with the old config settings
+    mergedConfig = buildLegacyAuthConfig(undefined, config)
+    connections.connections?.set(DEFAULT_CONNECTION, mergedConfig)
+    connections.connectionsMap.push({ serviceUrl: '*', connection: DEFAULT_CONNECTION })
+  } else {
+    // There are connections provided, use the default connection
+    const defaultItem = connections.connectionsMap?.find((item) => item.serviceUrl === '*')
+    const defaultConn = defaultItem ? connections.connections?.get(defaultItem.connection) : undefined
+    if (!defaultConn) {
+      throw new Error('No default connection found in environment connections.')
+    }
+    mergedConfig = buildLegacyAuthConfig(undefined, defaultConn)
+  }
+
+  return {
+    ...mergedConfig,
+    ...connections,
+  }
+}
+
+function buildLegacyAuthConfig (envPrefix: string = '', customConfig?: AuthConfiguration): AuthConfiguration {
+  const prefix = envPrefix ? `${envPrefix}_` : ''
+  const authority = customConfig?.authority ?? process.env[`${prefix}authorityEndpoint`] ?? 'https://login.microsoftonline.com'
+
+  const clientId = customConfig?.clientId ?? process.env[`${prefix}clientId`]
+
+  if (!clientId && !envPrefix && process.env.NODE_ENV === 'production') {
     throw new Error('ClientId required in production')
   }
-  const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
+  if (!clientId && envPrefix) {
+    throw new Error(`ClientId not found for connection: ${envPrefix}`)
+  }
+
+  const tenantId = customConfig?.tenantId ?? process.env[`${prefix}tenantId`]
+
   return {
-    tenantId: process.env.MicrosoftAppTenantId,
-    clientId: process.env.MicrosoftAppId!,
-    clientSecret: process.env.MicrosoftAppPassword,
-    certPemFile: process.env.certPemFile,
-    certKeyFile: process.env.certKeyFile,
-    connectionName: process.env.connectionName,
-    FICClientId: process.env.MicrosoftAppClientId,
+    tenantId,
+    clientId: clientId!,
+    clientSecret: customConfig?.clientSecret ?? process.env[`${prefix}clientSecret`],
+    certPemFile: customConfig?.certPemFile ?? process.env[`${prefix}certPemFile`],
+    certKeyFile: customConfig?.certKeyFile ?? process.env[`${prefix}certKeyFile`],
+    connectionName: customConfig?.connectionName ?? process.env[`${prefix}connectionName`],
+    FICClientId: customConfig?.FICClientId ?? process.env[`${prefix}FICClientId`],
     authority,
-    issuers: [
-      'https://api.botframework.com',
-      `https://sts.windows.net/${process.env.MicrosoftAppTenantId}/`,
-      `${authority}/${process.env.MicrosoftAppTenantId}/v2.0`
-    ]
+    scope: customConfig?.scope ?? process.env[`${prefix}scope`],
+    issuers: customConfig?.issuers ?? getDefaultIssuers(tenantId as string, authority),
+    altBlueprintConnectionName: customConfig?.altBlueprintConnectionName ?? process.env[`${prefix}altBlueprintConnectionName`],
+    WIDAssertionFile: customConfig?.WIDAssertionFile ?? process.env[`${prefix}WIDAssertionFile`]
   }
 }
+
+function getDefaultIssuers (tenantId: string, authority: string) : string[] {
+  return [
+    'https://api.botframework.com',
+    `https://sts.windows.net/${tenantId}/`,
+    `${authority}/${tenantId}/v2.0`
+  ]
+}

package/src/auth/authConstants.ts

@@ -0,0 +1,11 @@
+/**
+ * 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'

package/src/auth/authProvider.ts

@@ -16,4 +16,35 @@ export interface AuthProvider {
    * @returns A promise that resolves to the access token.
    */
   getAccessToken: (authConfig: AuthConfiguration, scope: string) => Promise<string>
+
+  /**
+   * Get an access token for the agentic application
+   * @param agentAppInstanceId
+   * @returns a promise that resolves to the access token.
+   */
+  getAgenticApplicationToken: (agentAppInstanceId: string) => Promise<string>
+
+  /**
+   * Get an access token for the agentic instance
+   * @param agentAppInstanceId
+   * @returns a promise that resolves to the access token.
+   */
+  getAgenticInstanceToken: (agentAppInstanceId: string) => Promise<string>
+
+  /**
+   * Get an access token for the agentic user
+   * @param agentAppInstanceId
+   * @param upn
+   * @param scopes
+   * @returns a promise that resolves to the access token.
+   */
+  getAgenticUserToken: (agentAppInstanceId: string, upn: string, scopes: string[]) => Promise<string>
+
+  acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+  acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
+  acquireTokenOnBehalfOf (
+    authConfigOrScopes: AuthConfiguration | string[],
+    scopesOrOboAssertion?: string[] | string,
+    oboAssertion?: string
+  ): Promise<string>
 }

package/src/auth/connections.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity } from '@microsoft/agents-activity'
+import { AuthConfiguration } from './authConfiguration'
+import { AuthProvider } from './authProvider'
+
+export interface Connections {
+  /**
+ * Get the OAuth connection for the agent.
+ * @param name - The connection name. Must match a configured OAuth connection.
+ * @returns An AuthProvider instance.
+ * @throws {Error} If the connection name is not found.
+ */
+  getConnection: (name: string) => AuthProvider
+
+  /**
+   * Get the default OAuth connection for the agent.
+   * @returns An AuthProvider instance.
+   */
+  getDefaultConnection: () => AuthProvider
+
+  /**
+   * Get the OAuth token provider for the agent.
+   * @param audience - The audience.
+   * @param serviceUrl - The service url.
+   * @returns An AuthProvider instance.
+   */
+  getTokenProvider: (audience: string, serviceUrl: string) => AuthProvider
+
+  /**
+   * Get the OAuth token provider for the agent.
+   * @param audience - The audience.
+   * @param activity - The activity.
+   * @returns An AuthProvider instance.
+   */
+  getTokenProviderFromActivity: (audience: string, activity: Activity) => AuthProvider
+
+  /**
+   * Get the default connection configuration for the agent.
+   * @returns An Auth Configuration.
+   */
+  getDefaultConnectionConfiguration: () => AuthConfiguration
+}

package/src/auth/index.ts

@@ -1,5 +1,7 @@
 export * from './authConfiguration'
+export * from './authConstants'
 export * from './authProvider'
 export * from './msalTokenProvider'
 export * from './request'
 export * from './msalTokenCredential'
+export * from './msalConnectionManager'

package/src/auth/jwt-middleware.ts

@@ -19,18 +19,37 @@ const logger = debug('agents:jwt-middleware')
  * @returns A promise that resolves to the JWT payload.
  */
 const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtPayload> => {
-  const getKey: GetPublicKeyOrSecret = (header: JwtHeader, callback: SignCallback) => {
-    const payload = jwt.decode(raw) as JwtPayload
-    logger.debug('jwt.decode ', JSON.stringify(payload))
-    const jwksUri: string = payload.iss === 'https://api.botframework.com'
-      ? 'https://login.botframework.com/v1/.well-known/keys'
-      : `${config.authority}/${config.tenantId}/discovery/v2.0/keys`
+  const payload = jwt.decode(raw) as JwtPayload
+  logger.debug('jwt.decode ', JSON.stringify(payload))
+
+  if (!payload) {
+    throw new Error('invalid token')
+  }
+  const audience = payload.aud
+
+  const matchingEntry = config.connections && config.connections.size > 0
+    ? [...config.connections.entries()].find(([_, configuration]) => configuration.clientId === audience)
+    : undefined
+
+  if (!matchingEntry) {
+    const err = new Error('Audience mismatch')
+    logger.error(err.message, audience)
+    throw err
+  }
+
+  const [key, authConfig] = matchingEntry
+  logger.debug(`Audience found at key: ${key}`)
 
-    logger.debug(`fetching keys from ${jwksUri}`)
-    const jwksClient: JwksClient = jwksRsa({ jwksUri })
+  const jwksUri = payload.iss === 'https://api.botframework.com'
+    ? 'https://login.botframework.com/v1/.well-known/keys'
+    : `${authConfig.authority}/${authConfig.tenantId}/discovery/v2.0/keys`
 
+  logger.debug(`fetching keys from ${jwksUri}`)
+  const jwksClient: JwksClient = jwksRsa({ jwksUri })
+
+  const getKey: GetPublicKeyOrSecret = (header: JwtHeader, callback: SignCallback) => {
     jwksClient.getSigningKey(header.kid, (err: Error | null, key: SigningKey | undefined): void => {
-      if (err != null) {
+      if (err) {
         logger.error('jwksClient.getSigningKey ', JSON.stringify(err))
         logger.error(JSON.stringify(err))
         callback(err, undefined)
@@ -41,24 +60,22 @@ const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtP
     })
   }
 
-  return await new Promise((resolve, reject) => {
-    const verifyOptions: jwt.VerifyOptions = {
-      issuer: config.issuers as [string, ...string[]],
-      audience: [config.clientId!, 'https://api.botframework.com'],
-      ignoreExpiration: false,
-      algorithms: ['RS256'],
-      clockTolerance: 300
-    }
+  const verifyOptions: jwt.VerifyOptions = {
+    issuer: authConfig.issuers as [string, ...string[]],
+    audience: [authConfig.clientId!, 'https://api.botframework.com'],
+    ignoreExpiration: false,
+    algorithms: ['RS256'],
+    clockTolerance: 300
+  }
 
+  return await new Promise((resolve, reject) => {
     jwt.verify(raw, getKey, verifyOptions, (err, user) => {
-      if (err != null) {
+      if (err) {
         logger.error('jwt.verify ', JSON.stringify(err))
         reject(err)
         return
       }
-      const tokenClaims = user as JwtPayload
-
-      resolve(tokenClaims)
+      resolve(user as JwtPayload)
     })
   })
 }