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

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

package/src/auth/msalConnectionManager.ts

@@ -0,0 +1,150 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity, RoleTypes } from '@microsoft/agents-activity'
+import { AuthConfiguration } from './authConfiguration'
+import { AuthProvider } from './authProvider'
+import { Connections } from './connections'
+import { MsalTokenProvider } from './msalTokenProvider'
+
+export interface ConnectionMapItem {
+  audience?: string
+  serviceUrl: string
+  connection: string
+}
+
+export class MsalConnectionManager implements Connections {
+  private _connections: Map<string, MsalTokenProvider>
+  private _connectionsMap: ConnectionMapItem[]
+  private _serviceConnectionConfiguration: AuthConfiguration
+  private static readonly DEFAULT_CONNECTION = 'serviceConnection'
+
+  constructor (
+    connectionsConfigurations: Map<string, AuthConfiguration> = new Map(),
+    connectionsMap: ConnectionMapItem[] = [],
+    configuration: AuthConfiguration = {}) {
+    this._connections = new Map()
+    this._connectionsMap = connectionsMap.length > 0 ? connectionsMap : (configuration.connectionsMap || [])
+    this._serviceConnectionConfiguration = {}
+
+    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._serviceConnectionConfiguration = config
+      }
+    }
+  }
+
+  /**
+   * Get the OAuth connection for the agent.
+   * @param connectionName The name of the connection.
+   * @returns The OAuth connection for the agent.
+   */
+  getConnection (connectionName: string): MsalTokenProvider {
+    const conn = this._connections.get(connectionName)
+    if (!conn) {
+      throw new Error(`Connection not found: ${connectionName}`)
+    }
+    return conn
+  }
+
+  /**
+   * Get the default OAuth connection for the agent.
+   * @returns The default OAuth connection for the agent.
+   */
+  getDefaultConnection (): MsalTokenProvider {
+    if (this._connections.size === 0) {
+      throw new Error('No connections found for this Agent in the Connections Configuration.')
+    }
+
+    // Return the wildcard map item instance.
+    for (const item of this._connectionsMap) {
+      if (item.serviceUrl === '*' && !item.audience) {
+        return this.getConnection(item.connection)
+      }
+    }
+
+    return this._connections.values().next().value as MsalTokenProvider
+  }
+
+  /**
+   * Finds a connection based on a map.
+   *
+   * @param audience The audience.
+   * @param serviceUrl The service URL.
+   * @returns The TokenProvider for the connection.
+   *
+   * @remarks
+   * Example environment variables:
+   * connectionsMap__0__connection=seviceConnection
+   * connectionsMap__0__serviceUrl=http://*..botframework.com/*
+   * connectionsMap__0__audience=optional
+   * connectionsMap__1__connection=agentic
+   * connectionsMap__1__serviceUrl=agentic
+   *
+   * ServiceUrl is:  A regex to match with, or "*" for any serviceUrl value.
+   * Connection is: A name in the 'Connections' list.
+   */
+  getTokenProvider (audience: string, serviceUrl: string): MsalTokenProvider {
+    if (!audience || !serviceUrl) throw new Error('Audience and Service URL are required to get the token provider.')
+
+    if (this._connectionsMap.length === 0) {
+      return this.getDefaultConnection()
+    }
+
+    for (const item of this._connectionsMap) {
+      let audienceMatch = true
+
+      // if we have an audience to match against, match it.
+      if (item.audience && audience) {
+        audienceMatch = item.audience === audience
+      }
+
+      if (audienceMatch) {
+        if (item.serviceUrl === '*' || !item.serviceUrl) {
+          return this.getConnection(item.connection)
+        }
+
+        const regex = new RegExp(item.serviceUrl, 'i')
+        if (regex.test(serviceUrl)) {
+          return this.getConnection(item.connection)
+        }
+      }
+    }
+    throw new Error(`No connection found for audience: ${audience} and serviceUrl: ${serviceUrl}`)
+  }
+
+  /**
+   * Finds a connection based on an activity's blueprint.
+   * @param audience The audience.
+   * @param activity The activity.
+   * @returns The TokenProvider for the connection.
+   */
+  getTokenProviderFromActivity (audience: string, activity: Activity): AuthProvider {
+    let connection = this.getTokenProvider(audience, activity.serviceUrl || '')
+
+    // This is for the case where the Agentic BlueprintId is not the same as the AppId
+    if (connection &&
+      (activity.recipient?.role === RoleTypes.AgenticIdentity ||
+        activity.recipient?.role === RoleTypes.AgenticUser)) {
+      if (connection.connectionSettings?.altBlueprintConnectionName &&
+          connection.connectionSettings.altBlueprintConnectionName.trim() !== '') {
+        connection = this.getConnection(connection.connectionSettings?.altBlueprintConnectionName as string)
+      }
+    }
+    return connection
+  }
+
+  /**
+   * Get the default connection configuration for the agent.
+   * @returns The default connection configuration for the agent.
+   */
+  getDefaultConnectionConfiguration (): AuthConfiguration {
+    return this._serviceConnectionConfiguration
+  }
+}

package/src/auth/msalTokenProvider.ts

@@ -4,10 +4,12 @@
  */
 
 import { ConfidentialClientApplication, LogLevel, ManagedIdentityApplication, NodeSystemOptions } from '@azure/msal-node'
+import axios from 'axios'
 import { AuthConfiguration } from './authConfiguration'
 import { AuthProvider } from './authProvider'
 import { debug } from '@microsoft/agents-activity/logger'
 import { v4 } from 'uuid'
+import { MemoryCache } from './MemoryCache'
 
 import fs from 'fs'
 import crypto from 'crypto'
@@ -19,28 +21,62 @@ const logger = debug('agents:msal')
  * Provides tokens using MSAL.
  */
 export class MsalTokenProvider implements AuthProvider {
+  private readonly _agenticTokenCache: MemoryCache<string>
+  public readonly connectionSettings?: AuthConfiguration
+
+  constructor (connectionSettings?: AuthConfiguration) {
+    this._agenticTokenCache = new MemoryCache<string>()
+    this.connectionSettings = connectionSettings
+  }
+
+  /**
+   * Gets an access token using the auth configuration from the MsalTokenProvider instance and the provided scope.
+   * @param scope The scope for the token.
+   * @returns A promise that resolves to the access token.
+   */
+  public async getAccessToken (scope: string): Promise<string>
   /**
    * Gets an access token.
    * @param authConfig The authentication configuration.
    * @param scope The scope for the token.
    * @returns A promise that resolves to the access token.
    */
-  public async getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string> {
+  public async getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string>
+
+  public async getAccessToken (authConfigOrScope: AuthConfiguration | string, scope?: string): Promise<string> {
+    let authConfig: AuthConfiguration
+    let actualScope: string
+
+    if (typeof authConfigOrScope === 'string') {
+    // Called as getAccessToken(scope)
+      if (!this.connectionSettings) {
+        throw new Error('Connection settings must be provided to constructor when calling getAccessToken(scope)')
+      }
+      authConfig = this.connectionSettings
+      actualScope = authConfigOrScope
+    } else {
+    // Called as getAccessToken(authConfig, scope)
+      authConfig = authConfigOrScope
+      actualScope = scope as string
+    }
+
     if (!authConfig.clientId && process.env.NODE_ENV !== 'production') {
       return ''
     }
     let token
-    if (authConfig.FICClientId !== undefined) {
-      token = await this.acquireAccessTokenViaFIC(authConfig, scope)
+    if (authConfig.WIDAssertionFile !== undefined) {
+      token = await this.acquireAccessTokenViaWID(authConfig, actualScope)
+    } else if (authConfig.FICClientId !== undefined) {
+      token = await this.acquireAccessTokenViaFIC(authConfig, actualScope)
     } else if (authConfig.clientSecret !== undefined) {
-      token = await this.acquireAccessTokenViaSecret(authConfig, scope)
+      token = await this.acquireAccessTokenViaSecret(authConfig, actualScope)
     } else if (authConfig.certPemFile !== undefined &&
       authConfig.certKeyFile !== undefined) {
-      token = await this.acquireTokenWithCertificate(authConfig, scope)
+      token = await this.acquireTokenWithCertificate(authConfig, actualScope)
     } else if (authConfig.clientSecret === undefined &&
       authConfig.certPemFile === undefined &&
       authConfig.certKeyFile === undefined) {
-      token = await this.acquireTokenWithUserAssignedIdentity(authConfig, scope)
+      token = await this.acquireTokenWithUserAssignedIdentity(authConfig, actualScope)
     } else {
       throw new Error('Invalid authConfig. ')
     }
@@ -51,7 +87,33 @@ export class MsalTokenProvider implements AuthProvider {
     return token
   }
 
-  public async acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string> {
+  public async acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+  public async acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
+
+  public async acquireTokenOnBehalfOf (
+    authConfigOrScopes: AuthConfiguration | string[],
+    scopesOrOboAssertion?: string[] | string,
+    oboAssertion?: string
+  ): Promise<string> {
+    let authConfig: AuthConfiguration
+    let actualScopes: string[]
+    let actualOboAssertion: string
+
+    if (Array.isArray(authConfigOrScopes)) {
+    // Called as acquireTokenOnBehalfOf(scopes, oboAssertion)
+      if (!this.connectionSettings) {
+        throw new Error('Connection settings must be provided to constructor when calling acquireTokenOnBehalfOf(scopes, oboAssertion)')
+      }
+      authConfig = this.connectionSettings
+      actualScopes = authConfigOrScopes
+      actualOboAssertion = scopesOrOboAssertion as string
+    } else {
+    // Called as acquireTokenOnBehalfOf(authConfig, scopes, oboAssertion)
+      authConfig = authConfigOrScopes
+      actualScopes = scopesOrOboAssertion as string[]
+      actualOboAssertion = oboAssertion!
+    }
+
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId as string,
@@ -61,12 +123,128 @@ export class MsalTokenProvider implements AuthProvider {
       system: this.sysOptions
     })
     const token = await cca.acquireTokenOnBehalfOf({
-      oboAssertion,
-      scopes
+      oboAssertion: actualOboAssertion,
+      scopes: actualScopes
     })
     return token?.accessToken as string
   }
 
+  public async getAgenticInstanceToken (agentAppInstanceId: string): Promise<string> {
+    logger.debug('Getting agentic instance token')
+    if (!this.connectionSettings) {
+      throw new Error('Connection settings must be provided when calling getAgenticInstanceToken')
+    }
+    const appToken = await this.getAgenticApplicationToken(agentAppInstanceId)
+    const cca = new ConfidentialClientApplication({
+      auth: {
+        clientId: agentAppInstanceId,
+        clientAssertion: appToken,
+        authority: `${this.connectionSettings.authority}/${this.connectionSettings.tenantId || 'botframework.com'}`,
+      },
+      system: this.sysOptions
+    })
+
+    const token = await cca.acquireTokenByClientCredential({
+      scopes: ['api://AzureAdTokenExchange/.default'],
+      correlationId: v4()
+    })
+
+    if (!token?.accessToken) {
+      throw new Error(`Failed to acquire instance token for agent instance: ${agentAppInstanceId}`)
+    }
+
+    return token.accessToken
+  }
+
+  /**
+   * Does a direct HTTP call to acquire a token for agentic scenarios - do not use this directly!
+   * This method will be removed once MSAL is updated with the necessary features.
+   * (This is required in order to pass additional parameters into the auth call)
+   * @param clientId
+   * @param clientAssertion
+   * @param scopes
+   * @param tokenBodyParameters
+   * @returns
+   */
+  private async acquireTokenByForAgenticScenarios (clientId: string, clientAssertion: string | undefined, scopes: string[], tokenBodyParameters: { [key: string]: any }): Promise<string | null> {
+    if (!this.connectionSettings) {
+      throw new Error('Connection settings must be provided when calling getAgenticInstanceToken')
+    }
+
+    // Check cache first
+    const cacheKey = `${clientId}/${Object.keys(tokenBodyParameters).map(key => key !== 'user_federated_identity_credential' ? `${key}=${tokenBodyParameters[key]}` : '').join('&')}/${scopes.join(';')}`
+    if (this._agenticTokenCache.get(cacheKey)) {
+      return this._agenticTokenCache.get(cacheKey) as string
+    }
+
+    const url = `${this.connectionSettings.authority}/${this.connectionSettings.tenantId || 'botframework.com'}/oauth2/v2.0/token`
+
+    const data: { [key: string]: any } = {
+      client_id: clientId,
+      scope: scopes.join(' '),
+      ...tokenBodyParameters
+    }
+
+    if (clientAssertion) {
+      data.client_assertion_type = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+      data.client_assertion = clientAssertion
+    } else {
+      data.client_secret = this.connectionSettings.clientSecret
+    }
+
+    const token = await axios.post(
+      url,
+      data,
+      {
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded;charset=utf-8'
+        }
+      }
+    ).catch((error) => {
+      logger.error('Error acquiring token: ', error.toJSON())
+      throw error
+    })
+
+    // capture token, expire local cache 5 minutes early
+    this._agenticTokenCache.set(cacheKey, token.data.access_token, token.data.expires_in - 300)
+    return token.data.access_token
+  }
+
+  public async getAgenticUserToken (agentAppInstanceId: string, agenticUserId: string, scopes: string[]): Promise<string> {
+    logger.debug('Getting agentic user token')
+    const agentToken = await this.getAgenticApplicationToken(agentAppInstanceId)
+    const instanceToken = await this.getAgenticInstanceToken(agentAppInstanceId)
+
+    const token = await this.acquireTokenByForAgenticScenarios(agentAppInstanceId, agentToken, scopes, {
+      user_id: agenticUserId,
+      user_federated_identity_credential: instanceToken,
+      grant_type: 'user_fic',
+    })
+
+    if (!token) {
+      throw new Error(`Failed to acquire instance token for user token: ${agentAppInstanceId}`)
+    }
+
+    return token
+  }
+
+  public async getAgenticApplicationToken (agentAppInstanceId: string): Promise<string> {
+    if (!this.connectionSettings?.clientId) {
+      throw new Error('Connection settings must be provided when calling getAgenticApplicationToken')
+    }
+    logger.debug('Getting agentic application token')
+    const token = await this.acquireTokenByForAgenticScenarios(this.connectionSettings.clientId, undefined, ['api://AzureAdTokenExchange/.default'], {
+      grant_type: 'client_credentials',
+      fmi_path: agentAppInstanceId,
+    })
+
+    if (!token) {
+      throw new Error(`Failed to acquire token for agent instance: ${agentAppInstanceId}`)
+    }
+
+    return token
+  }
+
   private readonly sysOptions: NodeSystemOptions = {
     loggerOptions: {
       logLevel: LogLevel.Trace,
@@ -197,6 +375,28 @@ export class MsalTokenProvider implements AuthProvider {
     return token?.accessToken as string
   }
 
+  /**
+   * Acquires a token using a Workload Identity client assertion.
+   * @param authConfig The authentication configuration.
+   * @param scope The scope for the token.
+   * @returns A promise that resolves to the access token.
+   */
+  private async acquireAccessTokenViaWID (authConfig: AuthConfiguration, scope: string) : Promise<string> {
+    const scopes = [`${scope}/.default`]
+    const clientAssertion = fs.readFileSync(authConfig.WIDAssertionFile as string, 'utf8')
+    const cca = new ConfidentialClientApplication({
+      auth: {
+        clientId: authConfig.clientId as string,
+        authority: `https://login.microsoftonline.com/${authConfig.tenantId}`,
+        clientAssertion
+      },
+      system: this.sysOptions
+    })
+    const token = await cca.acquireTokenByClientCredential({ scopes })
+    logger.info('got token using WID client assertion')
+    return token?.accessToken as string
+  }
+
   /**
    * Fetches an external token.
    * @param FICClientId The FIC client ID.

package/src/baseAdapter.ts

@@ -3,9 +3,6 @@
  * Licensed under the MIT License.
  */
 
-import { AuthConfiguration } from './auth/authConfiguration'
-import { AuthProvider } from './auth/authProvider'
-import { MsalTokenProvider } from './auth/msalTokenProvider'
 import { Middleware, MiddlewareHandler, MiddlewareSet } from './middlewareSet'
 import { TurnContext } from './turnContext'
 import { debug } from '@microsoft/agents-activity/logger'
@@ -13,7 +10,7 @@ import { Activity, ConversationReference } from '@microsoft/agents-activity'
 import { ResourceResponse } from './connector-client/resourceResponse'
 import { AttachmentData } from './connector-client/attachmentData'
 import { AttachmentInfo } from './connector-client/attachmentInfo'
-import { UserTokenClient } from './oauth'
+import { JwtPayload } from 'jsonwebtoken'
 
 const logger = debug('agents:base-adapter')
 
@@ -54,35 +51,15 @@ export abstract class BaseAdapter {
     await context.sendActivity('To continue to run this agent, please fix the source code.')
   }
 
-  /**
-   * Symbol key used to store agent identity information in the TurnContext.
-   */
-  readonly AgentIdentityKey = Symbol('AgentIdentity')
-
   /**
    * Symbol key used to store connector client instances in the TurnContext.
    */
   readonly ConnectorClientKey = Symbol('ConnectorClient')
 
   /**
-   * Symbol key used to store OAuth scope information in the TurnContext.
-   */
-  readonly OAuthScopeKey = Symbol('OAuthScope')
-
-  /**
-   * The authentication provider used for token management.
-   */
-  authProvider: AuthProvider = new MsalTokenProvider()
-
-  /**
-   * The user token client used for managing user tokens.
-   */
-  userTokenClient: UserTokenClient | null = null
-
-  /**
-   * The authentication configuration for the adapter.
+   * Symbol key used to store User Token Client instances in the TurnContext.
    */
-  abstract authConfig: AuthConfiguration
+  readonly UserTokenClientKey = Symbol('UserTokenClient')
 
   /**
    * Sends a set of activities to the conversation.
@@ -115,32 +92,36 @@ export abstract class BaseAdapter {
    * @returns A promise representing the completion of the continue operation.
    */
   abstract continueConversation (
+    botAppIdOrIdentity: string | JwtPayload,
     reference: Partial<ConversationReference>,
     logic: (revocableContext: TurnContext) => Promise<void>
   ): Promise<void>
 
   /**
+   * @deprecated This function will not be supported in future versions.  Use TurnContext.turnState.get<ConnectorClient>(CloudAdapter.ConnectorClientKey).
    * Uploads an attachment.
    * @param conversationId - The conversation ID.
    * @param attachmentData - The attachment data.
    * @returns A promise representing the ResourceResponse for the uploaded attachment.
    */
-  abstract uploadAttachment (conversationId: string, attachmentData: AttachmentData): Promise<ResourceResponse>
+  abstract uploadAttachment (context: TurnContext, conversationId: string, attachmentData: AttachmentData): Promise<ResourceResponse>
 
   /**
+   * @deprecated This function will not be supported in future versions.  Use TurnContext.turnState.get<ConnectorClient>(CloudAdapter.ConnectorClientKey).
    * Gets attachment information.
    * @param attachmentId - The attachment ID.
    * @returns A promise representing the AttachmentInfo for the requested attachment.
    */
-  abstract getAttachmentInfo (attachmentId: string): Promise<AttachmentInfo>
+  abstract getAttachmentInfo (context: TurnContext, attachmentId: string): Promise<AttachmentInfo>
 
   /**
+   * @deprecated This function will not be supported in future versions.  Use TurnContext.turnState.get<ConnectorClient>(CloudAdapter.ConnectorClientKey).
    * Gets an attachment.
    * @param attachmentId - The attachment ID.
    * @param viewId - The view ID.
    * @returns A promise representing the NodeJS.ReadableStream for the requested attachment.
    */
-  abstract getAttachment (attachmentId: string, viewId: string): Promise<NodeJS.ReadableStream>
+  abstract getAttachment (context: TurnContext, attachmentId: string, viewId: string): Promise<NodeJS.ReadableStream>
 
   /**
    * Gets the error handler for the adapter.