@microsoft/agents-hosting 1.6.1 → 1.7.0-beta.5.g67b2005119

package/src/auth/settings.ts

@@ -4,13 +4,29 @@
  */
 
 import { debug } from '@microsoft/agents-telemetry'
-import type { ConnectionMapItem } from './msalConnectionManager'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
+import type { MsalConnectionSettings } from './msal/msalConnectionSettings'
+import type { SidecarConnectionSettings } from './sidecar/sidecarConnectionSettings'
+
+export type { MsalConnectionSettings } from './msal/msalConnectionSettings'
+export type { SidecarConnectionSettings } from './sidecar/sidecarConnectionSettings'
 
 const logger = debug('agents:authConfiguration')
 
 const DEFAULT_CONNECTION = 'serviceConnection'
 const AUTHORITY_DEFAULT = 'https://login.microsoftonline.com'
 
+/**
+ * A single entry in the connections map used to route an inbound activity
+ * (matched by audience and/or serviceUrl) to a named connection.
+ */
+export interface ConnectionMapItem {
+  serviceUrl: string
+  audience?: string
+  connection: string
+}
+
 export const DEFAULT_CONNECTION_MAP: ConnectionMapItem = { serviceUrl: '*', connection: DEFAULT_CONNECTION }
 
 export type ConnectionKeys = keyof Omit<AuthConfiguration, 'connections' | 'connectionsMap'>
@@ -53,8 +69,14 @@ export function applyDefaultSettings (config: AuthConfiguration) {
     settings.authority = settings.authorityEndpoint
   }
 
+  // .NET parity alias: keep altBlueprintConnectionName and alternateBlueprintConnectionName in sync.
+  settings.altBlueprintConnectionName ??= settings.alternateBlueprintConnectionName
+  if (settings.altBlueprintConnectionName) {
+    settings.alternateBlueprintConnectionName = settings.altBlueprintConnectionName
+  }
+
   if (!settings.clientId && process.env.NODE_ENV?.toLowerCase() === 'production') {
-    throw new Error('ClientId required in production')
+    throw ExceptionHelper.generateException(Error, Errors.ClientIdRequiredInProduction)
   }
 
   const defaultConnections = settings.connections?.size
@@ -171,9 +193,16 @@ function getDefaultIssuers (tenantId: string, authority: string) : string[] {
 }
 
 /**
- * Represents the authentication configuration.
+ * Connection-level settings common to every authentication provider.
+ *
+ * @remarks
+ * Mirrors the .NET `Microsoft.Agents.Authentication.ConnectionSettingsBase` abstract class: these are
+ * the credential-agnostic properties shared by all connection types. Provider-specific settings
+ * extend this base (see {@link MsalConnectionSettings} for MSAL and {@link SidecarConnectionSettings}
+ * for the Entra sidecar). The active provider for a connection is selected
+ * by {@link ConnectionSettingsBase.authType | authType}; see `AuthProviderFactory`.
  */
-export interface AuthConfiguration {
+export interface ConnectionSettingsBase {
   /**
    * The tenant ID for the authentication configuration.
    */
@@ -185,24 +214,9 @@ export interface AuthConfiguration {
   clientId?: string
 
   /**
-   * The client secret for the authentication configuration.
-   */
-  clientSecret?: string
-
-  /**
-   * The path to the certificate PEM file.
-   */
-  certPemFile?: string
-
-  /**
-   * The path to the certificate key file.
-   */
-  certKeyFile?: string
-
-  /**
-   * Indicates whether to send the X5C param or not (for SNI authentication).
+   * The authentication type for the connection.
    */
-  sendX5C?: boolean
+  authType?: AuthType | string
 
   /**
    * A list of valid issuers for the authentication configuration.
@@ -214,13 +228,6 @@ export interface AuthConfiguration {
    */
   connectionName?: string
 
-  /**
-   * @deprecated Use federatedClientId instead.
-   *
-   * The FIC (First-Party Integration Channel) client ID.
-   */
-  FICClientId?: string,
-
   /**
    * @deprecated Use authorityEndpoint instead.
    *
@@ -234,78 +241,89 @@ export interface AuthConfiguration {
   authority?: string
 
   /**
-   * @deprecated Use scopes instead.
+   * Entra Authentication Endpoint to use.
+   *
+   * @remarks
+   * If not populated the Entra Public Cloud endpoint is assumed.
+   * This example of Public Cloud Endpoint is https://login.microsoftonline.com
+   * see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
    */
-  scope?: string
+  authorityEndpoint?: string
 
   /**
-   * A map of connection names to their respective authentication configurations.
+   * @deprecated Use scopes instead.
    */
-  connections?: Map<string, AuthConfiguration>
+  scope?: string
 
   /**
-   * A list of connection map items to map service URLs to connection names.
+   * The scopes for the authentication configuration.
    */
-  connectionsMap?: ConnectionMapItem[],
+  scopes?: string[]
 
   /**
    * An optional alternative blueprint Connection name used when constructing a connector client.
-   */
-  altBlueprintConnectionName?: string
-
-  /**
-   * @deprecated Use `authType` set to `'WorkloadIdentity'` and `federatedTokenFile` instead.
    *
-   * The path to K8s provided token.
-   */
-  WIDAssertionFile?: string
-
-  /**
-   * The Azure region for ESTS-R regional token acquisition (e.g. 'westus', 'eastus').
-   * When set, MSAL routes token requests to the specified regional endpoint.
-   * See https://learn.microsoft.com/en-us/entra/msal/javascript/node/regional-authorities for details.
-   */
-  azureRegion?: string
-
-  /**
-   * The authentication type for the connection.
-   */
-  authType?: AuthType | string
-
-  /**
-   * The path to the federated token file used for Workload Identity authentication.
+   * @remarks
+   * Equivalent to the .NET `AlternateBlueprintConnectionName` connection setting. {@link alternateBlueprintConnectionName}
+   * is an alias of this property that matches the .NET name exactly; when both are provided this property takes precedence.
    */
-  federatedTokenFile?: string
+  altBlueprintConnectionName?: string
 
   /**
-   * Sets the resource URL for Identity Proxy Manager (IDPM).
+   * Alias of {@link altBlueprintConnectionName} named to match the .NET `AlternateBlueprintConnectionName`
+   * connection setting exactly.
    *
    * @remarks
-   * Set this to the appropriate resource identifier when the application is running in an environment,
-   * such as a Foundry container, that exposes Managed Identity through a container-specific IMDS endpoint.
-   * This setting is only meaningful when using Identity Proxy Manager (AuthType.IdentityProxyManager) for authentication.
+   * Provided for stricter .NET parity. The two properties are kept in sync during configuration normalization;
+   * {@link altBlueprintConnectionName} takes precedence when both are set.
    */
-  idpmResource?: string
+  alternateBlueprintConnectionName?: string
+}
 
+/**
+ * The complete settings for a single connection, across every provider.
+ *
+ * @remarks
+ * This is the per-connection unit that an `AuthProvider` consumes: it combines the common base
+ * ({@link ConnectionSettingsBase}) with the MSAL settings ({@link MsalConnectionSettings}) and the
+ * Entra sidecar settings ({@link SidecarConnectionSettings}). The active provider for a connection is
+ * selected by `authType`, so only the subset of these properties relevant to that provider is used.
+ *
+ * Conceptually this is the consumer-facing counterpart to the {@link AuthConfiguration} *container*:
+ * each value in {@link AuthConfiguration.connections} is the settings for one connection. It parallels
+ * the .NET `IConnectionSettings` (a single connection's settings) as distinct from the connection
+ * registry. {@link AuthConfiguration} extends this type for backward compatibility (it doubles as the
+ * settings for the legacy single connection).
+ */
+export interface ConnectionSettings extends MsalConnectionSettings, SidecarConnectionSettings {}
+
+/**
+ * Represents the authentication configuration.
+ *
+ * @remarks
+ * The agent-level authentication container. It owns the connection registry
+ * (`connections`/`connectionsMap`) and, for backward compatibility, also extends
+ * {@link ConnectionSettings} so the legacy single-connection shape (a flat config with `clientId`,
+ * `clientSecret`, etc.) keeps working — in that mode the top-level object *is* the one connection's
+ * settings. The active provider for each connection is dispatched by `authType` via
+ * `AuthProviderFactory`, so a single connection only uses the subset of these properties relevant to
+ * its provider.
+ */
+export interface AuthConfiguration extends ConnectionSettings {
   /**
-   * Entra Authentication Endpoint to use.
+   * The connection registry: a map of connection name to that connection's settings.
    *
    * @remarks
-   * If not populated the Entra Public Cloud endpoint is assumed.
-   * This example of Public Cloud Endpoint is https://login.microsoftonline.com
-   * see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
-   */
-  authorityEndpoint?: string
-
-  /**
-   * The federated client ID for the authentication configuration, used for workload identity federation scenarios.
+   * Each value is the {@link ConnectionSettings} for one connection (typed as {@link AuthConfiguration}
+   * for backward compatibility; only the connection-settings subset is consumed). An `AuthProvider` is
+   * created per entry by `AuthProviderFactory`, dispatched by `authType`.
    */
-  federatedClientId?: string
+  connections?: Map<string, AuthConfiguration>
 
   /**
-   * The scopes for the authentication configuration.
+   * A list of connection map items to map service URLs to connection names.
    */
-  scopes?: string[]
+  connectionsMap?: ConnectionMapItem[]
 }
 
 /**
@@ -319,5 +337,42 @@ export enum AuthType {
   SystemManagedIdentity = 'SystemManagedIdentity',
   FederatedCredentials = 'FederatedCredentials',
   WorkloadIdentity = 'WorkloadIdentity',
-  IdentityProxyManager = 'IdentityProxyManager'
+  IdentityProxyManager = 'IdentityProxyManager',
+  EntraAuthSideCar = 'EntraAuthSideCar'
+}
+
+/**
+ * Resolves the authentication type for a given authentication configuration.
+ * @remarks
+ * The function checks various properties of the `authConfig` object to determine the appropriate authentication type.
+ * It returns a string representing the resolved authentication type or 'unknown' if it cannot be determined.
+ * @param authConfig The authentication configuration object.
+ * @returns The resolved authentication type as a string or 'unknown' if it cannot be determined.
+ */
+export function resolveAuthType (authConfig?: AuthConfiguration): AuthType | string {
+  if (!authConfig) {
+    return 'none'
+  }
+  if (authConfig.authType) {
+    return authConfig.authType
+  }
+  if (authConfig.WIDAssertionFile !== undefined) {
+    return AuthType.WorkloadIdentity
+  }
+  if (authConfig.federatedClientId !== undefined || authConfig.FICClientId !== undefined) {
+    return AuthType.FederatedCredentials
+  }
+  if (authConfig.clientSecret !== undefined) {
+    return AuthType.ClientSecret
+  }
+  if (authConfig.certPemFile !== undefined && authConfig.certKeyFile !== undefined) {
+    return AuthType.Certificate
+  }
+  if (authConfig.clientSecret === undefined && authConfig.certPemFile === undefined && authConfig.certKeyFile === undefined) {
+    return AuthType.UserManagedIdentity
+  }
+  if (authConfig.idpmResource !== undefined) {
+    return AuthType.IdentityProxyManager
+  }
+  return 'unknown'
 }

package/src/auth/sidecar/sidecarAuthProvider.ts

@@ -0,0 +1,234 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { debug } from '@microsoft/agents-telemetry'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../../errorHelper'
+import { AuthConfiguration } from '../authConfiguration'
+import { AuthProvider } from '../authProvider'
+import { SidecarHttpClient } from './sidecarHttpClient'
+import { resolveTokenExpiry } from './sidecarTokenExpiry'
+import {
+  ResolvedSidecarConnectionSettings,
+  SidecarRequestOptions,
+  toSidecarConnectionSettings
+} from './sidecarModels'
+
+const logger = debug('agents:sidecar')
+
+const GUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+// Refresh slightly ahead of the real expiry so callers never receive a token that expires mid-flight.
+const EXPIRY_BUFFER_MS = 30 * 1000
+
+// Hard upper bound on cached entries; protects memory when many distinct identities are served.
+const MAX_CACHE_ENTRIES = 500
+
+interface CachedToken {
+  token: string
+  expiresOn: number
+}
+
+/**
+ * Authentication provider that delegates token acquisition to the Microsoft Entra Agent ID
+ * sidecar (agent container). This replaces MSAL at the connection layer, using the sidecar's
+ * `/AuthorizationHeaderUnauthenticated/{serviceName}` endpoint for app-only and agentic identity
+ * flows. The sidecar performs the full Blueprint→Instance→User chain internally; no MSAL exchange is
+ * performed in-process.
+ */
+export class SidecarAuthProvider implements AuthProvider {
+  public readonly connectionSettings?: AuthConfiguration
+  private readonly _settings: ResolvedSidecarConnectionSettings
+  private readonly _httpClient: SidecarHttpClient
+  private readonly _tokenCache: Map<string, CachedToken> = new Map()
+
+  /**
+   * Creates a new {@link SidecarAuthProvider}.
+   * @param connectionSettings The connection authentication configuration.
+   */
+  constructor (connectionSettings?: AuthConfiguration) {
+    this.connectionSettings = connectionSettings
+    this._settings = toSidecarConnectionSettings(connectionSettings)
+
+    const resolvedUrl = SidecarHttpClient.resolveBaseUrl(this._settings.sidecarBaseUrl)
+    SidecarHttpClient.validateBaseUrl(resolvedUrl, this._settings.bypassLocalNetworkRestriction)
+    this._httpClient = new SidecarHttpClient(resolvedUrl, this._settings.requestTimeout, this._settings.retryCount)
+    logger.debug('SidecarAuthProvider initialized serviceName=%s blueprintServiceName=%s', this._settings.serviceName, this._settings.blueprintServiceName)
+  }
+
+  /**
+   * Acquires an app-only access token from the sidecar.
+   * @param scope The scope for the token.
+   */
+  async getAccessToken (scope: string): Promise<string>
+  /**
+   * Acquires an app-only access token from the sidecar.
+   * @param authConfig The authentication configuration. Ignored by the sidecar provider, which
+   * owns the credential and derives the token from its configured service name; accepted only to
+   * satisfy the {@link AuthProvider} overload.
+   * @param scope The scope for the token.
+   */
+  async getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string>
+  async getAccessToken (authConfigOrScope: AuthConfiguration | string, scope?: string): Promise<string> {
+    const actualScope = typeof authConfigOrScope === 'string' ? authConfigOrScope : scope
+    const options: SidecarRequestOptions = {
+      scopes: actualScope ? [actualScope] : this._settings.scopes,
+      requestAppToken: true
+    }
+    return this.getCachedToken(this._settings.serviceName, options)
+  }
+
+  /**
+   * Acquires the Blueprint (agent application) token from the sidecar.
+   * @param tenantId The tenant ID.
+   * @param agentAppInstanceId The agent instance ID (from the inbound activity); maps to `AgentIdentity`.
+   */
+  async getAgenticApplicationToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
+    this.ensureConnectionSettings()
+    const options: SidecarRequestOptions = {
+      agentIdentity: agentAppInstanceId,
+      tenant: tenantId
+    }
+    return this.getCachedToken(this._settings.blueprintServiceName, options)
+  }
+
+  /**
+   * Acquires the autonomous agent (instance) token from the sidecar for the configured resource.
+   * @param tenantId The tenant ID.
+   * @param agentAppInstanceId The agent instance ID (from the inbound activity); maps to `AgentIdentity`.
+   */
+  async getAgenticInstanceToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
+    this.ensureConnectionSettings()
+    const options: SidecarRequestOptions = {
+      agentIdentity: agentAppInstanceId,
+      requestAppToken: true,
+      tenant: tenantId,
+      scopes: this._settings.scopes
+    }
+    return this.getCachedToken(this._settings.serviceName, options)
+  }
+
+  /**
+   * Acquires the agentic user token from the sidecar for the configured resource.
+   * @param tenantId The tenant ID.
+   * @param agentAppInstanceId The agent instance ID (from the inbound activity); maps to `AgentIdentity`.
+   * @param upn The agentic user identifier. A GUID is sent as `AgentUserId`; otherwise as `AgentUsername`.
+   * @param scopes The OAuth scopes to request.
+   */
+  async getAgenticUserToken (tenantId: string, agentAppInstanceId: string, upn: string, scopes: string[]): Promise<string> {
+    this.ensureConnectionSettings()
+    const isObjectId = GUID_REGEX.test(upn ?? '')
+    const options: SidecarRequestOptions = {
+      agentIdentity: agentAppInstanceId,
+      agentUsername: isObjectId ? undefined : upn,
+      agentUserId: isObjectId ? upn : undefined,
+      tenant: tenantId,
+      scopes: scopes ?? this._settings.scopes
+    }
+    return this.getCachedToken(this._settings.serviceName, options)
+  }
+
+  /**
+   * On-behalf-of token exchange — not supported by the sidecar provider in Phase 1.
+   */
+  async acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+  async acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
+  async acquireTokenOnBehalfOf (
+    _authConfigOrScopes: AuthConfiguration | string[],
+    _scopesOrOboAssertion?: string[] | string,
+    _oboAssertion?: string
+  ): Promise<string> {
+    throw ExceptionHelper.generateException(Error, Errors.OnBehalfOfNotSupportedBySidecar)
+  }
+
+  /**
+   * Checks sidecar availability via the `/healthz` endpoint.
+   * @returns `true` when the sidecar is reachable and healthy.
+   */
+  async isHealthy (): Promise<boolean> {
+    return this._httpClient.isHealthy()
+  }
+
+  private ensureConnectionSettings (): void {
+    if (!this.connectionSettings) {
+      throw ExceptionHelper.generateException(Error, Errors.SidecarConnectionSettingsRequired)
+    }
+  }
+
+  private async getCachedToken (serviceName: string, options: SidecarRequestOptions): Promise<string> {
+    const forceRefresh = options.forceRefresh === true
+    const cacheKey = SidecarAuthProvider.buildCacheKey(serviceName, options)
+
+    const cached = this.cacheGet(cacheKey, forceRefresh)
+    if (cached) {
+      return cached
+    }
+
+    const result = await this._httpClient.getAuthorizationHeaderUnauthenticated(serviceName, options)
+    // The hosting stack always transmits the token as `Bearer {token}`. Reject any other scheme
+    // (e.g. PoP) rather than silently emitting an invalid Authorization header.
+    if (result.scheme && result.scheme.toLowerCase() !== 'bearer') {
+      throw ExceptionHelper.generateException(Error, Errors.SidecarUnsupportedAuthScheme, undefined, { scheme: result.scheme })
+    }
+    this.cacheSet(cacheKey, { token: result.token, expiresOn: resolveTokenExpiry(result.token) })
+    return result.token
+  }
+
+  private cacheGet (cacheKey: string, forceRefresh: boolean): string | undefined {
+    const cached = this._tokenCache.get(cacheKey)
+    if (cached) {
+      if (!forceRefresh && cached.expiresOn >= Date.now() + EXPIRY_BUFFER_MS) {
+        return cached.token
+      }
+      this._tokenCache.delete(cacheKey)
+    }
+    return undefined
+  }
+
+  private cacheSet (cacheKey: string, token: CachedToken): void {
+    this._tokenCache.set(cacheKey, token)
+    if (this._tokenCache.size > MAX_CACHE_ENTRIES) {
+      this.pruneExpiredEntries()
+      if (this._tokenCache.size > MAX_CACHE_ENTRIES) {
+        this.evictNearestExpiry()
+      }
+    }
+  }
+
+  private pruneExpiredEntries (): void {
+    const now = Date.now()
+    for (const [key, value] of this._tokenCache) {
+      if (value.expiresOn <= now) {
+        this._tokenCache.delete(key)
+      }
+    }
+  }
+
+  private evictNearestExpiry (): void {
+    const overflow = this._tokenCache.size - MAX_CACHE_ENTRIES
+    if (overflow <= 0) {
+      return
+    }
+    const sorted = [...this._tokenCache.entries()].sort((a, b) => a[1].expiresOn - b[1].expiresOn)
+    for (let i = 0; i < overflow; i++) {
+      this._tokenCache.delete(sorted[i][0])
+    }
+  }
+
+  private static buildCacheKey (serviceName: string, options: SidecarRequestOptions): string {
+    const scopes = options.scopes
+      ? [...new Set(options.scopes.filter((s) => s && s.trim()))].sort().join(' ')
+      : ''
+    return [
+      serviceName,
+      options.agentIdentity ?? '',
+      options.agentUsername ?? '',
+      options.agentUserId ?? '',
+      options.tenant ?? '',
+      options.requestAppToken === true ? 'app' : 'user',
+      scopes
+    ].join('|')
+  }
+}

package/src/auth/sidecar/sidecarConnectionSettings.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ConnectionSettingsBase } from '../settings'
+
+/**
+ * Connection settings for the Entra Agent ID sidecar (agent container) authentication provider, used when a
+ * connection's `authType` is `'EntraAuthSideCar'`.
+ *
+ * @remarks
+ * Mirrors the .NET `Microsoft.Agents.Authentication.EntraAuthSidecar.Model.SidecarConnectionSettings`
+ * class, which likewise derives from `ConnectionSettingsBase`. These are the configuration-level
+ * properties; they are normalized (with defaults applied) before use by the sidecar token provider.
+ */
+export interface SidecarConnectionSettings extends ConnectionSettingsBase {
+  /**
+   * Optional base URL of the Entra Agent ID sidecar (agent container).
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Resolution order:
+   * `SIDECAR_URL` environment variable > this setting > `http://localhost:5178`.
+   * Regardless of how it is resolved, the host must be a loopback/private address
+   * unless `bypassLocalNetworkRestriction` is set.
+   */
+  sidecarBaseUrl?: string
+
+  /**
+   * The configured downstream API service name in the sidecar's DownstreamApis configuration.
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Defaults to `'default'`.
+   */
+  serviceName?: string
+
+  /**
+   * The sidecar downstream API name used to acquire the Blueprint (agent application) token for the
+   * agentic FIC chain.
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Defaults to `'agenticblueprint'`. This
+   * downstream API must be configured app-only with the `api://AzureAdTokenExchange/.default` scope.
+   */
+  blueprintServiceName?: string
+
+  /**
+   * When `true`, disables the loopback/private-address safety check on the resolved sidecar base URL.
+   *
+   * @remarks
+   * UNSAFE. Leave this `false` in all normal deployments. Only enable it for a carefully validated
+   * private-network configuration where the sidecar is reachable at a non-private address that the
+   * operator explicitly trusts. Only used when `authType` is `'EntraAuthSideCar'`.
+   */
+  bypassLocalNetworkRestriction?: boolean
+
+  /**
+   * HTTP request timeout (in milliseconds) for sidecar calls.
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Defaults to 30000 (30 seconds).
+   */
+  requestTimeout?: number
+
+  /**
+   * Number of retry attempts for transient sidecar failures (5xx, 408, 429, network/timeout).
+   *
+   * @remarks
+   * Only used when `authType` is `'EntraAuthSideCar'`. Defaults to 3.
+   */
+  retryCount?: number
+}