Build BOT working with Authentication (Microsoft Bot Framework)

Uncategorized

By Tsuyoshi Matsuzaki on 2016-09-06 • ( 8 Comments )

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.

In this post I will show you how to build and design this kind of authentication bot.

Important (Added on May 2018) : Now Azure Bot Service introduces new authentication provider feature (see here) and you can build same functionality with a few lines of code. (This feature is generally available on Sep 2018.)

Work with 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 Azure Bot Service (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 Azure Bot Service“.)
Let’s see the following example. This 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 https://contoso.com/login) is opened in the new window. Even if you’re using Skype for phone, the same experience happens.

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 design your Bot (Several Patterns)

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 store

The first approach uses some storage (database etc) to keep tracking state. You save and retrieve the state scoped by either the user or the conversation, and continuous steps will be done in different endpoints.

In this case, we assume that some OAuth flow is used as authentication.
First, your bot shows the sign-in button to navigate to sign-in url or your own web site. As part of the url, your bot should pass the bot information like user id, conversation id, service url, etc. (For example, like “https://contoso.com/login?userid=29%3a1iFtpwQb…” or “https://contoso.com/login?state=(encoded property bags)…“)

In the next step, your browser is redirected to the sign-in url. After the user logged-in (login succeeded), your application (endpoint) might get some authenticated security token (access token, etc) and save token in the storage. (After that, the user can close web browser.)
Of course, the user can retrieve only his own state from storage and the other user cannot retrieve this state. (The state is tagged with user id, conversation id, or both.)

Finally, when the user inputs some chat messages in bot channel, the bot (in server side) can retrieve the previous token (which is tagged by user) from the storage and call some APIs with this retrieved token.

The following illustrates this flow of authentication steps.

Bot Builder SDK is having this kind of framework called bot state store, and I created the super super simple example for your reference.
Please run and see the source code. (This sample uses the Bot Builder SDK for .NET.)

Try the sample (Skype bot)
https://join.skype.com/bot/ed6d70b2-ddc8-4962-aa70-553884677652
(You need your Office 365 account.)

Source code (Github)
https://github.com/tsmatz/bot-framework-with-auth-example2

Notice : The built-in state service (StateAPI) is deprecated (obsolete). Use custom bot state store with IoC container (autofac), as this GitHub example does.
Here we use In-Memory state store, but please use custom persistent state store (e.g, state store using Azure Table Storage, CosmosDB, etc) in production code.

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

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 https://microsoft.com/devicelogin. (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 https://login.microsoftonline.com/common/oauth2/token 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.

Thanks,

Categories: Uncategorized

Tagged as: Bot