SidecarConnectionSettings interface

Package:
@microsoft/agents-hosting

Connection settings for the Entra Agent ID sidecar (agent container) authentication provider, used when a connection's authType is 'EntraAuthSideCar'.

Extends
ConnectionSettingsBase

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.

Properties

blueprintServiceName

The sidecar downstream API name used to acquire the Blueprint (agent application) token for the agentic FIC chain.
bypassLocalNetworkRestriction

When true, disables the loopback/private-address safety check on the resolved sidecar base URL.
requestTimeout

HTTP request timeout (in milliseconds) for sidecar calls.
retryCount

Number of retry attempts for transient sidecar failures (5xx, 408, 429, network/timeout).
serviceName

The configured downstream API service name in the sidecar's DownstreamApis configuration.
sidecarBaseUrl

Optional base URL of the Entra Agent ID sidecar (agent container).

Inherited Properties

altBlueprintConnectionName

An optional alternative blueprint Connection name used when constructing a connector client.
alternateBlueprintConnectionName

Alias of altBlueprintConnectionName named to match the .NET AlternateBlueprintConnectionName connection setting exactly.
authority
authorityEndpoint

Entra Authentication Endpoint to use.
authType

The authentication type for the connection.
clientId

The client ID for the authentication configuration. Required in production.
connectionName

The connection name for the authentication configuration.
issuers

A list of valid issuers for the authentication configuration.
scope
scopes

The scopes for the authentication configuration.
tenantId

The tenant ID for the authentication configuration.
validateIssuer

Whether to validate the token issuer against issuers.

Property Details

blueprintServiceName

The sidecar downstream API name used to acquire the Blueprint (agent application) token for the agentic FIC chain.

blueprintServiceName?: string

Property Value

string

Remarks

Only used when authType is 'EntraAuthSideCar'. Defaults to 'agenticblueprint'. This downstream API must be configured app-only with the api://AzureAdTokenExchange/.default scope.

bypassLocalNetworkRestriction

When true, disables the loopback/private-address safety check on the resolved sidecar base URL.

bypassLocalNetworkRestriction?: boolean

Property Value

boolean

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'.

requestTimeout

HTTP request timeout (in milliseconds) for sidecar calls.

requestTimeout?: number

Property Value

number

Remarks

Only used when authType is 'EntraAuthSideCar'. Defaults to 30000 (30 seconds).

retryCount

Number of retry attempts for transient sidecar failures (5xx, 408, 429, network/timeout).

retryCount?: number

Property Value

number

Remarks

Only used when authType is 'EntraAuthSideCar'. Defaults to 3.

serviceName

The configured downstream API service name in the sidecar's DownstreamApis configuration.

serviceName?: string

Property Value

string

Remarks

Only used when authType is 'EntraAuthSideCar'. Defaults to 'default'.

sidecarBaseUrl

Optional base URL of the Entra Agent ID sidecar (agent container).

sidecarBaseUrl?: string

Property Value

string

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.

Inherited Property Details

altBlueprintConnectionName

An optional alternative blueprint Connection name used when constructing a connector client.

altBlueprintConnectionName?: string

Property Value

string

Remarks

Equivalent to the .NET AlternateBlueprintConnectionName connection setting. alternateBlueprintConnectionName is an alias of this property that matches the .NET name exactly; when both are provided this property takes precedence.

Inherited From ConnectionSettingsBase.altBlueprintConnectionName

alternateBlueprintConnectionName

Alias of altBlueprintConnectionName named to match the .NET AlternateBlueprintConnectionName connection setting exactly.

alternateBlueprintConnectionName?: string

Property Value

string

Remarks

Provided for stricter .NET parity. The two properties are kept in sync during configuration normalization; altBlueprintConnectionName takes precedence when both are set.

Inherited From ConnectionSettingsBase.alternateBlueprintConnectionName

authority

Warning

This API is now deprecated.

Use authorityEndpoint instead.

Entra Authentication Endpoint to use.

authority?: string

Property Value

string

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

Inherited From ConnectionSettingsBase.authority

authorityEndpoint

Entra Authentication Endpoint to use.

authorityEndpoint?: string

Property Value

string

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

Inherited From ConnectionSettingsBase.authorityEndpoint

authType

The authentication type for the connection.

authType?: string

Property Value

string

Inherited From ConnectionSettingsBase.authType

clientId

The client ID for the authentication configuration. Required in production.

clientId?: string

Property Value

string

Inherited From ConnectionSettingsBase.clientId

connectionName

The connection name for the authentication configuration.

connectionName?: string

Property Value

string

Inherited From ConnectionSettingsBase.connectionName

issuers

A list of valid issuers for the authentication configuration.

issuers?: string[]

Property Value

string[]

Inherited From ConnectionSettingsBase.issuers

scope

Warning

This API is now deprecated.

Use scopes instead.

scope?: string

Property Value

string

Inherited From ConnectionSettingsBase.scope

scopes

The scopes for the authentication configuration.

scopes?: string[]

Property Value

string[]

Inherited From ConnectionSettingsBase.scopes

tenantId

The tenant ID for the authentication configuration.

tenantId?: string

Property Value

string

Inherited From ConnectionSettingsBase.tenantId

validateIssuer

Whether to validate the token issuer against issuers.

validateIssuer?: boolean

Property Value

boolean

Remarks

Disabled by default for backward compatibility. Tenant-to-issuer binding is always applied independently when both claims contain comparable tenant GUIDs.

Inherited From ConnectionSettingsBase.validateIssuer