Build BOT with Authentication (Microsoft Bot Framework)

In the case that your bot needs to communicate with some 3rd party api (for ex, Facebook api, Office 365 api, twitter api, and Google api etc), your bot must show the login UI for the user and get some security information (like “token”) as the authenticated result. (If you’re using OAuth, your bot can call the api using OAuth token.)
Please run and see the “FreeBusy” or “AzureBot” in the Bot Directory. The “FreeBusy” bot launches the web browser for authentication and you can login Office 365 or other calendar app. After logged-in, you can view or create the appointment in your calendar from the chat in FreeBusy bot.
The “AzureBot” interacts with Microsoft Azure using Azure ARM rest api. This also launches the web browser for logging-in to Azure.

Today, I will show you how to build and design this kind of authentication bot.

SignIn Exprience in Bot

It’s very easy to show the Login UI from your bot. As I mentioned in my previous post “Rich messages with Microsoft Bot Framework (Rich text, Image, Card, etc)“, you can show the openUrl button (the button which type is “openUrl”) and this button launches the web browser (some specific url).

You can also use the signin card and signin button in the Bot Framework. (For the usage of the “card” and “button” in bot Framework, see the previous post “Rich messages with Microsoft Bot Framework“.)
Let’s see the following example. The following rest shows the following UI in chat app. This sample shows how to use the signin card and the signin button, and how it’s displayed in the Skype.
When the user clicks the “connect” button in the following UI, the web browser (the url is “”) is opened in the new window. Even if you’re using Skype for phone, the same experience happens.

Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

  "type": "message",
  "text": "",
  "attachments": [
      "contentType": "application/",
      "content": {
        "text": "Please login to Office 365",
        "buttons": [
            "type": "signin",
            "title": "Authentication Required",
            "value": ""

How to work with your Bot

The openUrl button or the signin button only launches the web browser with the specific url, and this doesn’t do anything more. You must design and implement how to interact with your bot after logging-in.

There’re several patterns for designing, and I will show you some examples for your hint.

Pattern A. Using bot state

As I described in my previous post “BUILD BOT with Microsoft Bot Framework Rest Api“, the Microsoft Bot Framework is having the built-in state infrastructure called “bot state service”. By using the bot state service, you can save and retrieve the state, scoped by either the user or the conversation.
For instance, if your bot save the user bot state in the bot state service, only this user can retrieve this state from your bot. (The other user cannot retrieve this state.)

Now let’s see the detailed steps of authentication with the bot state service. (In this case, we assume that the OAuth flow is used as authentication.)

First, your bot shows the button to launch your web application (web site). As part of the url, your bot should pass the bot user id (for example, like “…“).

Next, when your web application (web site) is opened in the browser, the page is redirected to the login url.
After the user log-in (login succeeded), your web application might get some authenticated security token. Using Bot Framework api, your web application stores the given token as user state into the bot state service. (At this time, the user id is used for identifier.)
The user can close your web application (web browser).

Finally, when the user inputs some chat in your bot, your bot (in server side) can retrieve the previous token from the bot state service. (From now, this bot can call some api using this retrieved token.)

The following illustrates this authentication steps.

I created the super super simple example accomplishing this flow. Please run, and see the source code for your reference. (This sample uses the Bot Builder SDK for .NET.)

Try the sample bot ! (Skype)
(You need your Office 365 account.)

Source code (Github)

Notice : This sample is implementing the minimal code for accomplishing these steps, and I’m not implementing the additional code for scaling or security. (Do not copy and use this sample code in your production.)

Notice : The default state service is only having the basic functionalities and allows limited access to the state information. For the needs of the real production (storage management, scalability, etc), please implement your own custom state client or use Bot Builder SDK Azure Extensions. (When using Node.js, see here for the additional module.)

Pattern B. Match using some magic code in your bot

Instead of using the bot state, you can use your own keyword (unique code) and match the logged-in info (authenticated token, etc) to the bot user.

In this scenario, after the login succeeds, your web application issues the unique code (magic code), and stores both this code and the authenticated information (token, etc) in your own repository.

Your web application shows this magic code to the user (see the following screenshot), and the user copies this code and pastes into the bot chat.

As a result, the bot (server side) can check if this code is valid, and can retrieve the related information (token, etc) from the repository.

The following illustrates these steps.

For example, the “AzureBot” displays this kind of magic code.

Pattern C. Providing some magic code in your bot

Vice versa, your bot can provide (issue) some magic code in your chat, and your web application can verify this code and save the authenticated information. (In the previous pattern, the web application provided the magic code. In this case, the bot provides the magic code first.)

Especially, if you’re using the Azure Active Directory (Azure AD, i.e, Office 365, Dynamics CRM Online, etc), you can use the device login (OAuth device profile flow) with this integration pattern. The device login is often used when you’re on the environment without the graphical interface (like console app, printer, robot, etc). For example, the Azure CLI (command line interface) is also using this flow.

First, your bot can retrieve the 2 types of magic code called “user code” and “device code” from Azure AD, and provide the user code to the bot user.
Next, the user goes to the (The user can also use the browser in their own handy device like the smart phone.) This url shows the following screen, and the user input the user code on this screen. If this code is valid, the user can login (using id and password) to the Azure AD.

Finally, after logging-in to Azure AD, your bot can retrieve the Azure AD token from using device code. (Azure AD matches the client using this code, and passes the authenticated result.)

Notice : This retrieval expires in 15 minutes (900 seconds).

For details about this flow in Azure AD, please see my previous post in “Azure AD : OAuth flow when you cannot show the login UI“. (I’m sorry this post was written in Japanese, then please search for some English contents.)


Of course, so much other scenarios (patterns) exist for authentication, but I’ve just shown some typical examples in this post for your reference.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s