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. Learn more

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

  • SingleTenant / MultiTenant
  • Client Secret
  • Client Certificate
  • User Assigned Managed Identities
  • Federated Identitiy Credentials

Note

MultiTenant requires the Azure Bot instance to be configured as Multi Tenant and the EntraID app registration to be configured as Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant), and only supports Client Secret or Client Certificate. 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 loadBotAuthConfigFromEnv(): AuthConfiguration. The CloudAdapter instance requires to be initialized with the AuthConfiguration.

Based on the provided variables the authentication type will be infered as described below.

Single Tenant with client secret

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

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

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

tenantId={tenant-id-guid}
clientId={app-id-guid}
FICClientId={client-id-of-the-FIC}

For more details, see Authentication using Federated Identity Credentials.

Multi Tenant with ClientSecret

clientId={app-id-guid}
clientSecret={app-registration-secret}

Multi Tenant with Client Certificate

clientId={app-id-guid}
certPemFile={path-to-pem-file}
certKeyFile={path-to-key-file}

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

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