Troubleshooting Bot Framework authentication

APPLIES TO: SDK v4

This guide can help you to troubleshoot authentication issues with your bot by evaluating a series of scenarios to determine where the problem exists.

App ID and password

Bot security is configured by the Microsoft App ID and Microsoft App Password that you obtain when you register your bot with the Bot Framework. These values are typically specified within the bot's configuration file and used to retrieve access tokens from the Microsoft Account service.

If you haven't yet done so, deploy your bot to Azure to obtain a Microsoft App ID and Microsoft App Password that it can use for authentication.

Step 1: Disable security and test on localhost

In this step, you'll verify that your bot is accessible and functional on localhost when security is disabled.

Disable security

To disable security for your bot, edit its configuration settings to remove the values for app ID and password.

"MicrosoftAppId": "",
"MicrosoftAppPassword": ""

const adapter = new BotFrameworkAdapter({
    appId: null,
    appPassword: null
});

class DefaultConfig:
    """ Bot Configuration """
    APP_ID = None
    APP_PASSWORD = None

Test your bot on localhost

Next, test your bot on localhost by using the Bot Framework Emulator.

1. Start your bot on localhost.
2. Start the Bot Framework Emulator.
3. Connect to your bot using the Emulator.
   • Type http://localhost:port-number/api/messages into the Emulator's address bar, where port-number matches the port number shown in the browser where your application is running.
   • Ensure that the Microsoft App ID and Microsoft App Password fields are both empty.
   • Click Connect.
4. To test connectivity to your bot, type some text into the Emulator and press Enter.

If the bot responds to the input and there are no errors in the chat window, you've verified that your bot is accessible and functional on localhost when security is disabled. Proceed to Step 2.

If one or more error(s) are indicated in the chat window, click the error(s) for details. Common issues include:

• The Emulator settings specify an incorrect endpoint for the bot. Make sure you've included the proper port number in the URL and the proper path at the end of the URL, such as /api/messages.
• The Emulator settings specify a bot endpoint that begins with https. On localhost, the endpoint should begin with http.
• The Emulator settings specify a value for the Microsoft App ID field and/or the Microsoft App Password field. Both fields should be empty.
• Security hasn't been disabled of for the bot. Verify that the bot doesn't specify a value for either app ID or password.

Step 2: Verify your bot's app ID and password

In this step, you'll verify that the app ID and password that your bot will use for authentication are valid. (If you don't know these values, obtain them now.)

Issue an HTTP request to the Microsoft login service

These instructions describe how to use cURL to issue an HTTP request to the Microsoft login service. You may use an alternative tool such as Postman, just ensure that the request conforms to the Bot Framework authentication protocol.

To verify that your bot's app ID and password are valid, issue the following request using cURL, replacing APP_ID and APP_PASSWORD with your bot's app ID and password.

curl -k -X POST https://login.partner.microsoftonline.cn/botframework.com/oauth2/v2.0/token -d "grant_type=client_credentials&client_id=APP_ID&client_secret=APP_PASSWORD&scope=https%3A%2F%2Fapi.botframework.azure.cn%2F.default"

This request attempts to exchange your bot's app ID and password for an access token. If the request is successful, you'll receive a JSON payload that contains an access_token property, amongst others.

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAJKV1Q..."}

If the request is successful, you've verified that the app ID and password that you specified in the request are valid. Proceed to Step 3.

If you receive an error in response to the request, examine the response to identify the cause of the error. If the response indicates that the app ID or the password is invalid, obtain the correct values from the Bot Framework Portal and reissue the request with the new values to confirm that they're valid.

Step 3: Enable security and test on localhost

At this point, you've verified that your bot is accessible and functional on localhost when security is disabled and confirmed that the app ID and password that the bot will use for authentication are valid. In this step, you'll verify that your bot is accessible and functional on localhost when security is enabled.

Enable security

Your bot's security relies on Microsoft services, even when your bot is running only on localhost. To enable security for your bot, edit its configuration settings to populate app ID and password with the values that you verified in Step 2. Additionally, make sure your packages are up to date, specifically System.IdentityModel.Tokens.Jwt and Microsoft.IdentityModel.Tokens.

If you're using the Bot Framework SDK for .NET, populate these settings in your appsettings.config or the corresponding values in your appsettings.json file:

<appSettings>
  <add key="MicrosoftAppId" value="APP_ID" />
  <add key="MicrosoftAppPassword" value="PASSWORD" />
</appSettings>

If you're using the Bot Framework SDK for Node.js, populate these settings (or update the corresponding environment variables):

var connector = new builder.ChatConnector({
  appId: 'APP_ID',
  appPassword: 'PASSWORD'
});

Test your bot on localhost

Next, test your bot on localhost by using the Bot Framework Emulator.

1. Start your bot on localhost.
2. Start the Bot Framework Emulator.
3. Connect to your bot using the Emulator.
   • Type http://localhost:port-number/api/messages into the Emulator's address bar, where port-number matches the port number shown in the browser where your application is running.
   • Enter your bot's app ID into the Microsoft App ID field.
   • Enter your bot's password into the Microsoft App Password field.
   • Click Connect.
4. To test connectivity to your bot, type some text into the Emulator and press Enter.

If the bot responds to the input and there are no errors in the chat window, you've verified that your bot is accessible and functional on localhost when security is enabled. Proceed to Step 4.

If one or more error(s) are indicated in the chat window, click the error(s) for details. Common issues include:

• The Emulator settings specify an incorrect endpoint for the bot. Make sure you've included the proper port number in the URL and the proper path at the end of the URL, such as /api/messages.
• The Emulator settings specify a bot endpoint that begins with https. On localhost, the endpoint should begin with http.
• In the Emulator settings, the Microsoft App ID field and/or the Microsoft App Password don't contain valid values. Both fields should be populated and each field should contain the corresponding value that you verified in Step 2.
• Security hasn't been enabled for the bot. Verify that the bot configuration settings specify values for both app ID and password.

Step 4: Test your bot in the cloud

At this point, you've verified that your bot is accessible and functional on localhost when security is disabled, confirmed that your bot's app ID and password are valid, and verified that your bot is accessible and functional on localhost when security is enabled. In this step, you'll deploy your bot to the cloud and verify that it's accessible and functional there with security enabled.

Deploy your bot to the cloud

The Bot Framework requires that bots be accessible from the internet, so you must deploy your bot to a cloud hosting platform such as Azure. Be sure to enable security for your bot prior to deployment, as described in Step 3.

If you deploy your bot to Azure, SSL will automatically be configured for your application, thereby enabling the HTTPS endpoint that the Bot Framework requires. If you deploy to another cloud hosting provider, be sure to verify that your application is configured for SSL so that the bot will have an HTTPS endpoint.

Test your bot

To test your bot in the cloud with security enabled, complete the following steps.

1. Ensure that your bot has been successfully deployed and is running.
2. Sign in to the Azure portal.
3. Navigate to the Azure Bot resource for your bot within the portal.
4. Click Test in Web Chat in the Bot management pane on the left.
5. To test connectivity to your bot, type some text into the web chat control and press Enter.

If an error is indicated in the chat window, use the error message to determine the cause of the error. Common issues include:

• The Messaging endpoint specified on the Settings page for your bot in the Bot Framework Portal is incorrect. Make sure you've included the proper path at the end of the URL, such as /api/messages.
• The Messaging endpoint specified on the Settings page for your bot in the Bot Framework Portal doesn't begin with https or isn't trusted by the Bot Framework. Your bot must have a valid, chain-trusted certificate.
• The bot is configured with missing or incorrect values for app ID or password. Verify that the bot configuration settings specify valid values for app ID and password.

If the bot responds appropriately to the input, you've verified that your bot is accessible and functional in the cloud with security enabled. At this point, your bot is ready to securely connect to a channel such as Direct Line, and others.

Additional resources

If you're still experiencing issues after completing the steps above, you can:

• Review how-to debug a bot and the other debugging articles in that section.
• Debug your bot in the cloud using the Bot Framework Emulator and [Dev Tunnels](https://aka.ms/devtunnels tunneling software.
• Use a proxying tool like Fiddler to inspect HTTPS traffic to and from your bot. Fiddler isn't a Microsoft product.
• Review the Bot Connector authentication guide to learn about the authentication technologies that the Bot Framework uses.
• Solicit help from others by using the Bot Framework support resources.