Microsoft 365 Community Microsoft Teams, 15 Nov 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Add Azure AD single sign-on to your Microsoft Teams bots using Teams Toolkit for Visual Studio Code

Description

In this 25-minute developer focused demo, Garry Trinder steps through using the Teams Toolkit to add SSO assets to your bot projects. You have a bot, now add single sign-on (SSO) to call APIs like Microsoft Graph. Setup auth flow, implement command, update configuration, and then see how a user is authenticated by the bot calling the Microsoft Graph API. TeamsFX simplifies working with authentication, and with SSO enabled commands. This PnP Community demo is taken from the weekly Microsoft 365 Platform Community call recorded on November 15, 2022.

Demo Presenter
• Garry Trinder (Microsoft) | @garrytrinder

Supporting materials
• Documentation - Teams Toolkit Overview | https://learn.microsoft.com/microsoftteams/platform/toolkit/teams-toolkit-fundamentals?pivots=visual-studio-code
• Documentation - Build command bot with JavaScript | https://learn.microsoft.com/microsoftteams/platform/sbs-gs-commandbot?tabs=vscode
• Demo - Build your first Command bot for Microsoft Teams with Teams Toolkit for Visual Studio Code | https://www.youtube.com/watch?v=3skgtkJ1McQ
• Documentation – TeamsFx SDK | https://learn.microsoft.com/microsoftteams/platform/toolkit/teamsfx-sdk
• Repo - Microsoft Teams Toolkit | https://github.com/OfficeDev/TeamsFx
• Documentation – Add single sign-on to Teams app | https://learn.microsoft.com/microsoftteams/platform/toolkit/add-single-sign-on?tabs=typescript%2F%3Ffrom%3Dteamstoolkit&pivots=visual-studio-code
• Documentation – Microsoft Graph SDK overview | https://learn.microsoft.com/graph/sdks/sdks-overview
• Repo - Microsoft Graph JavaScript Client Library | https://github.com/microsoftgraph/msgraph-sdk-javascript

Previously delivered demos from Garry
• Build your first Workflow bot for Microsoft Teams with Teams Toolkit for Visual Studio Code | https://youtu.be/S4M9IUj7mOo?t=2384
• Build your first Command bot for Microsoft Teams with Teams Toolkit for Visual Studio Code | https://youtu.be/3skgtkJ1McQ
• Build your first Notification bot for Microsoft Teams with Teams Toolkit for Visual Studio Code | https://youtu.be/bwyd46tVzQo

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - http://aka.ms/m365/community

A

B

On to your Microsoft teams, Bots using team's toolkit for visual studio code, if you've been following along over the last few weeks, you know that I've I've been uh kind of covering Bots the different types of bots and it's been very much kind of getting started, and so I wanted to kind of go to the next step of okay. Now you've got your Bot. How can you add a single sign-on to call apis like the the Microsoft graph?

B

So that's what I'm going to go through uh with you today um so a little bit about me. My name is Gary trinder I'm, A, Cloud, developer Advocate at Microsoft and I am on Twitter, if you're still on Twitter and get me at Gary, trinder or I'm on all different socials as well so check out my link tree and you'll be able to find me on whatever platform you're you're on um quick recap for today.

B

um So I'm gonna go through the steps of how you can add single sign on to a command bot project, so we're going to go through setting up that all flow, implementing uh the command, uh updating the configuration of your Bot and then and then show that actually running and show you what the the user flow is like for authenticating users in your Bot uh to then call the Microsoft graph API, like I mentioned.

B

If you've not been following along uh the first few weeks- and this is the first time you've heard of team to talk it and just a bit of a recap. So teams toolkit Visual Studio code is a visual studio code extension that you can install for Marketplace. This provides lots of functionality to create uh Microsoft teams apps and makes it easy to create debug and then publish those apps into your Microsoft, 365 tenant and then into Azure and then running in production.

B

So that's the slides done we're going to get into the code um I'm going to basically go through all the steps that um do you need to follow to to add SSO.

B

um Okay, so we're going to go into Visual, Studio, Visual, Studio code, and so just to kind of uh kind of set the scenes of of the basis of this demo I'm going to show a uh an app that I've already built a command bot um that I've already created um I've done this. By going through teams, talk, it create new teams, app and I've used the command, bot, template and I've used. Typescript I've basically generated it, which has ended up with a new project which is Base projects.

B

So it comes with um a bot that has a command called hello world and we have an Adaptive card which gets rendered when you send in hello world I'll just show you that I've already got this running. I've done the F5 and I'm just run hello. World and I should get a response of an Adaptive card, so that is running, but it's completely disconnected it's not using SSO.

B

So, uh let's uh go through the steps of. If you then wanted to create a command to uh to call Microsoft graph, for example, um so one of the features in teams talk it. If we open it up from the sidebar is we have ADD features and in here there's numerous features um that help you add resources to your project like Azure functions, SQL databases, uh one of the options is single sign-on.

B

We've also got API connections as well, which might cover another session, but today we're going to focus on single sign-on, so I'm just going to click that and we've got to read me in front of us with some instructions but you'll notice in the source control there's been some changes that have been made to our project. So, let's just see what's actually happened there, so we see lots of files that have been changed.

B

If I go into the explore review, it might be easier to see what has actually changed because see the yeah, the orange files. So we've had some configuration uh changed for our our project.

B

We've had some um if I go into that view, yeah we'll see it, and so we've had some information about client, IDs and secrets, tenants um and also Authority hosts that that we'll need for um authentication. It's been an update to projects just to say that yeah. This is now a SSO enabled uh bot uh our tool chain, I guess our F5 debugging process that's been slightly updated with it, with a new task for setting up SSO and we've got a few other files that have been added infras.

B

um So we've got readme, which is this file here, which contains all the instructions to follow to add in single sign on which I'm going to go through and and actually show you all of the steps um we've. If I go back to Explorer we've got a new folder called off in this folder. We have some assets, so we have a public folder which contains some HTML files, and so these are the HTML files that are getting invoked um when our bot uh is um where our bot command is invoked.

B

It's going to need to call out to uh to Azure ID to get a token, and these two files are going to help that um that flow, and so that we can request and then receive a a token back and we've also got an SSL SSO folder, which I have a couple of examples as well. So there's an example for a command Handler for a bot.

B

There's also no example for a messenger extension as well I'm not going to cover the message extension today, but we're going to cover the the command Handler and, if I, just open this you'll see that there's an example already pre-given, and but what I wanted to do is just explain all of the the elements of this file and all the kind of the moving Pieces by actually implementing a a command from scratch that uses SSO.

B

um We've also got a new template file in here as well. So we've got Azure ad because our bot now um needs to have uh identity, authentication uh properties added into Azure ad. We can see that um there's a a template provided where we can add in what Scopes we we actually want to provision um as well. So we've just got user readers as an example. But actually you know you wanted to add more Scopes in there. You can come into here and you can.

B

You can add them for your for your provisioning, Okay, so I'm just gonna stop the uh the bot that I had running and let's go through the steps to uh to actually set up uh our authentication uh flow. So first step is: we have this public file? uh Sorry folder. We need to move this into our source directory, so super simple, just drag it in and move it. That's that's that first step done really quick and and easy.

B

um What we also need to do is we need to update our our bot. um So if we go to the index file, so in here our bot is using a restify server in its implementation. Currently it doesn't know how to serve these HTML files when they're actually requested. So we have to add in a server get method.

B

So we're going to add that in there and we're going to import the.

B

Import path and we can save that file, so essentially, this is just saying that if there is a correct request for a HTML file with the auth dash and the wildcard um there for the the start, it's going to serve serve that up from from this. uh This server next step is: we need to make an update to our package.json file and we need to update the build step.

B

So in this build step, what this is doing is just making sure that we're, including our HTML files, that we've got in the uh in the the public folder into our build and then the final step is. We need to make sure that we handle any errors. So in here we have our.

B

um We have our post uh Handler for the API messages um endpoint. So this is where all the communication between our uh bot and the bot framework is taking place. We just simply need to add a a catch to the end of this just to trap any user authentication errors so that we can handle them a little bit more gracefully I needed to replace all that.

B

And that is it, so our bot now actually has been set up uh for uh SSO.

B

What our next step is is we can now just go and create a command in our bot to uh to to leverage uh this uh this new functionality. So let's go and do that now. So in this example, what we're just going to do is create a a new command called profile. It's going to go off to the graph API, it's going to pull back my profile information and it's just going to get rendered in an Adaptive card to display that back to the the user.

B

So, first of all, let's create a new adaptive card, so profile command and super simple I'm, just gonna paste in this card, so I just show the uh the display name of the user and then a fact set um of some some individual properties.

B

So let's save that, okay, so we're going to create a new command now I'm, actually going to create a new folder. Oh called commands I'm going to move my Hello World command. Handler enter there, so just tied it up and create a new command which is going to be profile command. Handle it okay. So if you followed um in previous weeks, uh you know for a command Handler and we would Implement from a uh an interface which was teams FX, bot command, Handler. Well, there's a new one which is bot SSO command Handler.

B

So we're going to implement from from this I'm going to pull that in from the teams. Fx Library looks very very similar to our standard command. We've got our trigger patterns at the top, and our handle command received has an extra property which provides a token response, and it's inside here that we actually get our our token to use I'm just going to make this async and I'm going to update our trigger pattern, so so that when it sees the word profile, it knows to actually trigger this. This code.

B

Okay, so now we have our Command when it runs. What we need to do is we need to set up our identity and there's a in teamsfx library. So this is going to handle a lot of the complexities for um for our Authentication, get our SS SSO token, and we create a new instance of teams, FX just going to import that Library, and then we can use the create Microsoft graph client. So you can pass in our teams FX instance and the Scopes that we want to use for this request, which would be user.read.

B

Sorry for our client import that so now we have a client which is using the Microsoft graph, JavaScript SDK.

B

We can then make a request to the graph and that's all set up ready so that when we make that request, our token is going to be sent to Microsoft graph from our bot and and all that authentication is going to be handled now before I do that there is one thing that you'll need to do, and so the Microsoft graph um JavaScript SDK client actually needs um a package to be installed, which is the isomorphic fetch package.

B

So change into your Bot Source directory and run this command to just install the package.

B

And once that has finished, we can just import that into the command Handler to make sure that the SDK has everything it. It needs Okay. So we've set up our teams- FF FX instance, with our SSO token, uh that we've got back from uh from from the bot framework and we've set up a client and then we're making a request. So with that data that we return, we uh want to render that data in our adaptive card.

B

So let's just bring in the import for our adaptive cards and we'll bring in our profile card as well. So the Adaptive card we created in here.

B

So we're going to render the card next passing in the data that we've retrieved from the graph and then we're going to return that card back to the um to our bot I'm just going to import these.

B

From bot Builder and save that, okay, so so far, we've set up the off flow. We have created a command and an Adaptive card and implemented the logic to call the graph and um and return that data in an Adaptive card. The next step is, we need to tell our bot that actually it's now SSO enabled we have a an SSL command that we that we want to to use with it.

B

So if we come to the initialize file, so in here this is where our bot configuration is, we can add in a new property called SSO config in here.

B

So we can pass in the actual Scopes that we want to use with with this as well. So this will be the when there is the prompt for authentication. This is the uh the scope that that will need to be uh approved and then in the command um property. We have a new array property that we can add in our new SSO commands, which is the profile command Handler and bring that into there, so that set everything up on the bot side.

B

The final step is now to update our manifest and actually yeah provide some uh like a tool tip to the the user when they uh they're in the attack the compose message box. So in here, if we go to our template and we go to our manifest.

B

So in here we can add our new command, which is going to be profile and that's just going to return the user profile. Okay, so that is now ready. So, let's run our our Bots, all right use the run and debug so hit F5 if you'd like to- and this is just going to set everything up- it's going to run the the services. It's going to make sure that everything there is ready.

B

So I'll just take a few moments, whilst, uh whilst this happens.

B

So just wait for the uh the bot to start up there. We are the debug is attached, and then we have a new window.

B

We can side load our app.

B

The same app that we had before and now we have our profile option there. So, when I submit this, what will happen is we'll get a prompt there we go. So this is the the consent dialog. If I click continue, we get the window, we can see what permissions are being requested. So I can accept this.

B

Wait for a second, the code has actually been returned. There.

B

Demo Gods this week are not proving kindly. Let me just refresh this: let's try this again.

B

A lot of time for everything to go, slow, It's, Quickly, just jump back to the code. It's not going to hit break points running.

B

Live demos still got a couple of minutes left, so I should have time just to redo. This I think.

B

To close this down and let's rerun that.

A

B

So there we go, it's actually worked, I'm, not sure what happened there with uh with my browser, but the consent actually uh went through so now we can actually see that it's gone to the graph API. It's pulled back my details and it's actually rendered that uh into uh into the card. So you noticed as well. I didn't have to log in either so it it just knew that I'd already consented and got a token.

B

It was able to do that nice and silently in the background, and so that's a nice feature of using uh this approach. um If I go back to the the code.

B

So, in terms of other commands that you might have and select the hello world uh command Handler, so this default one. It uses the teamsfx bot command, Handler interface.

B

If you want to then just simply add in a call to this update the um the the Handler to the the SSO Handler and then you'll be able to get back the token response and then use uh use that token response in in your logic, uh call call the graph and and upgrade those um those commands that you might have already created um and with that I'm going to go back to the slides.

B

um So from what we've just been through today. So teams talk. It makes it easier to add those as so assets to your Bot projects, just use the add features and select the the single sign-on option. So it gives you um the uh the HTML files and the guidance as well so there's the readme.

B

Then the steps to to actually follow uh to to add that SSO to your Bot or to actually a message extension as well, uh if you're, if you're, if you're, looking to to build a message, extension and just in general, that teamsfx there's really simplifying working with uh authentication and actually you know making it really easy to get access to that token and then make make those graph calls as well, once your bot's been set up uh for SSO.

B

It's very easy, then, to just create more commands um and make use of uh of that flow, really easy by just using the teams, FX instance, um and being able to generate clients from from that teams. Fx Library.

B

So, uh where to go next, there's tons of uh resources, I'll put some links in the chat as well.

B

um You know if you've not built any Bots using a team's toolkit, definitely uh check out the videos that we've done in the previous weeks um in in this call as well, so create notification, Bots at command, Bots and most recently, workflow Bots um as well, and there's also guidance in the docs about you know: adding single sign-on to your team's apps, whether that is a bot, whether that's a tab as well. um All the areas are covered and with that back to you, facer.

A

Gary before you stop sharing just the one question, there's a great question from Andy all end: users would need to do the consent one by one or is there an option to do this as an admin consenting just good question? Actually.

B

That is a great question. I believe there is an option in the teams: admin Center to enable that um off the top of my head. uh I believe that there is I can check and I can get back to you on that one. But that is a great question. Yep.

A

That is a good question to make make the installations as seamless as possible, but.