ConnectionSettings interface

Package:
@microsoft/agents-hosting

The complete settings for a single connection, across every provider.

Extends

MsalConnectionSettings,SidecarConnectionSettings

Remarks

This is the per-connection unit that an AuthProvider consumes: it combines the common base (ConnectionSettingsBase) with the MSAL settings (MsalConnectionSettings) and the Entra sidecar settings (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 AuthConfiguration container: each value in AuthConfiguration.connections is the settings for one connection. It parallels the .NET IConnectionSettings (a single connection's settings) as distinct from the connection registry. AuthConfiguration extends this type for backward compatibility (it doubles as the settings for the legacy single connection).

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

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

The path to the certificate key file.
certPemFile

The path to the certificate PEM file.
clientId

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

The client secret for the authentication configuration.
connectionName

The connection name for the authentication configuration.
federatedClientId

The federated client ID for the authentication configuration, used for workload identity federation scenarios.
federatedTokenFile

The path to the federated token file used for Workload Identity authentication.
FICClientId
idpmResource

Sets the resource URL for Identity Proxy Manager (IDPM).
issuers

A list of valid issuers for the authentication configuration.
msalRetryCount

Maximum number of retries for an MSAL HTTP request that returns status 408.
requestTimeout

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

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

The scopes for the authentication configuration.
sendX5C

Indicates whether to send the X5C param or not (for SNI authentication).
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).
tenantId

The tenant ID for the authentication configuration.
validateIssuer

Whether to validate the token issuer against issuers.
WIDAssertionFile

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 MsalConnectionSettings.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 MsalConnectionSettings.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 MsalConnectionSettings.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 MsalConnectionSettings.authorityEndpoint

authType

The authentication type for the connection.

authType?: string

Property Value

string

Inherited From MsalConnectionSettings.authType

azureRegion

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

Property Value

string

Inherited From MsalConnectionSettings.azureRegion

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.

Inherited From SidecarConnectionSettings.blueprintServiceName

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

Inherited From SidecarConnectionSettings.bypassLocalNetworkRestriction

certKeyFile

The path to the certificate key file.

certKeyFile?: string

Property Value

string

Inherited From MsalConnectionSettings.certKeyFile

certPemFile

The path to the certificate PEM file.

certPemFile?: string

Property Value

string

Inherited From MsalConnectionSettings.certPemFile

clientId

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

clientId?: string

Property Value

string

Inherited From MsalConnectionSettings.clientId

clientSecret

The client secret for the authentication configuration.

clientSecret?: string

Property Value

string

Inherited From MsalConnectionSettings.clientSecret

connectionName

The connection name for the authentication configuration.

connectionName?: string

Property Value

string

Inherited From MsalConnectionSettings.connectionName

federatedClientId

The federated client ID for the authentication configuration, used for workload identity federation scenarios.

federatedClientId?: string

Property Value

string

Inherited From MsalConnectionSettings.federatedClientId

federatedTokenFile

The path to the federated token file used for Workload Identity authentication.

federatedTokenFile?: string

Property Value

string

Inherited From MsalConnectionSettings.federatedTokenFile

FICClientId

Warning

This API is now deprecated.

Use federatedClientId instead.

The FIC (First-Party Integration Channel) client ID.

FICClientId?: string

Property Value

string

Inherited From MsalConnectionSettings.FICClientId

idpmResource

Sets the resource URL for Identity Proxy Manager (IDPM).

idpmResource?: string

Property Value

string

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.

Inherited From MsalConnectionSettings.idpmResource

issuers

A list of valid issuers for the authentication configuration.

issuers?: string[]

Property Value

string[]

Inherited From MsalConnectionSettings.issuers

msalRetryCount

Maximum number of retries for an MSAL HTTP request that returns status 408.

msalRetryCount?: number

Property Value

number

Remarks

The initial request is not included in this count. Set to 0 to disable retries. Defaults to 2.

Inherited From MsalConnectionSettings.msalRetryCount

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

Inherited From SidecarConnectionSettings.requestTimeout

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.

Inherited From SidecarConnectionSettings.retryCount

scope

Warning

This API is now deprecated.

Use scopes instead.

scope?: string

Property Value

string

Inherited From MsalConnectionSettings.scope

scopes

The scopes for the authentication configuration.

scopes?: string[]

Property Value

string[]

Inherited From MsalConnectionSettings.scopes

sendX5C

Indicates whether to send the X5C param or not (for SNI authentication).

sendX5C?: boolean

Property Value

boolean

Inherited From MsalConnectionSettings.sendX5C

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

Inherited From SidecarConnectionSettings.serviceName

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 From SidecarConnectionSettings.sidecarBaseUrl

tenantId

The tenant ID for the authentication configuration.

tenantId?: string

Property Value

string

Inherited From MsalConnectionSettings.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 MsalConnectionSettings.validateIssuer

WIDAssertionFile

Warning

This API is now deprecated.

Use authType set to 'WorkloadIdentity' and federatedTokenFile instead.

The path to K8s provided token.

WIDAssertionFile?: string

Property Value

string

Inherited From MsalConnectionSettings.WIDAssertionFile