Microsoft 365 Community Community Demos, 13 Jul 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Microsoft Office Add-ins Single Sign-on (SSO) sample updates and demo

Description

In this 19-minute Developer-focused demo, David Chesnut relates how token handling in SSO NodeJS sample has been updated to not return a middle-tier token back to the client. Step through the logic of the three scenarios addressed in this sample. SSO with OBO (successful flow), SSO fails and must use MSAL (fallback flow) and the SSO token expired flow. Tips on extending this sample and 2 related SSO samples - ASP.NET and Outlook along with security notes. This PnP Community demo is taken from the Office Add-ins community call – July 2022, recorded on July 13, 2022.

Demo Presenter
• David Chesnut - Senior Technical Writer (Microsoft) | @davidchesnut

Supporting documents
• Documentation - Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow | https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow
• Documentation - Middle-tier access token request |
https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow#middle-tier-access-token-request
• Debug tool for examining tokens – jwt.ms | https://jwt.ms/
https://jwt.ms/
• SSO NodeJS walkthrough - Create a Node.js Office Add-in that uses single sign-on |
https://docs.microsoft.com/office/dev/add-ins/develop/create-sso-office-add-ins-nodejs
• SSO NodeJS sample Repo - Office Add-in that supports Single Sign-on to Office, the Add-in, and Microsoft Graph | https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/auth/Office-Add-in-NodeJS-SSO
• Documentation - Microsoft identity platform documentation | https://docs.microsoft.com/azure/active-directory/develop/

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

I'm going to talk about some sso sample updates that are in progress. There's been some information. That's that's come to our attention recently. We discovered that the node.js sample in particular, which I'll be talking about here, was returning a middle tier token and off some graphics to kind of explain, split more, but it was returning a middle tier token back to the client, which is not something you should do.

A

It's risky and I'll show some more information about that as we go along to kind of explain more about this, so we have on the office add-ins repo, there's a few sso samples, there's one for outlook, there's one for office with asp.net there's one for node.js, and it was the one for node.js in particular that that was doing this, the other two weren't returning the token in that way, although they do treat if they go to their fallback off, they do treat the fallback off that same way, so they are being updated in the process of that.

A

So let me walk through how things should work and how it does work now with node.js. So when you're doing sso with the on behalf of flow, because your goal is to call microsoft graph services, there's several different players in this flow, uh the black boxes on this slide are showing the parts that you would code. So the task pane add-in is, you know your javascript and the taskband gets displayed.

A

Then you have a middle tier server which has rest apis, that your add-in is going to call and the military server will through delegated access from the user. That signs in is going to call microsoft graph and to make this work. The office host that you're in be that excel word powerpoint or outlook is involved as well, and the microsoft identity platform. Is there because that's the platform, that's going to create the tokens and also handle authorization requests, so the way it works is your add-in is going to call get access. Token!

A

That's an officejs api that the office host exposes and then the office host will return to you for the currently signed in user, an access token- and you know anytime, you get an access token. I think a good question is access to what- and in this case it's an access token to your own middle tier server. So the add-in is going to use that to call the military server a rest api and then the middletour server is going to call microsoft graph.

A

So now it has to do this on behalf of flow, because that access token only has like user identity and an access as user scope. It has no scopes microsoft graph in it, so it can't be used, call microsoft graph, so it'll call out to microsoft, identity platform, your middle tier server. Does this and say hey? I want to exchange this for a graph token. Can you give me the scopes for that and you would pass along whatever it is.

A

You need like files.read, for example, so the microsoft edit platform will do all the proper checks make sure the user is consented and it creates a new graph token that it returns to your middle to a server.

A

So that's this token, that's sort of a greenish color, it's a new one, and now I can the middle clear server can call graph. For example, getting a list of file names, microsoft graph, will check that token and then return the data. I should also point out like every step, along the way where these tokens are passed, they're being validated, so your middletour server is always validating. Microsoft.

A

Graph would also validate any token pass to it, so it returns the data and your middle third server may do some additional processing on that, and then it also returns data back to the add-in.

A

So this is the successful flow. There's also another flow. The sample needs to handle, which is the fallback. This could happen say if the office hosts your own doesn't support the api, or maybe an error occurs, so you call get access token to your office host and you get an error back.

A

So in this case the adam's gonna say: okay, we're gonna have to do fallback authentication, because sso isn't working so we'll open up a dialog box, we'll use emcell microsoft, authentication library to sign in using the oauth 2 flow, so we're going to use microsoft, identity platform pop up a dialog box, get them to sign in and consent.

A

So we're going to get back an access token, and this is just like before this is an access token. That again is for your middle tier server. It doesn't have any graph access in it, so you're going to call your rest api, and at this point it's the same flow as before so middle to a server is going to do. Obo flow, get the graph token call graph data comes back.

A

Maybe you do some additional processing on that data before you return, whatever the atom needs, and then one more scenario that needs to be handled by this or it is handled in the sample is, if your token expired. Now this could happen like you get your access token from the office host and it returns the token and say the token was really close to expiring, so it doesn't happen very often, but it can so you call the rest api.

A

You pass that token in the military server it goes to do the obo flow, and at this point the token has expired and so identity platforms is not going to allow that. So you get an error back and the way we handle this flows. We have the military server return that error back to the client so that the client can say. Oh, I need a new token, so you call get access token again at this point. Office will see that it's expired.

A

It's not going to return an expired token, so it'll it'll refresh it behind the scenes. It'll actually request this from the identity platform. It gets the updated token just sort of this bluish color, and then it returns that token and again it's just an access token to your middle two server and you call the rest api and the whole obo flow continues again.

A

So so that's what the sample needs to handle and the thing that we changed is in this obo flow. The sample was returning that token to the client at least on node.js, and which is not something you want to do so. Let me share my desktop and just kind of walk through some of the code.

A

um Let's see, let's go to so there's a variety of links that I'm gonna I'll put these into the chat as we go uh probably right after the presentation. So so you have them. um So I want to point out uh the identity. Docs are your friend whenever you're doing working with this stuff, and so there is this link to the microsoft identity platform on behalf of flow, and it shows pretty much that same diagram I was showing office has an additional wrinkle.

A

You know that you have a task pane in the middle tier, but it's pretty much the same flow and down here. There's a warning that talks about- and this is what I just want to point this out like it says- don't send access tokens that you get in your middle tier anywhere else and there's a list of things that can go wrong. If you start doing that and then in the sample itself.

A

Let me get the code here. We go all right, so this is the office, a node.js sso sample and in the folder structure it's been reorganized a little bit. So you have your middle tier code down here in the routes, so there's a get files throughout and your server helpers, which are all to help call microsoft, graph apis and then the client side is here under the javascripts.

A

So everything that works with sso is in these three files for the most part, especially sso auth es6, there's also a fallback msl folder that has whatever you have to do fallback. This has all the code for doing msl, because it's sort of like you're implementing two auth systems, so there's a full m msl implementation here and then you also have your sso implementation down here um and see this in action.

A

I've loaded this up here in excel, and so this office added node.js sso. You click, get onedrive file names and what it does it goes. It gets an access, token does the whole middle tier obvio flow, and then you get back your file names here and they're printed into the document.

A

One thing I think is interesting that I want to show is when you get that token.

A

I want to show here like here's, where we're going to call get access. Token and I'm going to step over that, and then this is the actual access token it's all encoded. So I'm going to copy that and there's this site you can go to called jwt.ms and if you put tokens in here you can decode them.

A

This is the handy way to kind of debug things and see. What's going on, I find it very useful, so there's interesting things in here like there's this audience value, this audience value is set to the id of the app registration I created for my middle tier. So this is how I know this is going to access the middle tier, and so I go over sorry, I'm jump around a bit, but this is my azure app registration.

A

If I go up to the overview you'll see, I have that same id here, so you can look at any of the claims in here and you'll. See like this is pretty much just a user identity token. So it's got my name for my test tenant that I have preferred username, so it's kind of like open id values.

A

It also has the scopes which in this case is only accessed as user, so you won't see anything here having to do with microsoft graph, which is why you know the token on the middle tiers could be the one that's going to have an audience set to a microsoft graph location.

A

So anyway, if you ever need to debug, this is a very handy tool. I just want to make sure folks know about it and now, let's take a look at the code.

A

One thing I want to point out: I don't think in the original sample is very easy to extend like. If you want to add more functions, it was a little tricky. So the way this works is in the on ready. You know we're going to wire up the click event, so somebody says: get 10 a list of 10 files for my onedrive. Then it's going to call get file name list, and this is your basic pattern for calling any rest api you middle to a server you're going to have one function.

A

That makes the call and then another function that handles the response and the way this is working. This clear message is just clearing the task pane. So it's not an important part of this, but you want to create a request. So in the request you're going to say, I need to call this particular api on my server. This one's called get user file names. I'm going to have the name of my response handler, which is this function down here.

A

So you want to pass that for a callback function and then another callback function so that when the request is created, it'll pass it back to you. You'll get this client request. Once you have it, you can go call the web server. This seems a little complicated.

A

uh The main thing just want to show here is like say you wanted to get calendar items from graph right. You could create another function, get calendar items and you just do the same pattern, create requests but just plug in the rest, api in your middletown server. That does that particular function and then you'll get back the response to your handler, and then you just do whatever it is. You need to do with that response. Maybe just write them out to your document or show them in the task pane or whatever.

A

So that's how you would extend this sample now to show how it works. Let's take a look at the create request and what create request is doing is basically creating this little structure. It's a client request because of all those flows. I was just showing there's various points at which we might need to pop up a dialogue. If we're doing fallback, we might need to request a new token. So we end up looping around sometimes, and I found it was just easier just to create this request to kind of track.

A

What was the original thing we're trying to do, because there's there's like a lot of sequencing going on, so this will track our off options for sso, which we just default to true for all these there's a global variable for auth sso, that's defaults to true, but it'll flip defaults. If we have to do a fallback because we have to track whether or not which type of authentication are we trying to do with this request, we track the access token.

A

That's in use the url that we're going to call on our middle tier and then the two callback functions, one for when the rest api is completed and then the other one which we'll call right after we create this request.

A

So to create the request we check if we're using auth sso. If we are, then we're going to go get our token and then we're going to call our callback function and we've completed. If not we're going to go, use, dialog fallback pass the client request along and then the dialogue fallback will handle fulfilling that request and then calling back to the original function and then get access token from sso.

A

This is where it's going to do. The actual get access, token call to office, and then it returns that access token. If there's any error, then uh we go, we have a handler for that. This is actually was in the sample from the beginning to look at various sso errors and we'll throw an error back to the caller, which indicates that they're going to have to do fallback and then what was the other piece of this so.

A

There is a part in the flow later where we need to handle web server errors. So this is, we called our middle tier rest api, but it returned an error and I mentioned there's a possibility. It's like there's several. We track this type. The sample just does this like it creates a type, and it says: okay, it could be microsoft. Graph failed. If that happened, we're just going to show the error for microsoft graph, there's a possibility. We didn't have access as user for some reason, there's also possibility.

A

This is the error we get from the identity platform if the token expired- and in this case we're going to say, oh, I need to retry this call so we're tracking this and return that back to caller to go. Do a retry loop um fallout fails. There's this switchback switch to fallback off, which will setter global defaults and then create a new request. That's using fallback instead of off sso, so it gets sorta. I wish it wasn't quite as complicated as this I've been trying to simplify this and simplify it.

A

But you know it's it's open source. If folks have ideas on how to simplify this further, please feel free to contribute on the server side. I want to point out an important thing. I don't think this was here originally, but so when our middle tear server is called, you always want to validate that token. You don't want to just accept any token that gets passed to your server, because it's a public api endpoint.

A

So we have this op helper, validate jwt and then over here it's going to suck our validation options, so we're going to make sure like the audience is correct, like the audience should be for us and there's some additional information here.

A

If you want to know more about token validation, there is another topic in the identity docs which I'll throw a link into, because it's really just standard microsoft, identity, stuff, it's not really specific to office, and we're also going to check we're going to look through the scopes of that token that got passed to us and make sure it is an access as user scope and then once we've confirmed all that, and every api needs to do this- that that you're going to expose.

A

Then you would do the on behalf of flow and we set up. You know our graph url that we're going to call the parameters to you know, select the name and just the top ten, and then we use our helper methods to get to that graph data. And then we check to see what happened if graph returned an error. This is where we set our our error type to microsoft. Graph return that back to the client.

A

If it worked we'll return to success along with an array, that's a list of the file names, and we also check for the expired token scenario. So this is where we would set that if all else fails we'll just say it was a known error. We just pass along the details and they get surfaced on the task pane.

A

Let's see have. I just want to make sure I covered everything, go back to the slides here for just a second okay. So a couple of important security notes I'll pass along uh one is never cash tokens yourself.

A

It can be risky to do that. Especially if you have a bug, you can inadvertently end up exposing user data or leaking a token, and that could be bad. So what you do is you always call get access. Token office caches this for you so anytime, you need it just call get access token.

A

You don't need to try to go, create your own caching mechanism and, if you're, using like the on behalf of flow m cell, does the same thing like when you call that on behalf of flow, if the token was already acquired m cells, cached it for you, so you don't have to think. Oh, I got my obo token back. I need to store that somewhere and save it. There's no need to do that.

A

You don't need to well. Obviously you never returned from the middle tier back to the client, so I think we covered that pretty well. There is that link to the docs that explains more about what the risk is for that make sure you always validate the access. Token. That's past your rest, apis! um You might consider a well-known client list like if you know there are specific tenants. You work with. You can configure that in your azure app registration.

A

So that's something to think about. Also the client secret. Oh, I didn't show the client secret. Your middle tier will use a client secret to call and that should be stored securely, like maybe azure key vault. If I switch back yeah, let me switch back real quick.

A

I just want to show where that secret is there. Is this env file? That's in the sample there? It is this one and this tracks this is for the middle tier. So it has this client secret and you know for testing developer purposes. This is fine. We're just saying like when you deploy, you don't want to just have it in a file or something you'd want to actually go with the second azure keyboard, so that was that last slide see if we have any questions, but I am going to kind of go backwards here.

A

My sso access token, the audience is in outlook includes the server name. Is that something that outlook does differently from other office products, as everyone had just the id um yeah? I think you might see differences depending on which office host you're in behind the scenes office goes and requests the token from microsoft, identity platform, and I didn't show that flow, because it's it's not something you have to worry about so office, never creates these tokens. They always come from microsoft, identity platform. So there could be subtle differences.

A

The validation should work, I'm just looking. You have the audience api, localhost 4200., I'm not sure what you're saying there, because that looks like the the the reply not to reply the there's, a uri resource uri that you have to use which isn't the same as the audience, so the audience should always be set to the idea of your app registration. If it's not the token validation will fail.