Microsoft 365 Community Microsoft Teams App Camp, 2 Mar 2023

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Microsoft Teams App Camp - Start with Azure Active Directory - Lab A01

Description

This module introduces you to how to register an app in Azure Active directory

📖 Full lab can be found here https://microsoft.github.io/app-camp/aad/A01-begin-app/

This video is part of a series in a playlist about Building apps for Microsoft Teams: https://www.youtube.com/watch?v=hFwLfG95rVU&list=PLR9nK3mnD-OW5yCjKO0K8b-Xi4Ci1iBlU

➡️ Next video on this series - https://www.youtube.com/watch?v=khpjsWwmB5U&list=PLR9nK3mnD-OW5yCjKO0K8b-Xi4Ci1iBlU&index=7
⬅️ Previous video on this series - https://www.youtube.com/watch?v=CrvX_UZ38eA&list=PLR9nK3mnD-OW5yCjKO0K8b-Xi4Ci1iBlU&index=5&t=158s

#Microsoft365 #AzureAD #MicrosoftTeams

In this lab you will learn to:
• How to run a web application using NodeJS
• How to expose a local web application using ngrok
• How to register an application with the Microsoft identity platform (https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app?WT.mc_id=m365-58890-cxa)
• How to use the Microsoft Authentication Library (MSAL)(https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-overview?WT.mc_id=m365-58890-cxa)
• How to validate an Azure AD access token in a NodeJS application (https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens?WT.mc_id=m365-58890-cxa)

👩🏾‍💻 Completed lab source code is here https://github.com/microsoft/app-camp/tree/main/src/create-core-app/aad/A01-begin-app
📽️ Watch this video to learn about ngrok https://youtu.be/A5U-3o-mHD0
📽️ Watch this video to set up your free developer tenant https://youtu.be/DhhpJ1UjbJ0
📽️ Watch this video to learn about multitenant apps https://youtu.be/RjGVOFm39j0
📽️ Watch this video to learn more about SSO in Microsoft teams apps
🛠️ Lab prerequisites https://github.com/microsoft/app-camp/wiki/Prerequisites

✨ Demo Presenter
• Bob German (Microsoft) | @Bob1German

📝 Learn more
• YouTube playlist for this video series - https://www.youtube.com/watch?v=hFwLfG95rVU&list=PLR9nK3mnD-OW5yCjKO0K8b-Xi4Ci1iBlU
• Overview on Microsoft Teams extensibility - https://learn.microsoft.com/en-us/microsoftteams/platform/overview
• Design guidance for Microsoft Teams apps - https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/design/design-teams-app-overview
• Sample Microsoft Teams apps with code - https://adoption.microsoft.com/en-us/sample-solution-gallery/?product=Teams&sortby=creationDateTime-true&page=1

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

Sharing is caring! You are awesome! 🧡

A

Hi and welcome to teams app camp I'm, Bob German and in this video I'll walk you through zero one. The very first of the things want to follow along navigate to AKA dot, Ms, slash, app dash camp and scroll down to the link to lab a01 start with Azure active directory in teams app Camp, you'll port, a simple software as a service application, called the Northwind orders app to become a Microsoft teams application.

A

This is the first lab in the a path in which you'll set up the north wind orders, application using Azure active directory for authentication and authorization. If you'd like to start with a SAS application that doesn't use Azure ad, then you'll want to switch to the B path.

A

You can complete these Labs on a PC, Mac or Linux any computer. That runs the prerequisites it's based on node.js, which is an open source, JavaScript interpreter and express which is a web server that runs on node.js, we'll start by installing the prerequisite software, which is node.js itself. A text editor and a tunneling program called ngrok, which will allow us to more easily access the locally running application over https.

A

Then we'll go on to register the application with Azure ad and get it running in web browser.

A

So the first prerequisite is node.js, so there's a link right in the lab instructions. You can go and select your operating system and download that I'm on windows, so I'll just grab the windows MSI and install that on my local computer. If you are using different versions of node for different projects, you might want to install something called NVM.

A

The node version manager before you do this, but in this case I'm just I'm just going to use this one version, which is the latest version of node, and so the installer will run, and it's really no big deal now at the end. I'll just bring up a command window and make sure that it worked so I should be able to say node, minus V and get back. The version number next thing. I need is a code editor I'm, partial to visual studio code, very popular these days, like the rest of everything.

A

Here it runs on PC, Mac and Linux, and so I'll go ahead and download the version for my machine and install that and uh just take the defaults very simple and I do like. Actually, when you can open files with code, so I'll go ahead and and select that and there we go and now it will come up and run and I'm just going to go ahead and select the light theme for this machine.

A

And now the last step is to install ngrok there's a URL in the instructions. You just have to come here and sign up I'm not going to demo the sign up instructions but you're going to get a command couple of commands back that you would run to set up ngrok, so I want to explain what ngrok is and how it works, and to do that, let's take a step back and look at your developer setup. So here's a setup that would be typical of any web developer. You've got your client program in this case.

A

Maybe the teams, client or browser you've got your web server hosted locally using node.js in the case of app Camp labs and then you're calling apis out on the internet and since they're outgoing calls, your firewall lets them pass through and everything works okay.

A

Now, if you want to do this, you're going to have to set up your local web server with https termination and a valid hostname could be in your local hosts file, but it has to look like a valid host name. Otherwise, teams will not allow you to use it in your application. So you actually would have to set these up locally.

A

If you wanted to run all local, and also mobile testing would be another exercise in setting up DNS inside of your local network, so that all works pretty well as long as we're making outgoing calls to the apis. But what happens when teams needs to call into our application?

A

This is done using the Azure bot framework and it's not only used for conversational Bots, but it's also used for other features such as teams, messaging extensions or even sending proactive messages have to be done using the bot framework, and what happens is that you get your message from the bot framework saying somebody clicked a menu, for instance, and and once your messaging extension to run and that's going to hit that incoming message is going to hit your firewall and your local web server is not going to be able to get to it, and so that's why we're using ngrok in app camp is so that those incoming messages can get to your local web server.

A

What ngrok does is it exposes a URL with the HTTP termination and host naming already taken care of that is a public live URL on the internet and anything that comes in that URL is going to get directed to your local web server, using just regular HTTP over whatever Port you want. So it neatly solves this problem.

A

It also redu removes the need for you to set up local https termination and host naming, and it makes mobile testing or testing from any number of clients easy, because that your entire application can share that public URL, that's provided by ngrok.

A

You may find that some corporate networks or networks with perimeter-based Security will block ngrok, in which case you may have to find a public internet location in order to run it.

A

So in this exercise, you're going to set up your Microsoft 365 subscription. Now maybe you already have one and if you have a developer tenant, then good for you. You can use that. Of course, if you use Microsoft 365 for day-to-day work in your company, you probably don't want to use that production subscription. You likely not going to have enough permission to do what you need to do and you might break something right so much better to do your experimentation in a separate subscription and they are free and you'll, be a full admin.

A

So here's the place to sign up and I'm, not gonna I'm, not gonna, demo signing up. It's really straightforward, um but I will point out this tip here. Navigating many tenants, it's really a Time Saver to come up here in your browser. This is Edge, but it works also on Chrome, Firefox and I think most of the major browsers you can either go into privacy mode, but it's easier if you actually add a profile and then you can switch it'll store.

A

All your logins and everything separate in the two profiles so you're not having to constantly log in and out as you're, switching between regular work and this development work so anyway. The next step is to enable teams, application, uploads and so I'm going to show you where that is right.

A

Now, um let me just come in and I'll start at the beginning: I'll go to office.com and from here there is admin right because I'm, an office admin and I'm using one of the CDX transform tenants by the way, this is available to our partners to be able to create a demo tenant. That's fine too. It's a nice, isolated environment and then I'm going to go into teams. You might have to click, show all in order to see teams on this list and I. Have it pinned? That's why it shows up.

A

So let me go in here and I'll show you this setting now this is going to make it so that users can just upload or you as a as a as a developer user, can just upload your team's apps directly from teams without having to go in and out of admin all the time.

A

So it's a Time Saver, so you go into teams, apps, setup policies and then pick the global policy or if you have fancy policies set up, you go into the one that you're in- and this is the check box right here- that you want. Is this upload custom? Apps? That's! What's going to allow you to do this uploading and then the key is that there's a save button down at the bottom of this page? And so, if you make the change and you don't click, save you don't get the change.

A

Another thing is that this can take several hours to take effect. So it's a good thing to kind of. Do it right away and get that done.

A

So in this exercise, we're going to set up our test users- and the main thing we need to do is add a Northwind employee ID to each user, so that we know which orders are associated with that user right. So to do this, I'm just going to skip past these instructions, you can follow them, but just show you this little table which has the nine employees that are in the Northwind database.

A

Now the the names aren't going to match up, but but that's okay and the app is going to use these to determine what data to show the users inside of the Northwind database. So to do this I'm going to go into Microsoft, 365 admin and you'll see here that there's an active users link right here, and this is not it because you can't change the employee ID from this screen. So you know it's useful for other things, but for this we got to skip down.

A

We got to go to the Azure admin Center, which is a special part of the Azure portal that you don't even need in Azure subscription to use, and it just lets. You manage different aspects of azure ID, so I'm just going to go into there, and inside of here is users, and now this is going to work for me, so I'm logged in as Megan Bowen.

A

So let me go into Megan and I'm going to first of all check and make sure she has licenses. So that's also in the instructions.

A

um I think I might be doing a slightly different way here, but you can see she has an Office 365 license.

A

That's going to allow her to run teams, so if she doesn't have that she won't be able to run teams when we get to our teams app and then I'm going to go into the properties and I'm I'm going to set the employee ID in here right, very simple: I'll set it to one and notice that she has a manager, because this test date is already set up, we're not actually using the manager field anymore, but we're probably going to use it in the future.

A

So if you're here and you got a sec, go ahead and give your employee a manager, if they don't already have one it's interesting, Microsoft 365 will actually construct the complete org chart from just the manager field in each in each of the user accounts. So let me just do this one more time, because I really would like to have another test user to work with and I think I'll pick Lee for that other user. So just come in here to Lee and again edit the properties and come down here to the employee.

A

Id and Lee can be employee, ID number two, all right and that's it, and now the exercise is done.

A

So in this exercise we'll start with a command line and we're going to go ahead and run ngrok and to make a tunnel to http Port 3978, you type ngrok HTTP 3978, and what you'll notice is that there's a forwarding URL, um which I'm copying right now to my clipboard.

A

That is a public internet facing URL that will forward through the tunnel to that localhost port. So I'll save that in a in a just a little file on the side and now let's go ahead and register our application. So we needed that ngrok URL to register the app because the app URL is part of the registration, so I'm just going to go into Azure active directory and go to app registrations and click, the plus to add a new app registration.

A

And, let's just call it Northwind orders to keep it simple, and this will run the app can run in any organizational directory. That is any Office 365 tenant anywhere. So we're making this public. Even though we're going to be testing in the same location and there we had to put the ngrok URL in there so that the login will work.

A

So now you can see, we've got some numbers here, I'm going to grab the app ID, which is also called the client ID and save that away in my little note file and then also I'm going to grab the tenant ID, which is also the directory ID and put that inside of there as well, so we'll be using those later on now, let's just go into certificates and secrets and make a new app secret. You can set this to last for up to 24 months in production.

A

You'll want to rotate these much as you would rotate a digital certificate, and now this is the only time I can get to that secret. So I'll copy it to my clipboard and paste it here and yeah I. Don't need to hide it from you on the video, because I've already changed it long before I publish the video now under API permissions notice that we have permission to call the Microsoft graph and so I'll go ahead and Grant that permission so that users in this tenant won't be challenged again and now.

A

What I need to do is add a scope. This allows my client side of my app to call the server side and then the server side to validate those incoming requests so to make it work with teams in the next Lab.

A

After this, we need to change the scope and, instead of just taking the default, we're going to put the ngrok hostname or the wherever it's hosted, hostname into the app ID URI and now um I'm, just going to give it a scope, name called access as user and type the message that admins will see when they have to consent to this permission and I'll go ahead and add that and that's it for the app registration.

A

All right, so, let's go ahead and get the code and put that into place. So there's a link in the instructions to the GitHub, repo and I'll just copy the URL. You could download the repo as a zip but I prefer to use GitHub. So I'll go to my git CLI and uh my git shell and clone that repository so I have the whole thing locally. Now, I don't need to actually modify inside of there unless you want to make a contribution to the repo.

A

But what I'll do is I'll just go ahead and open up a file explorer and I want to go to the folder called Source, create core app aad a01 begin app.

A

This folder has the starting solution, so I'll copy that and go back to my source location and paste it in and then what I want to do is rename it to just something like working, because this is where I'm going to keep doing the lab work and applying one lab after another is in this working folder right here and you can see the files in there.

A

So let me I'm just going to go in and go into that folder and I'm going to do an npm install. So that's going to install all the dependent packages using the node package manager and then the other thing I need to do is download the Northwind database. So I've provided a script for that. You just do npm, run DB download and it will actually go out to the Northwind database at the odata sample service and download the whole thing into local Json files.

A

If you haven't heard of the Northwind database, it's just a sample database that is was originally distributed, I think with Microsoft Access. So it's really been around for a long time and our friends at the odata organization, so odata is a standard for sending structured data over rest calls. So they've provided the Northwind data sample here on their site and all the orders and things that you see inside of the app Camp sample are going to come from this data.

A

The script will download the data so that you can update it locally in some Json files and that's just there to provide kind of a business context for the sample app as you go through app camp.

A

So let's just bring this up in Visual Studio code and you'll be able to see the project and the project structure right here. So yes, we trust it and I'll maximize this. So the next thing I need to do is set up my environment file. So there's a sample here, but I want my own, so I'm going to copy this and rename it to just simply.env.

A

This is a common thing for node.js development and now I have a local copy that won't get checked into Source control because I'm going to put all my data in there. So, let's start off by grabbing this ngrok hostname out of my notes that I started earlier, and now we just paste that right in where it says hostname and then the next thing would be the app ID or the actually, let's get the tenant ID.

A

Next, that's the next thing on the list so copy that and put that into the EnV file, and now the validation code can in the server can use that as well as in the client, we can use the app ID to tell the Microsoft authentication library on the client what app we're logging into the same EnV file serves for both the client and the server.

A

So if you're curious about that, there's the answers in the server.js file, and so there we have all this information that we would need on both the client and the server we're not going to send the client secret down to the client, because it's a secret and you really can't keep a secret in the browser. So start this thing up with npm start now.

A

I can open a browser and I still have ngrok running from before now, since uh I recorded that other segment I've switched over to my registered paid for ngrok URL, so I don't have to keep changing it as I. Do this recording- and you can see now- I logged in and I'm identified as employee number, one Nancy, which is the one that I associated with my user login. So even though I'm actually logged in as Megan and it looks like I'm Nancy I might just be a little confused.

A

But that's just the linkage that we made to the Northwind database and I can click around and look at all the products and the product categories and the orders and all this different information which is actually stored. Now in the Json files that I downloaded earlier.

A

If you log off it's important that log off always works and it does and then of course, I'll get prompted to log in again back at the application and that's the way it should work for you as well.

A

So, let's take a moment to look at the source code here, the client side login, is using a library called msel and Microsoft authentication library and I'm not going to get into that because, uh frankly, we're gonna we're gonna, replace that with uh teams code anyway or augment it with teams code anyway. But what will stay? The same is the server side, where we're going to actually be validating requests from the client to our own web service.

A

So here we are in server.js, where we're setting up Express and notice that they're on line 24, there's initialize identity service and if I come into the identity service, module you'll, see. Here's that same call and what it's going to do is set up a validate aad login web method.

A

That I can call from the client and get back the employee ID. So it's going to call some underlying code and then look up the employee ID based on that code, plus every API request to get the data or the the whole. You know back end. That's providing data to the Northwind UI under slash API, this piece of middleware, and you can see that now on line.

A

34 we're using a library and aad.verify is going to take the token that we got from the client the audience, because you don't want to accept somebody else's token and then it's going to check the the digital signature and everything and make sure that it's a valid token, and if it is we'll output, something to the console and if not, then we'll we'll output, an error and return a 401 access tonight.

A

Now, if we go down a little bit further, here's where we're actually looking up the employee ID so that we know which orders to show and and what to show on the UI for that employee. And so what it's going to do is same code to verify the token. And then it's going to look for a user ID from that, and it's going to call another function here. Called get employee ID for user and get employee ID for user is going to call the Microsoft graph.

A

That's the main API for all of Microsoft, 365 and Azure ad, and so we're just going to use this to look up the employee ID, and you can see that on line 94 where there's a dollar select equal, employee, ID, so graph is a whole subject unto itself. We are planning Labs specific on graph, but to keep it really super simple here: we're just calling it with a regular fetch.

A

So what we had to do is on line 91 I had to exchange my access token that just got sent from the client for an access token that can call the graph and then we're calling the graph getting the current users, employee, ID and returning that up and then come down to the very bottom. Here's that, on behalf of access token, this is how a this is, how you can exchange the access token that you get from a client for your app for another access, token Downstream to call another service like the Microsoft graph.

A

You can think of it kind of like constrained delegation in Kerberos. If you remember that stuff, but basically this is these. Are the steps to call the graph in the most simplest way from our application and because it's a native Azure ad application, it's designed to go ahead and and get information from the graph so that the source of truth about users is in fact Azure active directory.

A

I hope this video makes it easier for you to complete your journey through teams at Camp. Once you've completed the Core Labs, you can go on to the extended labs and add Advanced features to your application. So, thanks for watching and I wish you smooth sailing as you complete the lab.