Testing authentication to your bot using the Bot Framework Emulator

In this blog post, we’ll show you how to test bot authentication capabilities from Azure Bot Service using the Bot Framework Emulator. You’ll learn what is required to set up in the Emulator to use OAuthCards as well as various options for interacting with OAuthCards.

When the bot sends an OAuthCard to the user, the user will have an opportunity to click on the sign-in button. OAuthCards handle sign-ins for remote services such as AAD, O365, or GitHub and as such, performing the sign in requires network connectivity. There are ways to fall back on an ‘offline mode’ for situations where the bot and Emulator do not have network availability.

The Basics

To use the Emulator with OAuthCards the following are prerequisites for the Bot:

  1. Register the bot within the Azure Portal and have a valid MicrosoftAppId and MicrosoftPassword available for your bot.
  2. Configure your bot to use the MicrosoftAppId and MicrosoftPassword (in the web.config for C#, or in the ChatConnector for JS/Node.

Note that while the bot does need to be registered, you can run the bot either locally or remotely with the Emulator.

The following prerequisites are needed within the Emulator:

  1. Install the emulator.
  2. Configure a connection to the bot using the MicrosoftAppId and MicrosoftPassword
  3. Configure tunneling software within the Emulator (such as ngrok). Instructions are here.

These settings are needed so that the Emulator can successfully access the bot’s registration and OAuth Connection Settings values. Tunnelling software (ngrok) is needed so the Azure Bot Service can return the token to the emulator when it becomes available.

Note that when using ngrok, it will ‘expire’ after about 8 hours so if you leave the Emulator open for too long OAuthCard signins will stop working until you restart the Emulator.

Emulating Sign-In Verification Codes

The Emulator uses the WebChat control to display the conversation with the bot. By default, WebChat is secured so that OAuthCard sign-in links do not result in a ‘verification code’ response. However, when using other channels such as Slack or Facebook, after the user clicks on the OAuthCard card, the user is presented with a 6-digit verification code that he or she must type into the chat window for the sign in to complete. To simulate this experience in the Emulator, you can go to the Settings page in the Emulator and turn it on:

When ‘Use a sign-in verification code for OAuthCards’ is checked, you will be sent a 6-digit verification code before OAuthCard sign-in is complete. When this setting is not enabled, you will get the default WebChat behavior which is a secure login link with no 6-digit code.

Running Offline

OAuthCards enable the bot to sign in users to remote identity providers and resources. If you’d prefer to debug your bot without doing an actual sign-in, you can turn on an offline mode for OAuthCards where the emulator will generate a random value and return this as the token.

To enable this, you can set a configuration parameter in your bot to notify the emulator. In C#, this is done by adding the following app setting into your web.config:


<add key=”EmulateOAuthCards” value=”true”/>

<add key=”MicrosoftAppId” value=”…” />

<add key=”MicrosoftAppPassword” value=”…” />



In node/JS, you can call this method to turn this mode on:

adapter.emulateOAuthCards(context, true);

This setting is part of the bot configuration because it also instructs the bot to ask for tokens from the emulator rather than the Azure Bot Service.

If you are using the Emulator with a bot that is not registered with Azure Bot Service, or you do not configure the bot and emulator to use the MicrosoftAppId and MicrosoftPassword, the bot will automatically use offline mode and you will get emulated tokens.

We hope this blog post helps you test bot authentication capabilities from Azure Bot Service using the Bot Framework Emulator.

Happy Making!

The Azure Bot Service Team