MsalConnectionSettings interface

Package:
@microsoft/agents-hosting

Connection settings for the MSAL-backed authentication providers (the default providers used for every AuthType except EntraAuthSideCar).

Extends
ConnectionSettingsBase

Remarks

Mirrors the .NET Microsoft.Agents.Authentication.Msal.Model.ConnectionSettings class. Node.js uses PEM certificate files (certPemFile/certKeyFile) rather than the Windows certificate store, so the .NET CertThumbprint/CertSubjectName/CertStoreName/ValidCertificateOnly settings have no JS equivalent; all other MSAL properties map one-to-one.

Properties

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

The path to the certificate key file.
certPemFile

The path to the certificate PEM file.
clientSecret

The client secret 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).
msalRetryCount

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

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

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

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

certKeyFile

The path to the certificate key file.

certKeyFile?: string

Property Value

string

certPemFile

The path to the certificate PEM file.

certPemFile?: string

Property Value

string

clientSecret

The client secret for the authentication configuration.

clientSecret?: string

Property Value

string

federatedClientId

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

federatedClientId?: string

Property Value

string

federatedTokenFile

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

federatedTokenFile?: string

Property Value

string

FICClientId

Warning

This API is now deprecated.

Use federatedClientId instead.

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

FICClientId?: string

Property Value

string

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.

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.

sendX5C

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

sendX5C?: boolean

Property Value

boolean

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