Up to this point, I’ve done a number of workshops with partners around the world on the Microsoft Bot Framework and time and again, it is the authentication that always, without exception, is the most time-consuming aspect of developing bots. I figured it warranted a blog post for clarification.
The bot is a user, not an API!
Much of the confusion around bot authentication, I believe, is due to the fact that the solution you as a developer are writing is NOT an API. The resulting bot service, that receives and handles calls by your users is NOT some random api that requires the user to sign in. Instead, the bot service can be seen as an automated user that is part of a conversation on the channel that you’re in:
image: Both the user and your chatbot service are signed in to the conversational channel
In the sample diagram above, both the user and the bot are connected to Skype and talking with eachother through that channel. The Bot Framework supports a variety of channels, and makes connecting your bot to those very easy.
Both users have their own set of credentials for connecting to that channel. User 1 is in no way authenticated with the bot, he is merely engaged in a conversation with the bot. Much of the confusion around authentication, I believe, comes from the local development process, where the developer connects directly to the bot’s API using the Bot Framework Emulator – it feels like an API, yet it isn’t!
Suppose that User1 wants our bot to reveal restricted information:
It is reasonable for the bot to require the user to prove his identity/kinship to the domain in which the bot operates.
How authentication is done
What happens is basically:
- The user agrees with the bot that it is time to authenticate towards AD
- The bot returns a special OAuth card, which, when activated, will open a sign-in browser window, and contains the appId created in AD for this purpose
- Login.microsoft.com will sign the user in, and verify that the AppId exists, and then return an authentication token to the bot
- The bot will now STORE this token in it’s configured storage, and use the granted access to access company resources.
In earlier versions of the Bot Framework, both the requestUrl as well as the replyUrl sent to login.microsoft.com had to come from a domain under the developers control. Later versions no longer require this, as the bot framework provides it’s own urls for this purpose.
I hope this brought you some clarity on how authentication with bots work. Let me know in the comments if it was useful for you.
Some useful links
- The Microsoft Bot Framework Developer portal
- Different authentication scenarios/options for bots
- What the heck is oAuth? (great post)
- Microsoft Teams Developer Platform
- Microsoft Teams App on DotNet Core Sample
Some images used in this blogpost were obtained by searching for images “Labeled for reuse”.