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

package/src/app/auth/authorization.ts

@@ -0,0 +1,252 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { debug } from '@microsoft/agents-activity/logger'
+import { TokenResponse } from '../../oauth'
+import { TurnContext } from '../../turnContext'
+import { TurnState } from '../turnState'
+import { AuthorizationManager } from './authorizationManager'
+import { AuthorizationHandlerTokenOptions } from './types'
+
+const logger = debug('agents:authorization')
+
+/**
+ * Class responsible for managing authorization and OAuth flows.
+ * Handles multiple OAuth providers and manages the complete authentication lifecycle.
+ *
+ * @remarks
+ * The Authorization class provides a centralized way to handle OAuth authentication
+ * flows within the agent application. It supports multiple authentication handlers,
+ * token exchange, on-behalf-of flows, and provides event handlers for success/failure scenarios.
+ *
+ * Key features:
+ * - Multiple OAuth provider support
+ * - Token caching and exchange
+ * - On-behalf-of (OBO) token flows
+ * - Sign-in success/failure event handling
+ * - Automatic configuration from environment variables
+ *
+ */
+export class Authorization {
+  /**
+   * Creates a new instance of Authorization.
+   * @param manager The AuthorizationManager instance to manage handlers.
+   */
+  constructor (private manager: AuthorizationManager) {}
+
+  /**
+   * Gets the token for a specific auth handler.
+   *
+   * @param context - The context object for the current turn.
+   * @param authHandlerId - ID of the auth handler to use.
+   * @returns A promise that resolves to the token response from the OAuth provider.
+   * @throws {Error} If the auth handler is not configured.
+   *
+   * @remarks
+   * This method retrieves an existing token for the specified auth handler.
+   * The token may be cached and will be retrieved from the OAuth provider if needed.
+   *
+   * @example
+   * ```typescript
+   * const tokenResponse = await auth.getToken(context, 'microsoft');
+   * if (tokenResponse.token) {
+   *   console.log('User is authenticated');
+   * }
+   * ```
+   *
+   * @public
+   */
+  public async getToken (context: TurnContext, authHandlerId: string): Promise<TokenResponse> {
+    const handler = this.getHandler(authHandlerId)
+    const { token } = await handler.token(context)
+    return { token }
+  }
+
+  /**
+   * @deprecated
+   * Exchanges a token for a new token with different scopes.
+   *
+   * @param context - The context object for the current turn.
+   * @param scopes - Array of scopes to request for the new token.
+   * @param authHandlerId - ID of the auth handler to use.
+   * @returns A promise that resolves to the exchanged token response.
+   * @throws {Error} If the auth handler is not configured.
+   *
+   * @remarks
+   * This method handles token exchange scenarios, particularly for on-behalf-of (OBO) flows.
+   * It checks if the current token is exchangeable (e.g., has audience starting with 'api://')
+   * and performs the appropriate token exchange using MSAL.
+   *
+   * @example
+   * ```typescript
+   * const exchangedToken = await auth.exchangeToken(
+   *   context,
+   *   ['https://graph.microsoft.com/.default'],
+   *   'microsoft'
+   * );
+   * ```
+   *
+   * @public
+   */
+  public async exchangeToken (context: TurnContext, scopes: string[], authHandlerId: string): Promise<TokenResponse>
+  /**
+   * Exchanges a token for a new token with different scopes.
+   *
+   * @param context - The context object for the current turn.
+   * @param authHandlerId - ID of the auth handler to use.
+   * @param options - Optional token options. If `connection` and `scopes` are NOT provided, the auth handler's configured options are used
+   * (`AgentApplication.authorization.obo.connection` and `AgentApplication.authorization.obo.scopes`), and the token exchange operation will happen automatically,
+   * meaning that this method should not be called, otherwise it will perform the token exchange operation twice.
+   * Provide `options` only when you need to override the `AgentApplication.authorization.obo` configuration for a specific call.
+   * @returns A promise that resolves to the exchanged token response.
+   * @throws {Error} If the auth handler is not configured.
+   *
+   * @remarks
+   * This method handles token exchange scenarios, particularly for on-behalf-of (OBO) flows.
+   * It checks if the current token is exchangeable (e.g., has audience starting with 'api://')
+   * and performs the appropriate token exchange using MSAL.
+   *
+   * @example
+   * ```typescript
+   * const exchangedToken = await auth.exchangeToken(
+   *   context,
+   *   'microsoft',
+   *   { connection: 'oboConnection', scopes: ['https://graph.microsoft.com/.default'] }
+   * });
+   * ```
+   *
+   * @public
+   */
+  public async exchangeToken (context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): Promise<TokenResponse>
+
+  /**
+   * @internal
+   * Internal implementation of exchangeToken method.
+   * Handles both overloads and performs the actual token exchange logic.
+   */
+  public async exchangeToken (context: TurnContext, authHandlerId: string[] | string, options?: AuthorizationHandlerTokenOptions | string): Promise<TokenResponse> {
+    if (authHandlerId instanceof Array && typeof options === 'string') {
+      logger.warn('Authorization.exchangeToken(context, scopes, authHandlerId) is deprecated. Use Authorization.exchangeToken(context, authHandlerId, options) instead.')
+      const [handlerId, handlerScopes] = [options, authHandlerId]
+      return this.exchangeToken(context, handlerId, { scopes: handlerScopes })
+    }
+
+    if (typeof authHandlerId === 'string' && typeof options === 'object') {
+      const handler = this.getHandler(authHandlerId)
+      const { token } = await handler.token(context, options)
+      return { token }
+    }
+
+    throw new Error('Invalid parameters for exchangeToken method.')
+  }
+
+  /**
+   * Signs out the current user.
+   *
+   * @param context - The context object for the current turn.
+   * @param state - The state object for the current turn.
+   * @param authHandlerId - Optional ID of the auth handler to use for sign out. If not provided, signs out from all handlers.
+   * @returns A promise that resolves when sign out is complete.
+   * @throws {Error} If the specified auth handler is not configured.
+   *
+   * @remarks
+   * This method clears the user's token and resets the authentication state.
+   * If no specific authHandlerId is provided, it signs out from all configured handlers.
+   * This ensures complete cleanup of authentication state across all providers.
+   *
+   * @example
+   * ```typescript
+   * // Sign out from specific handler
+   * await auth.signOut(context, state, 'microsoft');
+   *
+   * // Sign out from all handlers
+   * await auth.signOut(context, state);
+   * ```
+   *
+   * @public
+   */
+  public async signOut (context: TurnContext, state: TurnState, authHandlerId?: string) : Promise<void> {
+    if (authHandlerId) {
+      await this.getHandler(authHandlerId).signout(context)
+    } else {
+      for (const handler of Object.values(this.manager.handlers)) {
+        await handler.signout(context)
+      }
+    }
+  }
+
+  /**
+   * Sets a handler to be called when sign-in is successfully completed.
+   *
+   * @param handler - The handler function to call on successful sign-in.
+   *
+   * @remarks
+   * This method allows you to register a callback that will be invoked whenever
+   * a user successfully completes the authentication process. The handler receives
+   * the turn context, state, and the ID of the auth handler that was used.
+   *
+   * @example
+   * ```typescript
+   * auth.onSignInSuccess(async (context, state, authHandlerId) => {
+   *   await context.sendActivity(`Welcome! You signed in using ${authHandlerId}.`);
+   *   // Perform any post-authentication setup
+   * });
+   * ```
+   *
+   * @public
+   */
+  public onSignInSuccess (handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => Promise<void>) {
+    for (const authHandler of Object.values(this.manager.handlers)) {
+      authHandler.onSuccess((context) => handler(context, new TurnState(), authHandler.id))
+    }
+  }
+
+  /**
+   * Sets a handler to be called when sign-in fails.
+   *
+   * @param handler - The handler function to call on sign-in failure.
+   *
+   * @remarks
+   * This method allows you to register a callback that will be invoked whenever
+   * a user's authentication attempt fails. The handler receives the turn context,
+   * state, auth handler ID, and an optional error message describing the failure.
+   *
+   * Common failure scenarios include:
+   * - User cancels the authentication process
+   * - Invalid credentials or expired tokens
+   * - Network connectivity issues
+   * - OAuth provider errors
+   *
+   * @example
+   * ```typescript
+   * auth.onSignInFailure(async (context, state, authHandlerId, errorMessage) => {
+   *   await context.sendActivity(`Sign-in failed: ${errorMessage || 'Unknown error'}`);
+   *   await context.sendActivity('Please try signing in again.');
+   * });
+   * ```
+   *
+   * @public
+   */
+  public onSignInFailure (handler: (context: TurnContext, state: TurnState, authHandlerId?: string, errorMessage?: string) => Promise<void>) {
+    for (const authHandler of Object.values(this.manager.handlers)) {
+      authHandler.onFailure((context, reason) => handler(context, new TurnState(), authHandler.id, reason))
+    }
+  }
+
+  /**
+   * Gets the auth handler by ID or throws an error if not found.
+   *
+   * @param id - ID of the auth handler to retrieve.
+   * @returns The auth handler instance.
+   * @throws {Error} If the auth handler with the specified ID is not configured.
+   * @private
+   */
+  private getHandler (id: string) {
+    if (!Object.prototype.hasOwnProperty.call(this.manager.handlers, id)) {
+      throw new Error(`Cannot find auth handler with ID '${id}'. Ensure it is configured in the agent application options.`)
+    }
+    return this.manager.handlers[id]
+  }
+}

package/src/app/auth/authorizationManager.ts

@@ -0,0 +1,213 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity, debug } from '@microsoft/agents-activity'
+import { AgentApplication } from '../agentApplication'
+import { AgenticAuthorization, AzureBotAuthorization } from './handlers'
+import { TurnContext } from '../../turnContext'
+import { HandlerStorage } from './handlerStorage'
+import { ActiveAuthorizationHandler, AuthorizationHandlerStatus, AuthorizationHandler, AuthorizationHandlerSettings, AuthorizationOptions } from './types'
+import { Connections } from '../../auth/connections'
+
+const logger = debug('agents:authorization:manager')
+
+/**
+ * Active handler information used by the AuthorizationManager.
+ */
+interface ManagerActiveHandler {
+  data: ActiveAuthorizationHandler;
+  handlers: AuthorizationHandler[];
+}
+
+/**
+ * Result of the authorization manager process.
+ */
+export interface AuthorizationManagerProcessResult {
+  /**
+   * Indicates whether the authorization was successful.
+   */
+  authorized: boolean;
+}
+
+/**
+ * Function to retrieve handler IDs for the current activity.
+ */
+export type GetHandlerIds = (activity: Activity) => string[] | Promise<string[]>
+
+/**
+ * Manages multiple authorization handlers and their interactions.
+ * Processes authorization requests and maintains handler states.
+ * @remarks
+ * This class is responsible for coordinating the authorization process
+ * across multiple handlers, ensuring that each handler is invoked in
+ * the correct order and with the appropriate context.
+ */
+export class AuthorizationManager {
+  private _handlers: Record<string, AuthorizationHandler> = {}
+
+  /**
+   * Creates an instance of the AuthorizationManager.
+   * @param app The agent application instance.
+   */
+  constructor (private app: AgentApplication<any>, connections: Connections) {
+    if (!app.options.storage) {
+      throw new Error('Storage is required for Authorization. Ensure that a storage provider is configured in the AgentApplication options.')
+    }
+
+    if (app.options.authorization === undefined || Object.keys(app.options.authorization).length === 0) {
+      throw new Error('The AgentApplication.authorization does not have any auth handlers')
+    }
+
+    const settings: AuthorizationHandlerSettings = { storage: app.options.storage, connections }
+    for (const [id, handler] of Object.entries(app.options.authorization)) {
+      const options = this.loadOptions(id, handler)
+      if (options.type === 'agentic') {
+        this._handlers[id] = new AgenticAuthorization(id, options, settings)
+      } else {
+        this._handlers[id] = new AzureBotAuthorization(id, options, settings)
+      }
+    }
+  }
+
+  /**
+   * Loads and validates the authorization handler options.
+   */
+  private loadOptions (id: string, options: AuthorizationOptions[string]) {
+    const result: AuthorizationOptions[string] = {
+      ...options,
+      type: (options.type ?? process.env[`${id}_type`])?.toLowerCase() as typeof options.type,
+    }
+
+    // Validate supported types, agentic, and default (Azure Bot - undefined)
+    const supportedTypes = ['agentic', undefined]
+    if (!supportedTypes.includes(result.type)) {
+      throw new Error(`Unsupported authorization handler type: '${result.type}' for auth handler: '${id}'. Supported types are: '${supportedTypes.filter(Boolean).join('\', \'')}'.`)
+    }
+
+    return result
+  }
+
+  /**
+   * Gets the registered authorization handlers.
+   * @returns A record of authorization handlers by their IDs.
+   */
+  public get handlers (): Record<string, AuthorizationHandler> {
+    return this._handlers
+  }
+
+  /**
+   * Processes an authorization request.
+   * @param context The turn context.
+   * @param getHandlerIds A function to retrieve the handler IDs for the current activity.
+   * @returns The result of the authorization process.
+   */
+  public async process (context: TurnContext, getHandlerIds: GetHandlerIds): Promise<AuthorizationManagerProcessResult> {
+    const storage = new HandlerStorage(this.app.options.storage!, context)
+
+    let active = await this.active(storage, getHandlerIds)
+
+    const handlers = active?.handlers ?? this.mapHandlers(await getHandlerIds(context.activity) ?? []) ?? []
+
+    for (const handler of handlers) {
+      const status = await this.signin(storage, handler, context, active?.data)
+      logger.debug(this.prefix(handler.id, `Sign-in status: ${status}`))
+
+      if (status === AuthorizationHandlerStatus.IGNORED) {
+        await storage.delete()
+        return { authorized: true }
+      }
+
+      if (status === AuthorizationHandlerStatus.PENDING) {
+        return { authorized: false }
+      }
+
+      if (status === AuthorizationHandlerStatus.REJECTED) {
+        await storage.delete()
+        return { authorized: false }
+      }
+
+      if (status === AuthorizationHandlerStatus.REVALIDATE) {
+        await storage.delete()
+        return this.process(context, getHandlerIds)
+      }
+
+      if (status !== AuthorizationHandlerStatus.APPROVED) {
+        throw new Error(this.prefix(handler.id, `Unexpected registration status: ${status}`))
+      }
+
+      await storage.delete()
+
+      if (active) {
+        // Restore the original activity in the turn context for the next handler to process.
+        // This is done like this to avoid losing data that may be set in the turn context.
+        (context as any)._activity = Activity.fromObject(active.data.activity)
+        active = undefined
+      }
+    }
+
+    return { authorized: true }
+  }
+
+  /**
+   * Gets the active handler session from storage.
+   */
+  private async active (storage: HandlerStorage, getHandlerIds: GetHandlerIds): Promise<ManagerActiveHandler | undefined> {
+    const data = await storage.read()
+    if (!data) {
+      return
+    }
+
+    const handlerIds = await getHandlerIds(Activity.fromObject(data.activity))
+    let handlers = this.mapHandlers(handlerIds ?? [])
+
+    // Sort handlers to ensure the active handler is processed first, to ensure continuity.
+    handlers = handlers.sort((a, b) => {
+      if (a.id === data.id) {
+        return -1
+      }
+      if (b.id === data.id) {
+        return 1
+      }
+      return 0
+    }) ?? []
+    return { data, handlers }
+  }
+
+  /**
+   * Attempts to sign in using the specified handler and options.
+   */
+  private async signin (storage: HandlerStorage, handler: AuthorizationHandler, context: TurnContext, active?: ActiveAuthorizationHandler): Promise<AuthorizationHandlerStatus> {
+    try {
+      return await handler.signin(context, active)
+    } catch (cause) {
+      await storage.delete()
+      throw new Error(this.prefix(handler.id, 'Failed to sign in'), { cause })
+    }
+  }
+
+  /**
+   * Maps an array of handler IDs to their corresponding handler instances.
+   */
+  private mapHandlers (ids: string[]): AuthorizationHandler[] {
+    let unknownHandlers = ''
+    const handlers = ids.map(id => {
+      if (!this._handlers[id]) {
+        unknownHandlers += ` ${id}`
+      }
+      return this._handlers[id]
+    })
+    if (unknownHandlers) {
+      throw new Error(`Cannot find auth handlers with ID(s): ${unknownHandlers}`)
+    }
+    return handlers
+  }
+
+  /**
+   * Prefixes a message with the handler ID.
+   */
+  private prefix (id: string, message: string) {
+    return `[handler:${id}] ${message}`
+  }
+}

package/src/app/auth/handlerStorage.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ActiveAuthorizationHandler } from './types'
+import { TurnContext } from '../../turnContext'
+import { Storage } from '../../storage'
+
+/**
+ * Storage manager for handler state.
+ */
+export class HandlerStorage<TActiveHandler extends ActiveAuthorizationHandler = ActiveAuthorizationHandler> {
+  /**
+   * Creates an instance of the HandlerStorage.
+   * @param storage The storage provider.
+   * @param context The turn context.
+   */
+  constructor (private storage: Storage, private context: TurnContext) { }
+
+  /**
+   * Gets the unique key for a handler session.
+   */
+  public get key (): string {
+    const channelId = this.context.activity.channelId?.trim()
+    const userId = this.context.activity.from?.id?.trim()
+    if (!channelId || !userId) {
+      throw new Error(`Both 'activity.channelId' and 'activity.from.id' are required to generate the ${HandlerStorage.name} key.`)
+    }
+    return `auth/${channelId}/${userId}`
+  }
+
+  /**
+   * Reads the active handler state from storage.
+   */
+  public async read (): Promise<TActiveHandler | undefined> {
+    const ongoing = await this.storage.read([this.key])
+    return ongoing?.[this.key]
+  }
+
+  /**
+   * Writes handler state to storage.
+   */
+  public write (data: TActiveHandler) : Promise<void> {
+    return this.storage.write({ [this.key]: data })
+  }
+
+  /**
+   * Deletes handler state from storage.
+   */
+  public async delete (): Promise<void> {
+    try {
+      await this.storage.delete([this.key])
+    } catch (error) {
+      if (error instanceof Error && 'code' in error && error.code === 404) {
+        return
+      }
+      throw error
+    }
+  }
+}