@microsoft/agents-hosting 1.9.0-beta.8.gf58e66b2ee → 1.9.1

package/src/app/agentApplication.ts

@@ -20,6 +20,7 @@ import { TranscriptLoggerMiddleware } from '../transcript'
 import { CloudAdapter } from '../cloudAdapter'
 import { Authorization, UserAuthorization, AuthorizationManager } from './auth'
 import { Proactive } from './proactive'
+import { AgentApplicationRateLimiter } from './rateLimit'
 import { JwtPayload } from 'jsonwebtoken'
 import { trace, debug, redactString } from '@microsoft/agents-telemetry'
 import { AgentApplicationTraceDefinitions } from '../observability'
@@ -104,6 +105,7 @@ export class AgentApplication<TState extends TurnState> {
   private readonly _proactive?: Proactive<TState>
   protected readonly _extensions: AgentExtension<TState>[] = []
   private readonly _adaptiveCards: AdaptiveCardsActions<TState>
+  private readonly _rateLimiter?: AgentApplicationRateLimiter
 
   /**
    * Creates a new instance of AgentApplication.
@@ -141,6 +143,7 @@ export class AgentApplication<TState extends TurnState> {
       longRunningMessages: options?.longRunningMessages !== undefined ? options.longRunningMessages : false,
       removeRecipientMention: options?.removeRecipientMention !== undefined ? options.removeRecipientMention : true,
       transcriptLogger: options?.transcriptLogger || undefined,
+      rateLimit: options?.rateLimit || undefined,
     }
 
     this._adaptiveCards = new AdaptiveCardsActions<TState>(this)
@@ -148,11 +151,20 @@ export class AgentApplication<TState extends TurnState> {
     if (this._options.adapter) {
       this._adapter = this._options.adapter
     } else {
-      this._adapter = new CloudAdapter()
+      this._adapter = new CloudAdapter(
+        undefined,
+        undefined,
+        undefined,
+        { configurationContext: this._options.configurationContext }
+      )
     }
 
     this._adapter.setAgentName(this._options.agentName)
 
+    if (this._options.rateLimit && this._options.rateLimit.length > 0) {
+      this._rateLimiter = new AgentApplicationRateLimiter(this._options.rateLimit, this._options.storage)
+    }
+
     // Create Proactive whenever proactive options are explicitly configured or a storage
     // backend is available — no explicit `proactive` option is required.
     if (this._options.proactive !== undefined || this._options.storage !== undefined) {
@@ -201,6 +213,7 @@ export class AgentApplication<TState extends TurnState> {
       fileDownloaders: this._options.fileDownloaders ? 'configured' : undefined,
       turnStateFactory: options?.turnStateFactory ? 'custom' : 'default',
       adaptiveCardsOptions: this._options.adaptiveCardsOptions,
+      rateLimitRules: this._options.rateLimit?.length,
     })
   }
 
@@ -208,7 +221,7 @@ export class AgentApplication<TState extends TurnState> {
    * Gets the authorization instance for the application.
    *
    * @returns The authorization instance.
-   * @throws Error if no authentication options were configured.
+   * @throws Error if no authorization handlers were resolved.
    */
   public get authorization (): Authorization {
     if (this._authorizationManager.handlers.length === 0) {
@@ -495,7 +508,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    * @param handler - The handler function to be called after successful sign-in.
    * @returns The current instance of the application.
-   * @throws Error if authentication options were not configured.
+   * @throws Error if no authorization handlers were resolved.
    *
    * @remarks
    * This method allows you to perform actions after a user has successfully authenticated.
@@ -510,11 +523,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    */
   public onSignInSuccess (handler: (context: TurnContext, state: TurnState, id?: string) => Promise<void>): this {
-    if (this.options.authorization) {
-      this.authorization.onSignInSuccess(handler)
-    } else {
-      throw ExceptionHelper.generateException(Error, Errors.AuthorizationOptionNotAvailable)
-    }
+    this.authorization.onSignInSuccess(handler)
     return this
   }
 
@@ -523,7 +532,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    * @param handler - The handler function to be called after a failed sign-in attempt.
    * @returns The current instance of the application.
-   * @throws Error if authentication options were not configured.
+   * @throws Error if no authorization handlers were resolved.
    *
    * @remarks
    * This method allows you to handle cases where a user fails to authenticate,
@@ -538,11 +547,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    */
   public onSignInFailure (handler: (context: TurnContext, state: TurnState, id?: string) => Promise<void>): this {
-    if (this.options.authorization) {
-      this.authorization.onSignInFailure(handler)
-    } else {
-      throw ExceptionHelper.generateException(Error, Errors.AuthorizationOptionNotAvailable)
-    }
+    this.authorization.onSignInFailure(handler)
     return this
   }
 
@@ -675,6 +680,14 @@ export class AgentApplication<TState extends TurnState> {
    * ```
    */
   public async runInternal (turnContext: TurnContext): Promise<boolean> {
+    if (this._rateLimiter) {
+      const rateLimitDecision = await this._rateLimiter.shouldAllowTurn(turnContext)
+      if (!rateLimitDecision.allowed) {
+        await this._rateLimiter.handleThrottledTurn(turnContext, rateLimitDecision.rule!, rateLimitDecision.result!)
+        return false
+      }
+    }
+
     const { authorized, context } = await this.handleAuthorization(turnContext)
 
     if (!authorized) {

package/src/app/agentApplicationBuilder.ts

@@ -3,11 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { Storage } from '../storage'
+import { StorageProvider } from '../storage'
 import { AgentApplication } from './agentApplication'
 import { AgentApplicationOptions } from './agentApplicationOptions'
 import { AuthorizationOptions } from './auth/types'
 import { ProactiveOptions } from './proactive'
+import { RateLimitRule } from './rateLimit'
 import { TurnState } from './turnState'
 import { TypingOptions } from './agentApplicationOptions'
 
@@ -31,7 +32,7 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
    * @param storage The storage implementation to use
    * @returns This builder instance for chaining
    */
-  public withStorage (storage: Storage): this {
+  public withStorage (storage: StorageProvider): this {
     this._options.storage = storage
     return this
   }
@@ -86,6 +87,16 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
     return this
   }
 
+  /**
+   * Configures rate limit rules for incoming turns.
+   * @param rules The rate limit rules to apply
+   * @returns This builder instance for chaining
+   */
+  public withRateLimit (rules: RateLimitRule[]): this {
+    this._options.rateLimit = rules
+    return this
+  }
+
   /**
    * Builds and returns a new AgentApplication instance configured with the provided options.
    * @returns A new AgentApplication instance

package/src/app/agentApplicationOptions.ts

@@ -4,7 +4,7 @@
  */
 
 import { CloudAdapter } from '../cloudAdapter'
-import { Storage } from '../storage'
+import { StorageProvider } from '../storage'
 import { TranscriptLogger } from '../transcript'
 import { AdaptiveCardsOptions } from './adaptiveCards'
 import { InputFileDownloader } from './inputFileDownloader'
@@ -13,6 +13,8 @@ import { HeaderPropagationDefinition } from '../headerPropagation'
 import { AuthorizationOptions } from './auth/types'
 import { Connections } from '../auth/connections'
 import { ProactiveOptions } from './proactive'
+import { RateLimitRule } from './rateLimit'
+import { ConfigurationContext } from '../configuration/configuration'
 
 /**
  * Typing timer settings for a specific channel or the global default.
@@ -52,6 +54,12 @@ export interface TypingOptions extends TypingTimingOptions {
  * custom state management specific to your agent's needs.
  */
 export interface AgentApplicationOptions<TState extends TurnState> {
+  /**
+   * Optional host-scoped external configuration used by the application's
+   * default adapter and authorization handlers.
+   */
+  configurationContext?: ConfigurationContext;
+
   /**
    * The adapter used for handling bot interactions with various messaging platforms.
    * This adapter manages the communication layer between your agent and the Bot Framework.
@@ -72,12 +80,12 @@ export interface AgentApplicationOptions<TState extends TurnState> {
 
   /**
    * The storage mechanism for persisting conversation and user state across turns.
-   * This can be any implementation of the Storage interface, such as memory storage
-   * for development or blob storage for production scenarios.
+   * This can be a legacy Storage implementation, a StorageV2 implementation,
+   * or a built-in storage provider.
    *
    * @default undefined (no persistence)
    */
-  storage?: Storage;
+  storage?: StorageProvider;
 
   /**
    * Whether to start a typing indicator timer when the bot begins processing a message.
@@ -201,4 +209,10 @@ export interface AgentApplicationOptions<TState extends TurnState> {
    * When provided, `app.proactive` will be available.
    */
   proactive?: ProactiveOptions
+
+  /**
+   * Optional. Rate limit rules for incoming turns.
+   * When omitted or empty, no rate limiting is applied.
+   */
+  rateLimit?: RateLimitRule[]
 }

package/src/app/auth/authorizationManager.ts

@@ -4,7 +4,7 @@
  */
 
 import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
-import { debug, redactScopes } from '@microsoft/agents-telemetry'
+import { debug, redactScopes, redactString } from '@microsoft/agents-telemetry'
 import { AgentApplication } from '../agentApplication'
 import { AgenticAuthorization, AzureBotAuthorization } from './handlers'
 import { TurnContext } from '../../turnContext'
@@ -13,8 +13,10 @@ import { Errors } from '../../errorHelper'
 import { ActiveAuthorizationHandler, AuthorizationHandlerStatus, AuthorizationHandler, AuthorizationHandlerSettings, AuthorizationOptions } from './types'
 import { Connections } from '../../auth/connections'
 import { sendInvokeResponse } from './utils'
-import { envParser, envParserUtils } from '../../auth/settings'
-import { prune } from '../../utils'
+import { mergeDefined, prune } from '../../utils'
+import { getConfigurationSnapshot } from '../../configuration/configuration'
+import { loadModernEnvironmentConfiguration } from '../../configuration/environmentConfiguration'
+import { loadBotFrameworkAuthorizationEnvironmentConfiguration } from '../../configuration/botFrameworkEnvironmentCompatibility'
 
 const logger = debug('agents:authorization:manager')
 
@@ -22,6 +24,39 @@ const AGENTIC = 'AgenticUserAuthorization'
 const AGENTIC_LEGACY = 'agentic'
 const AZURE_BOT = 'AzureBotUserAuthorization'
 
+function redactAuthorizationString (value: unknown): string | undefined {
+  return typeof value === 'string' ? redactString(value) : undefined
+}
+
+function summarizeAuthorizationConfiguration (options: AuthorizationOptions[string]) {
+  return prune({
+    type: options.type,
+    azureBotOAuthConnectionName: 'azureBotOAuthConnectionName' in options
+      ? redactAuthorizationString(options.azureBotOAuthConnectionName)
+      : undefined,
+    invalidSignInRetryMax: 'invalidSignInRetryMax' in options && typeof options.invalidSignInRetryMax === 'number'
+      ? options.invalidSignInRetryMax
+      : undefined,
+    oboConnectionName: 'oboConnectionName' in options
+      ? redactAuthorizationString(options.oboConnectionName)
+      : undefined,
+    oboScopes: 'oboScopes' in options && Array.isArray(options.oboScopes) &&
+      options.oboScopes.every(scope => typeof scope === 'string')
+      ? redactScopes(options.oboScopes)
+      : undefined,
+    enableSso: 'enableSso' in options && typeof options.enableSso === 'boolean'
+      ? options.enableSso
+      : undefined,
+    scopes: 'scopes' in options && Array.isArray(options.scopes) &&
+      options.scopes.every(scope => typeof scope === 'string')
+      ? redactScopes(options.scopes)
+      : undefined,
+    altBlueprintConnectionName: 'altBlueprintConnectionName' in options
+      ? redactAuthorizationString(options.altBlueprintConnectionName)
+      : undefined
+  })
+}
+
 /**
  * Active handler information used by the AuthorizationManager.
  */
@@ -60,92 +95,6 @@ type GetHandlerIds = (activity: Activity) => string[] | Promise<string[]>
 export class AuthorizationManager {
   private _handlers: Record<string, AuthorizationHandler> = {}
 
-  /**
-   * Environment variable configuration for the latest format.
-   */
-  private _envLatest = {
-    key: {
-      prefix: 'AgentApplication__UserAuthorization__Handlers__',
-      separator: '__Settings__',
-      create (id: string, prop: string) {
-        return `${this.prefix}${id}${this.separator}${prop}`
-      },
-      extract (envKey: string) {
-        // Substring: AgentApplication__UserAuthorization__Handlers__<id>__Settings__<prop>
-        // position —————————————————————————————————————————> start^   ^end         ^prop
-        const start = this.prefix.length
-        const end = envKey.toUpperCase().indexOf(this.separator.toUpperCase())
-        if (end === -1) {
-          return { id: undefined, prop: undefined }
-        }
-
-        const id = envKey.substring(start, end)
-        const prop = envKey.substring(end + this.separator.length)
-        return { id, prop }
-      }
-    },
-    parser: envParser({
-      // Common
-      type: envParserUtils.bypass,
-
-      // Azure Bot
-      azureBotOAuthConnectionName: envParserUtils.bypass,
-      title: envParserUtils.bypass,
-      text: envParserUtils.bypass,
-      invalidSignInRetryMessage: envParserUtils.bypass,
-      invalidSignInRetryMessageFormat: envParserUtils.bypass,
-      invalidSignInRetryMaxExceededMessage: envParserUtils.bypass,
-      oboConnectionName: envParserUtils.bypass,
-      enableSso (value) {
-        return { value: value !== 'false' }
-      },
-      invalidSignInRetryMax (value) {
-        return { value: parseInt(value) }
-      },
-      oboScopes (value) {
-        return this.scopes(value)
-      },
-
-      // Agentic
-      altBlueprintConnectionName: envParserUtils.bypass,
-      scopes (value) {
-        if (value.includes(',')) {
-          return { value: value.split(',').map(s => s.trim()).filter(Boolean) }
-        }
-        return { value: value.split(/\s+/).filter(Boolean) }
-      }
-    }),
-  }
-
-  /**
-   * Environment variable configuration for the legacy format.
-   */
-  private _envLegacy = {
-    key: {
-      separator: '_',
-    },
-    parser: envParser({
-      // Common
-      type: envParserUtils.redirect(this._envLatest.parser, 'type'),
-
-      // Azure Bot
-      connectionName: envParserUtils.redirect(this._envLatest.parser, 'azureBotOAuthConnectionName'),
-      connectionTitle: envParserUtils.redirect(this._envLatest.parser, 'title'),
-      connectionText: envParserUtils.redirect(this._envLatest.parser, 'text'),
-      maxAttempts: envParserUtils.redirect(this._envLatest.parser, 'invalidSignInRetryMax'),
-      messages_invalidCode: envParserUtils.redirect(this._envLatest.parser, 'invalidSignInRetryMessage'),
-      messages_invalidCodeFormat: envParserUtils.redirect(this._envLatest.parser, 'invalidSignInRetryMessageFormat'),
-      messages_maxAttemptsExceeded: envParserUtils.redirect(this._envLatest.parser, 'invalidSignInRetryMaxExceededMessage'),
-      obo_connection: envParserUtils.redirect(this._envLatest.parser, 'oboConnectionName'),
-      obo_scopes: envParserUtils.redirect(this._envLatest.parser, 'oboScopes'),
-      enableSso: envParserUtils.redirect(this._envLatest.parser, 'enableSso'),
-
-      // Agentic
-      scopes: envParserUtils.redirect(this._envLatest.parser, 'scopes'),
-      altBlueprintConnectionName: envParserUtils.redirect(this._envLatest.parser, 'altBlueprintConnectionName')
-    })
-  }
-
   /**
    * Creates an instance of the AuthorizationManager.
    * @param app The agent application instance.
@@ -318,82 +267,58 @@ export class AuthorizationManager {
     let legacyMessage = ''
     const settings: AuthorizationHandlerSettings = { storage: this.app.options.storage!, connections: this.connections }
     const runtimeOptionEntries = Object.entries(this.app.options.authorization ?? {})
-    const result = { latest: {}, legacy: {} } as {
+    const result = {
+      latest: {},
+      legacy: {}
+    } as {
       latest: Record<string, Record<string, any> | undefined>;
       legacy: Record<string, Record<string, any> | undefined>;
     }
+    const external = getConfigurationSnapshot(this.app.options.configurationContext)
+    const externalOptionEntries = [
+      ...[...external.fallback.agentApplication.userAuthorization.handlers.values()].map(handler => [handler.id, handler.settings] as const),
+      ...[...external.overrideEnvironment.agentApplication.userAuthorization.handlers.values()].map(handler => [handler.id, handler.settings] as const),
+      ...[...external.enforce.agentApplication.userAuthorization.handlers.values()].map(handler => [handler.id, handler.settings] as const)
+    ]
+    const modernHandlers = loadModernEnvironmentConfiguration()
+      .agentApplication.userAuthorization.handlers
+    for (const handler of modernHandlers.values()) {
+      result.latest[handler.id] = { ...handler.settings }
+    }
 
-    for (const [envKey, envValue] of Object.entries(process.env)) {
-      if (!envValue?.trim()) {
-        continue
-      }
-
-      const upperEnvKey = envKey.toUpperCase()
-
-      // Legacy: extract handler ID, handler options key and its value, and assign it to the correct runtime handler ID.
-      if (!upperEnvKey.startsWith(this._envLatest.key.prefix.toUpperCase())) {
-        const [id] = runtimeOptionEntries.find(([id]) => upperEnvKey.startsWith(`${id.toUpperCase()}${this._envLegacy.key.separator}`)) ?? []
-        if (!id) {
-          continue
-        }
-
-        const prop = envKey.substring(id.length + this._envLegacy.key.separator.length)
-        if (!prop) {
-          continue
-        }
-
-        const { key, value } = this._envLegacy.parser.parse(prop as any, envValue)
-        if (!key) {
-          continue
-        }
-
-        legacyMessage += `  ${envKey}= # Use ${this._envLatest.key.create(id, key)} instead.\n`
-
-        result.legacy[id] ??= {}
-        result.legacy[id][key] = value
-        continue
-      }
-
-      // Latest: extract handler ID, handler options key and its value, and assign it to the correct latest handler ID.
-      const { id, prop } = this._envLatest.key.extract(envKey)
-      if (!id || !prop) {
-        continue
-      }
-
-      const { key, value } = this._envLatest.parser.parse(prop as any, envValue)
-      if (!key) {
-        continue
-      }
-
-      // Find existing handler ID case-insensitively to avoid duplicates, but keep the original casing for later processing.
-      // This allows users to specify environment variables in a case-insensitive way, while ensuring that the handler IDs are treated in a case-sensitive way internally, to avoid issues when referencing them later.
-      // For example, if the user specifies AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__GRAPH__SETTINGS__AZUREBOTOAUTHCONNECTIONNAME and agentapplication__userauthorization__handlers__graph__settings__azurebotoauthconnectionname, we want to treat them as the same handler ID "graph", and not create two separate handlers "GRAPH" and "graph".
-      // Note: the first environment variable that is processed will determine the casing of the handler ID, and any subsequent environment variable that matches the same handler ID case-insensitively will be treated as referring to the same handler, regardless of its casing.
-      const existingId = id in result.latest ? id : Object.keys(result.latest).find(e => e.toLowerCase() === id.toLowerCase())
-      const realId = existingId ?? id
-      result.latest[realId] ??= {}
-      result.latest[realId][key] = value
+    const compatibility = loadBotFrameworkAuthorizationEnvironmentConfiguration(
+      [...runtimeOptionEntries, ...externalOptionEntries].map(([id]) => id)
+    )
+    for (const handler of compatibility.layer.agentApplication.userAuthorization.handlers.values()) {
+      result.legacy[handler.id] = { ...handler.settings }
+    }
+    for (const replacement of compatibility.replacements) {
+      legacyMessage += `  ${replacement.legacyKey}= # Use ${replacement.modernKey} instead.\n`
     }
 
     if (legacyMessage.length > 0) {
       logger.warn('Deprecated environment variables detected, update to the latest format: (case-insensitive)', `[\n${legacyMessage}]`)
     }
 
-    // Fix types
-    const fixTypes = (entries: [string, any][]) => entries
-      .map(([id, options]) => [id, { ...options, type: this.fixType(id, options?.type) }] as [string, AuthorizationOptions[string]])
-
-    const runtimeEntries = fixTypes(runtimeOptionEntries)
-    const latestEntries = fixTypes(Object.entries(result.latest))
-    const legacyEntries = fixTypes(Object.entries(result.legacy))
-
     const registeredHandlers = new Set()
-    for (const [id] of [...runtimeEntries, ...latestEntries]) {
+    const handlerEntries = [
+      ...runtimeOptionEntries,
+      ...Object.entries(result.latest),
+      ...Object.entries(result.legacy),
+      ...externalOptionEntries
+    ]
+    for (const [id] of handlerEntries) {
       if (registeredHandlers.has(id.toLowerCase())) {
         continue
       }
 
-      const { options, format } = this.resolveHandlerConfiguration(id, runtimeEntries, latestEntries, legacyEntries)
+      const { options, format } = this.resolveHandlerConfiguration(
+        id,
+        runtimeOptionEntries,
+        Object.entries(result.latest),
+        Object.entries(result.legacy),
+        external
+      )
 
       if (options.type === AZURE_BOT) {
         // Set default values if not provided
@@ -403,17 +328,11 @@ export class AuthorizationManager {
         options.enableSso = options.enableSso !== false // default value is true if undefined.
       }
 
-      const maskedOptions: any = {}
-
-      if ('oboScopes' in options && options.oboScopes && options.oboScopes.length > 0) {
-        maskedOptions.oboScopes = redactScopes(options.oboScopes)
-      }
-
-      if ('scopes' in options && options.scopes && options.scopes.length > 0) {
-        maskedOptions.scopes = redactScopes(options.scopes)
-      }
-
-      logger.info(this.prefix(id, 'settings loaded from \'%s\''), format, { ...options, ...maskedOptions })
+      logger.info(
+        this.prefix(id, 'settings loaded from \'%s\''),
+        format,
+        summarizeAuthorizationConfiguration(options)
+      )
 
       if (!settings.storage) {
         throw ExceptionHelper.generateException(Error, Errors.StorageRequiredForAuthorization)
@@ -458,62 +377,65 @@ export class AuthorizationManager {
    */
   private resolveHandlerConfiguration (
     id: string,
-    runtimeEntries: Array<[string, AuthorizationOptions[string]]>,
-    latestEntries: Array<[string, AuthorizationOptions[string]]>,
-    legacyEntries: Array<[string, AuthorizationOptions[string]]>
+    runtimeEntries: Array<[string, any]>,
+    latestEntries: Array<[string, any]>,
+    legacyEntries: Array<[string, any]>,
+    external: ReturnType<typeof getConfigurationSnapshot>
   ): {
       options: AuthorizationOptions[string];
       format: string;
     } {
-    const matchesId = ([_id]: [string, AuthorizationOptions[string]]) => _id.toLowerCase() === id.toLowerCase()
+    const matchesId = ([_id]: [string, any]) => _id.toLowerCase() === id.toLowerCase()
+    const find = (entries: Array<[string, any]>) => entries.find(matchesId)?.[1]
+    const findExternal = (
+      entries: ReadonlyMap<string, Readonly<{ id: string; settings: Readonly<Record<string, unknown>> }>>
+    ) => [...entries.values()].find(handler => handler.id.toLowerCase() === id.toLowerCase())?.settings
 
-    // Find entries case-insensitively for later processing
-    const [, runtime] = runtimeEntries.find(matchesId) ?? []
-    const [, latest] = latestEntries.find(matchesId) ?? []
-    const [, legacy] = legacyEntries.find(matchesId) ?? []
+    const runtime = find(runtimeEntries)
+    const latest = find(latestEntries)
+    const legacy = find(legacyEntries)
 
     if (runtime !== undefined && latest !== undefined) {
       logger.warn(this.prefix(id, 'Both runtime options and latest environment variable configurations detected. Runtime configuration will take precedence over latest environment variables.'))
     }
 
+    const runtimeOptions = runtime === undefined ? undefined : { ...runtime }
     const runtimeLegacyKeys = ['name', 'maxAttempts', 'messages', 'obo']
-    const isRuntimeLegacy = runtime !== undefined && Object.keys(runtime).some(key => runtimeLegacyKeys.includes(key))
-
-    let runtimeLegacyFormat = ''
-    if (isRuntimeLegacy && runtime.type === AZURE_BOT) {
-      runtime.azureBotOAuthConnectionName ??= runtime.name
-      runtime.invalidSignInRetryMax ??= runtime.maxAttempts
-      runtime.invalidSignInRetryMessage ??= runtime.messages?.invalidCode
-      runtime.invalidSignInRetryMessageFormat ??= runtime.messages?.invalidCodeFormat
-      runtime.invalidSignInRetryMaxExceededMessage ??= runtime.messages?.maxAttemptsExceeded
-      runtime.oboConnectionName ??= runtime.obo?.connection
-      runtime.oboScopes ??= runtime.obo?.scopes
-      delete runtime.name
-      delete runtime.maxAttempts
-      delete runtime.messages
-      delete runtime.obo
-      runtimeLegacyFormat = 'runtime options (legacy)'
-    }
-
-    if (runtime !== undefined && legacy !== undefined) {
-      return { format: `${runtimeLegacyFormat || 'runtime options'} + .env variables (legacy)`, options: { ...prune(legacy), ...prune(runtime) } }
+    const isRuntimeLegacy = runtimeOptions !== undefined && Object.keys(runtimeOptions).some(key => runtimeLegacyKeys.includes(key))
+
+    let runtimeFormat = 'runtime options'
+    if (isRuntimeLegacy && this.fixType(id, runtimeOptions.type) === AZURE_BOT) {
+      runtimeOptions.azureBotOAuthConnectionName ??= runtimeOptions.name
+      runtimeOptions.invalidSignInRetryMax ??= runtimeOptions.maxAttempts
+      runtimeOptions.invalidSignInRetryMessage ??= runtimeOptions.messages?.invalidCode
+      runtimeOptions.invalidSignInRetryMessageFormat ??= runtimeOptions.messages?.invalidCodeFormat
+      runtimeOptions.invalidSignInRetryMaxExceededMessage ??= runtimeOptions.messages?.maxAttemptsExceeded
+      runtimeOptions.oboConnectionName ??= runtimeOptions.obo?.connection
+      runtimeOptions.oboScopes ??= runtimeOptions.obo?.scopes
+      delete runtimeOptions.name
+      delete runtimeOptions.maxAttempts
+      delete runtimeOptions.messages
+      delete runtimeOptions.obo
+      runtimeFormat = 'runtime options (legacy)'
     }
 
-    if (runtime !== undefined) {
-      return { format: runtimeLegacyFormat || 'runtime options', options: prune(runtime) }
+    const layers: Array<[string, Record<string, any> | undefined]> = [
+      ['external configuration (fallback)', findExternal(external.fallback.agentApplication.userAuthorization.handlers)],
+      ['.env variables (legacy)', runtimeOptions !== undefined || latest === undefined ? legacy : undefined],
+      ['.env variables', runtimeOptions === undefined ? latest : undefined],
+      ['external configuration (overrideEnvironment)', findExternal(external.overrideEnvironment.agentApplication.userAuthorization.handlers)],
+      [runtimeFormat, runtimeOptions],
+      ['external configuration (enforce)', findExternal(external.enforce.agentApplication.userAuthorization.handlers)]
+    ]
+    const activeLayers = layers.filter((layer): layer is [string, Record<string, any>] => layer[1] !== undefined)
+    const options = mergeDefined<AuthorizationOptions[string]>(
+      ...activeLayers.map(([, layer]) => layer)
+    )
+    options.type = this.fixType(id, options.type)
+
+    return {
+      format: activeLayers.map(([format]) => format).join(' + ') || 'empty options',
+      options
     }
-
-    if (latest !== undefined) {
-      return { format: '.env variables', options: prune(latest) }
-    }
-
-    if (legacy !== undefined) {
-      // Note: this should never happen, as legacy requires runtime to be present.
-      // However, we show a warning just in case to detect if something goes wrong.
-      logger.warn(this.prefix(id, 'Legacy environment variable configuration detected without a corresponding runtime options configuration.'))
-      return { format: '.env variables (legacy)', options: prune(legacy) }
-    }
-
-    return { format: 'empty options', options: {} }
   }
 }