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

package/src/app/auth/handlers/agenticAuthorization.ts

@@ -0,0 +1,194 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { debug } from '@microsoft/agents-activity'
+import { TurnContext } from '../../../turnContext'
+import { AuthorizationHandler, AuthorizationHandlerSettings, AuthorizationHandlerStatus, AuthorizationHandlerTokenOptions } from '../types'
+import { TokenResponse } from '../../../oauth'
+import { AuthProvider } from '../../../auth'
+
+const logger = debug('agents:authorization:agentic')
+
+/**
+ * Options for configuring the Agentic authorization handler.
+ */
+export interface AgenticAuthorizationOptions {
+  /**
+   * The type of authorization handler.
+   * @remarks
+   * When using environment variables, this can be set using the `${authHandlerId}_type` variable.
+   */
+  type: 'agentic'
+  /**
+   * The scopes required for the authorization.
+   * @remarks
+   * When using environment variables, this can be set using the `${authHandlerId}_scopes` variable (comma-separated values, e.g. `scope1,scope2`).
+   */
+  scopes?: string[]
+  /**
+   * (Optional) An alternative connection name to use for the authorization process.
+   * @remarks
+   * When using environment variables, this can be set using the `${authHandlerId}_altBlueprintConnectionName` variable.
+   */
+  altBlueprintConnectionName?: string
+}
+
+/**
+ * Settings for configuring the Agentic authorization handler.
+ */
+export interface AgenticAuthorizationSettings extends AuthorizationHandlerSettings {}
+
+/**
+ * Authorization handler for Agentic authentication.
+ */
+export class AgenticAuthorization implements AuthorizationHandler {
+  private _options: AgenticAuthorizationOptions
+  private _onSuccess?: Parameters<AuthorizationHandler['onSuccess']>[0]
+  private _onFailure?: Parameters<AuthorizationHandler['onFailure']>[0]
+
+  /**
+   * Creates an instance of the AgenticAuthorization class.
+   * @param id The unique identifier for the authorization handler.
+   * @param options The options for configuring the authorization handler.
+   * @param settings The settings for the authorization handler.
+   */
+  constructor (public readonly id: string, options: AgenticAuthorizationOptions, private settings: AgenticAuthorizationSettings) {
+    if (!this.settings.connections) {
+      throw new Error(this.prefix('The \'connections\' option is not available in the app options. Ensure that the app is properly configured.'))
+    }
+
+    this._options = this.loadOptions(options)
+  }
+
+  /**
+   * Loads and validates the authorization handler options.
+   */
+  private loadOptions (settings: AgenticAuthorizationOptions) {
+    const result: AgenticAuthorizationOptions = {
+      type: 'agentic',
+      altBlueprintConnectionName: settings.altBlueprintConnectionName ?? (process.env[`${this.id}_altBlueprintConnectionName`]),
+      scopes: settings.scopes ?? this.loadScopes(process.env[`${this.id}_scopes`]),
+    }
+
+    if (!result.scopes || result.scopes.length === 0) {
+      throw new Error(this.prefix('At least one scope must be specified for the Agentic authorization handler.'))
+    }
+
+    return result
+  }
+
+  /**
+   * @inheritdoc
+   */
+  signin (): Promise<AuthorizationHandlerStatus> {
+    return Promise.resolve(AuthorizationHandlerStatus.IGNORED)
+  }
+
+  /**
+   * @inheritdoc
+   */
+  signout (): Promise<boolean> {
+    return Promise.resolve(false)
+  }
+
+  /**
+   * @inheritdoc
+   */
+  async token (context: TurnContext, options?: AuthorizationHandlerTokenOptions): Promise<TokenResponse> {
+    try {
+      const tokenResponse = this.getContext(context)
+      if (tokenResponse.token) {
+        logger.debug(this.prefix('Using cached Agentic user token'))
+        return tokenResponse
+      }
+
+      let connection: AuthProvider
+
+      if (this._options.altBlueprintConnectionName?.trim()) {
+        connection = this.settings.connections.getConnection(this._options.altBlueprintConnectionName)
+      } else {
+        const audience = this.getAudience(context)
+        connection = this.settings.connections.getTokenProvider(audience, context.activity.serviceUrl ?? '')
+      }
+
+      const token = await connection.getAgenticUserToken(
+        context.activity.getAgenticInstanceId() ?? '',
+        context.activity.getAgenticUser() ?? '',
+        options?.scopes || this._options.scopes!
+      )
+
+      this.setContext(context, { token })
+      this._onSuccess?.(context)
+      return { token }
+    } catch (error) {
+      const reason = 'Error retrieving Agentic user token'
+      logger.error(this.prefix(reason), error)
+      this._onFailure?.(context, `${reason}: ${(error as Error).message}`)
+      return { token: undefined }
+    }
+  }
+
+  /**
+   * @inheritdoc
+   */
+  onSuccess (callback: (context: TurnContext) => void): void {
+    this._onSuccess = callback
+  }
+
+  /**
+   * @inheritdoc
+   */
+  onFailure (callback: (context: TurnContext, reason?: string) => void): void {
+    this._onFailure = callback
+  }
+
+  /**
+   * Prefixes a message with the handler ID.
+   */
+  private prefix (message: string) {
+    return `[handler:${this.id}] ${message}`
+  }
+
+  private _key = `${AgenticAuthorization.name}/${this.id}`
+
+  /**
+   * Sets the authorization context in the turn state.
+   */
+  private setContext (context: TurnContext, data: TokenResponse) {
+    return context.turnState.set(this._key, () => data)
+  }
+
+  /**
+   * Gets the authorization context from the turn state.
+   */
+  private getContext (context: TurnContext): TokenResponse {
+    const result = context.turnState.get(this._key)
+    return result?.() ?? { token: undefined }
+  }
+
+  /**
+   * Gets the audience from the turn context.
+   */
+  private getAudience (context: TurnContext): string {
+    const { aud } = context.identity
+    if (!aud) {
+      throw new Error('No audience (aud) claim found in Activity.identity.')
+    }
+    return Array.isArray(aud) ? aud[0] : aud
+  }
+
+  /**
+   * Loads the OAuth scopes from the environment variables.
+   */
+  private loadScopes (value:string | undefined): string[] {
+    return value?.split(',').reduce<string[]>((acc, scope) => {
+      const trimmed = scope.trim()
+      if (trimmed) {
+        acc.push(trimmed)
+      }
+      return acc
+    }, []) ?? []
+  }
+}