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 information (like “token”) as the authenticated result. (If you’re using OAuth, your bot can call the api using OAuth token.)
For example, please run and see the “FreeBusy” or “AzureBot” in the Bot Directory. The “FreeBusy” bot launches the web browser 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 FreeBusy bot using chat.
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 launches the web browser (some specific url) by clicking this button.

When the logging-in experience, 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 (Rich text, Image, Card, etc)“.)
Let’s see the following example. 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 screenshot, the web browser (the url is “https://contoso.com/login”) is opened in the new window. Even if you’re using Skype for phone, the same experience.

POST https://skype.botframework.com/v3/conversations/29%3A1iFtpwQb.../activities
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "message","text": "","attachments": [
    {"contentType": "application/vnd.microsoft.card.signin","content": {"text": "Please login to Office 365","buttons": [
          {"type": "signin","title": "Authentication Required","value": "https://contoso.com/login"
          }
        ]
      }
    }
  ]
}

How to work with your Bot

The openUrl button or the signin button only launches the web browser with the specific url. You must design 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”. By using this infrastructure, you can save and retrieve the state, scoped by either the user or the conversation.
For instance, if your bot save some user bot state, only this user can retrieve this state information from your bot. (The other user cannot see this state info.)

Now let’s see the flow of the authentication with the bot state. (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). At this time, your bot passes the bot user id as part of the url (for example, like “https://contoso.com/login?userid=29%3a1iFtpwQb…“)

Your web application redirects to the login url.
After the user log in (login succeeded), your web application might get some authenticated security token. Then your web application stores the given token into the bot state with bot user id using Bot Framework api.
The user can close your web application (browser).

After that, when the user inputs some chat in your bot, your bot (in server side) can retrieve the previous token from bot state, and can call some api using this token.

The following illustrates this authentication flow.

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

Authentication Bot Sample (Skype)
https://join.skype.com/bot/ed6d70b2-ddc8-4962-aa70-553884677652
(You need your Office 365 account.)

Source code (Github)
https://github.com/tsmatsuz/AuthDemoBot

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

Pattern B. Match using some magic code in your bot

Instead of using the bot state, you can use your own keyword and match the logged-in info to the bot user.

For example, after logging-in, your web application stores some magic code (keyword, hint) and authenticated information in your own repository, and shows this magic code (keyword) to the user. (Please see the following example app. The “AzureBot” also displays this kind of unique code.)

The user copies this magic code and pastes into the bot. The bot can check if this magic code is valid, and can retrieve the authenticated information (token, etc) from the repository.

The following illustrates this authentication flow.

Pattern C. Providing some magic code in your bot

Vice versa, your bot can provide 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 also 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 application (bot) can retrieve the unique code (called “device code”) from Azure AD, and can provide this code to the bot user.
Next, the user goes to the https://aka.ms/devicelogin. (The user can also use the browser in their own handy device like the smart phone.)
As you can see in the following screenshot, the user can input their device code on this screen. If the code is valid, the user can login to the Azure AD.

Finally, after logging-in to Azure AD, your application (bot) can retrieve the authenticated token using OAuth (rest api on Azure AD) with the device code.

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 the English contents.)

Of course, there’re several other designs for authentication in your bot, but I showed some typical examples in this blog post for your reference.