Share via

Configure authentication in a JavaScript agent

The JavaScript SDK requires an AuthenticationProvider to obtain JWT tokens to send activities to the target channel. To learn more, see Access tokens in the Microsoft identity platform

The package @microsoft/agents-hosting provides a default authentication provider based on MSAL, that can be configured for the following types of credentials:

  • Client Secret
  • Client Certificate
  • User Assigned Managed Identities
  • Federated Identity Credentials (FIC)

Single-tenant vs multitenant

Client Secret and Client Certificate authentication support both single-tenant and multitenant configurations.

User Assigned Managed Identities and Federated Identity Credentials only support single-tenant configurations.

Note

For multitenant, you need to configure the Azure Bot instance as multitenant and the Microsoft EntraID app registration must be configured as Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant). To learn more, see Single and multitenant apps

Environment variables for each authentication type

The configuration is obtained at runtime from environment variables, using the helper function loadAuthConfigFromEnv(): AuthConfiguration. The CloudAdapter instance requires to be initialized with the AuthConfiguration.

Based on the provided variables, the authentication type is inferred as described below.

Single-tenant with Client Secret

Setting Name Type Default Value Description
tenantId String Null The Microsoft Entra ID tenant ID for the app registration.
clientId String Null The client ID (app ID) of the app registration.
clientSecret String Null The secret associated with the app registration. Should only be used for testing and development purposes. 
tenantId={tenant-id-guid}
clientId={app-id-guid}
clientSecret={app-registration-secret}

This is the recommended configuration for local development.

Single-tenant with Client Certificate

Setting Name Type Default Value Description
tenantId String Null The Microsoft Entra ID tenant ID for the app registration.
clientId String Null The client ID (app ID) of the app registration.
certPemFile String Null Path to the PEM certificate file.
certKeyFile String Null Path to the private key file for the certificate. 
tenantId={tenant-id-guid}
clientId={app-id-guid}
certPemFile={path-to-pem-file}
certKeyFile={path-to-key-file}

Note

The key file should not use any password.

Single-tenant with User-Assigned Managed Identity

Setting Name Type Default Value Description
tenantId String Null The Microsoft Entra ID tenant ID for the app registration.
clientId String Null The managed identity client ID to use when creating the access token. 
tenantId={tenant-id-guid}
clientId={app-id-guid}

This is the recommended configuration for production scenarios. To learn more, see Managed identities for Azure resources.

Note

The agent needs to run in any Azure service supporting Managed Identities. To see which Azure services support managed identities, see Managed identities for Azure resources. The managed identity should match the one configured in EntraID. For more information, see How to configure managed identities.

Single-tenant with Federated Identity Credential

Setting Name Type Default Value Description
tenantId String Null The Microsoft Entra ID tenant ID for the app registration.
clientId String Null The client ID (app ID) of the app registration.
FICClientId String Null The managed identity client ID of the Federated Identity Credential. 
tenantId={tenant-id-guid}
clientId={app-id-guid}
FICClientId={client-id-of-the-FIC}

For more details, see Authentication using Federated Identity Credentials.

Multitenant with ClientSecret

Setting Name Type Default Value Description
clientId String Null The client ID (app ID) of the app registration.
clientSecret String Null The secret associated with the app registration. Should only be used for testing and development purposes. 
clientId={app-id-guid}
clientSecret={app-registration-secret}

Multitenant with Client Certificate

Setting Name Type Default Value Description
clientId String Null The client ID (app ID) of the app registration.
certPemFile String Null Path to the PEM certificate file.
certKeyFile String Null Path to the private key file for the certificate. 
clientId={app-id-guid}
certPemFile={path-to-pem-file}
certKeyFile={path-to-key-file}

Backward compatibility with Azure Bot Framework SDK

To load the configuration using the same format as the Azure Bot Framework SDK, we provide another helper function loadBotAuthConfigFromEnv(): AuthConfiguration.

Setting Name Type Default Value Description
MicrosoftAppTenantId String Null The Microsoft Entra ID tenant ID (legacy Bot Framework SDK format).
MicrosoftAppId String Null The client ID (app ID) of the app registration (legacy Bot Framework SDK format).
MicrosoftAppPassword String Null The app secret (legacy Bot Framework SDK format). 
MicrosoftAppTenantId={tenant-id-guid}
MicrosoftAppId={app-id-guid}
MicrosoftAppPassword={app-registration-secret}

Custom Authentication Provider

Users requiring a customized authentication provider can implement the interface:

export interface AuthProvider {
  getAccessToken: (authConfig: AuthConfiguration, scope: string) => Promise<string>
}

As an example, let's implement the AuthProvider using @azure/identity:

import { EnvironmentCredential } from "@azure/identity"
import { AuthProvider, AuthConfiguration } from "@microsoft/agents-bot-hosting"
class DevTokenProvider implements AuthProvider {
  async getAccessToken(authConfig: AuthConfiguration): Promise<string> {
    const id = new EnvironmentCredential()
    const tokenResponse = await id.getToken("https://api.botframework.com/.default")
    return tokenResponse.token
  }

To instantiate the CloudAdapter using the DevTokenProvider

const adapter = new CloudAdapter(authConfig, new DevTokenProvider())
  • Last updated on