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.
Note
To complete all steps in this guide, you'll need to download and use the Bot Framework Emulator and must have access to the bot's registration settings in the Azure portal.
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.
Note
To find your bot's AppID and AppPassword for an already deployed bot, see MicrosoftAppID and MicrosoftAppPassword.
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.
Warning
Disabling security for your bot may allow unknown attackers to impersonate users. Only implement the following procedure if you're operating in a protected debugging environment.
Disable security
To disable security for your bot, edit its configuration settings to remove the values for app ID and password.
If you're using the Bot Framework SDK for .NET, add or edit the settings in your appsettings.json file:
"MicrosoftAppId": "",
"MicrosoftAppPassword": ""
Test your bot on localhost
Next, test your bot on localhost by using the Bot Framework Emulator.
- Start your bot on localhost.
- Start the Bot Framework Emulator.
- 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.
- Type
- 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 withhttp
. - 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.)
Warning
The following instructions disable SSL verification for login.microsoftonline.com
. Only perform this procedure on a secure network and consider changing your application's password afterward.
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.
Tip
Your password may contain special characters that make the following call invalid. If so, try converting your password to URL encoding.
curl -k -X POST https://login.microsoftonline.com/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.com%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'
});
Note
To find your bot's AppID and AppPassword, see MicrosoftAppID and MicrosoftAppPassword.
Test your bot on localhost
Next, test your bot on localhost by using the Bot Framework Emulator.
- Start your bot on localhost.
- Start the Bot Framework Emulator.
- 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.
- Type
- 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 withhttp
. - 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.
Note
If you don't already have a cloud hosting provider, you can register for a free account.
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.
- Ensure that your bot has been successfully deployed and is running.
- Sign in to the Azure portal.
- Navigate to the Azure Bot resource for your bot within the portal.
- Click Test in Web Chat in the Bot management pane on the left.
- 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 Facebook Messenger, 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 ngrok tunneling software. ngrok isn't a Microsoft product.
- 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.