As GPT and other large language models revolutionize the way we communicate and how we can build custom solutions for companies, the demand for intuitive frontends to deliver these AI capabilities to end-users has never been higher. If you’re wondering whether there’s a seamless way to integrate a bot into Microsoft Teams, you’re in luck! In this blog, I’ll guide you through the process of developing and deploying your own custom bot tailored for Microsoft Teams and the bot framework from Microsoft.
My Experience in the Bot Jungle
Navigating the world of Microsoft Teams bot development can feel like traversing a dense jungle filled with outdated projects, non-functioning examples, and incorrect instructions. After facing numerous hurdles in building my first bot, I realized the need for a clear and straightforward guide. That’s why I’ve crafted this blog—to simplify your journey into bot development and help you avoid the pitfalls I encountered.
How does it work?
To set up a Teams bot you basically need 3 components. One is, for sure, the client component, like the Teams app on your device or in the browser. The other one is the bot service which has to be deployed in Azure (How to do this will be shown below) and the third one is your bot endpoint, which can be an App Service or a container deployed, e.g., to AKS (Azure Kubernetes Service).
This is the technical setup for the infrastructure and the needed services, but we want to build an SSO (Single Sign-On) application. Let’s now also have a look at how the authentication setup works. Here, it is important that it is transparent for the user. This means we want to avoid additional prompts.
The first step is the user logs in to their MS Teams client and authenticates
App registration
The first thing we need is an Entra ID App Registration. I want to show you how you can create a single tenant app, but the same steps also apply to a multi-tenant app. To create this, navigate to Entra ID App Registration Blade and click “New Registration” in the top-left corner.
In the creation dialog enter a name and select single tenant app. After this, set the redirect URI to “https://token.botframework.com/.auth/web/redirect” and click “Register”.
The app registration is now created. Next, we have to configure it. But before that, copy the Application/Client ID and the Tenant ID and note them down.
The second thing we need is the app secret. You can find it in the certificates & secrets section. Click here on “New Client Secret” and note it down as well. This is needed for the further steps.
After this, navigate to “Expose an API” in the left menu. Set your Application ID URL. To do this enter api://botid-{ID_OF_THE_BOT}. The Bot ID is the id which is already in the field.
Next click “Add a scope“. Enter access_as_user as the Scope name and set ‘Who can consent?ʼ to ‘Admins and usersʼ and enter a display name and description. Ensure that State is set to Enabled.
Add the following IDs as authorized clients for your application.
Minimum:
- 1fec8e78-bce4-4aaf-ab1b-5451cc387264 – Teams mobile/desktop application)
- 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 – Teams web application)
Next, navigate to “API permissions” on the left-hand side. Add any user delegated permissions that your app will need plus the openid and profile permission. Most apps need the User.Read permission to get, e.g., the user ID or the email.
Navigate to “Authenticationˮ and make sure Access tokens and ID tokens boxes are checked as shown in the screenshot below.
Azure Bot creation
As mentioned above we also need a bot resource. To create this, open the Azure Portal and type in the search Azure Bot. Select this and click on create.
For the configuration select ‘Single Tenant’ (Optionally you can also select Multi Tenant). Check “Use existing app registration” and type in the client id and secret noted down above. Click on Review + create on the Azure bot.
It is important that you fill out the messaging endpoint in the configuration section. The URL for this is the public FQDN/IP of your bot service or ngrok server plus /api/messages. But we will come back later to how you get this FQDN.
Next, we have to activate the Teams channel. Navigate to Channels on the left side, select MS Teams in this menu, and accept the TOU to enable this feature.
Once this is done, we must also set the SSO setting. You can do this in the configuration plane. Select here Add Oauth Connection Setting. Fill out these options with the previously noted information. It is important to note the name you set for the OAuth connection; we need this later.
If you have a multi-tenant app set “common” as Tenant ID and for single tenant app your Tenant ID noted before. For the scope set all the scopes you set in the app registration in our example it is “openid profile User.Read”. Once this is done, click “Save” and the configuration is done for now.
How to run the bot locally?
First, you have to clone this repository https://github.com/JayRHa/TeamsSSOBot.
Next, we want to run the bot locally with the help of ngrok to have a good development flow for testing the changes. The first thing you have to do is fill in the noted information (appid, secret, tenantId, connectionNam and the Apptype) in the .env file.
To make your local code reachable on the internet, we have to launch the ngrok server. This is one way, but there are also other solutions like dev tunnel to allocate a URL to a port on localhost to have a tunnel to your local machine. To run the ngrok server, you first have to install it and create an account to get an API key. Once this is done you can run it with ngrok http 3978. When the server runs, it shows you a screen with the allocated URL. This URL you can add to the messaging endpoint configuration in the bot service.
The only thing we have to do now is run the server code with `npm i && npm start`.
How to add the APP to teams?
This is the easiest part in the whole journey. The only thing you have to do is navigate to the appManifest folder and open the manifest.json. Here you can replace the APPID and the BotID with the noted values.
You can use the icons which are already in the folder or replace them with custom ones. The same applies to the links and descriptions in the manifest.json.
Once you are done, you have to create a zip file from both icons and the manifest (not from the folder). After that, open your Teams client, click on Apps, then Manage your apps, and click on Upload App.
How to make changes on the Bot?
As you may know, I mostly develop in PowerShell or Python. The bot framework SDK supports 4 languages, namely Python, .Net, JS and TS. The first try I did was with Python, but I couldn’t get this working. After some research, I figured out that there is a bug in this framework which makes it not possible to have a functional SSO bot in Python (this could be fixed by the time you read this blog). This was the reason I decided to switch to JS. JS is not my biggest strength, but I had developed some projects in it in the past.
But let’s jump into this topic. Before I show you how to make changes to the bot code, I will first explain you what the current code does and how it works.
The main file is the Index.js, which runs the bot and the (message/api).
This script has dependencies on the dialogBot.js and the teamsBot.js in the bot folder. These are both files where the triggers for onMemberApp and onMessages are located. These are the triggers which react when you add the bot and when you send a message to the bot.
In addition, we also want to get an SSO token claimed for the Graph scope to also get additional information from the user. This can be found in the dialog folder in the mainDialog.js file. This dialog gathers your SSO token and saves it in the userTokenMap to use it in one of the trigger actions.
If you want to react to messages or add buttons, you can do it in the dialogBot.js.