Using the Microsoft Graph PowerShell SDK for common operations

[Music] glad to be presenting to you folks today on this very first day of summer it doesn't look anything like summer where i am i'm actually located in ottawa canada and it is a cold 15 degrees right now i am a senior program manager on the microsoft graph team i'm also i'm focusing more on the component called microsoft graph data connect which is a way for you to extract data in bulk and i'm also the principal lead and creator for the microsoft 365 desired state configuration tool the topic for today is going to be a little different than what i normally present right i've been presenting uh on this forum a couple different sessions today we're going to be talking about the microsoft graph powershell sdk what i want to do is i want to just quickly do a quick overview of what the module actually is it is something that's available right now in the official powershell gallery for those of you that are not familiar with the powershell gallery you can go to powershellgallery.com so this is a microsoft owned website where we publish all of the yes it's 15 celsius brian very important i should have mentioned that i'm in canada so we talk celsius but the uh so it is available in the fireshell gallery and essentially what it allows you to do is to install the any modules that we published with a simple uh command right so you can go and install module for example microsoft 365 dsc it will go and will automatically download the bits from the powershell gallery and install them on your machine now microsoft graph is a a group of about 40 plus different powershell modules right in total they make for about 660 meg of powershell goodness so when you're you're writing your own scripts it's really important that you only pick the ones you want unless you want to install the whole thing be my guest however normally when you write your scripts you're going to go in and let's say you're trying to interact with emails you're going to go and install the microsoft draft.mail module only which is only about 10 magazine sites overall when you install all the microsoft graph modules we offer over seventeen thousand different commandlets in powershell we support powershell 5.1 and we also support powershell 7 and above really important now every single graph operation that is exposed right is going to be exposed to various command lists to get this new the set they remove right so essentially your crowd operations create read update and delete the permissions for the commandlets are going to be driven by azure id so you go in and you create your azure id um application registration and then you can either grant delegated or app-only permissions like you would if you're writing any application that would call the rest apis and automatically as i mentioned right when we on board new api so when new features are being rolled out or when new workloads are being migrated over to microsoft graph we automatically provide powershell support so we essentially wrap it directly inside of a powershell command list so it's always up to date so when we have it on microsoft graph we have it in the powershell module another thing that's really important to note is that it is open source on github so if you have any questions if you have any feature requests or if you uncover any bugs you can go in the github repo and then just open an issue in there and you're going to be talking to the product group directly that's it for the slides um now let's move on to the demos the first thing is i wanted to do a quick tour of the powerstell gallery so this is what the firesalt gallery looks like if you do a search on microsoft.graph you're going to see all the various parcel modules that we have right so those are the 40 plus modules that i mentioned if you're trying to understand right because there are so many modules there are over 17 000 different commandlets let's say you're trying to get user emails right and you know that the command you're looking for is the get dash ng ng stands for microsoft graph user message but you don't know what module you actually need right um and eric yes there are many partial modules but we're making it easier for you to figure out what module you actually need right so if i go in here and i actually just go and let me just clear this here if i go in and just execute and i'm using the powershell ise just because it makes my demos a little easier to go through but essentially if i do the find module and then pass in the command name i can go in and get the module that's associated with this command here and then what it returns me is essentially information that the command i'm looking for is part of the microsoft.draft.net powershell module so what i can do then is i can go in and simply go and install this module here to get access to this command what i'm going to do here is i actually have a few modules that i need to install for my demos so i'm going to go in i'm going to install the main one that you will need for any script is the grab that authentication one that's the core module for the microsoft graph firestop sdk that will allow you to go and obtain the token from the microsoft graph right so this is what you would use to go and connect essentially to microsoft graph in my case i'm going to go and grab about five different modules directory management's probably more like six or seven the mail the reports the teams and the actual users and i'm going to go and use that install module command that i mentioned so what i'm going to do is i'm going to go and i'm going to run this and what's happening in the back end you can see it here where it's actually downloading the modules from the powershell gallery and installing them on my machine what installing means in this context here it's essentially downloading it as a zip and extracting it in a specific folder and that folder is under c program files windows firestone module when you're installing it for all users right you have the choice of powershell 7 to go and install it directly inside of your users folder but um normally these full these modules would just get exported in there and if you take a look at the various modules all you see is that those are actual powershell modules right so there's no binaries being installed it's just downloading powershell modules and putting them in that location so now that we have everything installed what i want to show you is how authentication works the first thing i'm going to do is i'm going to be connecting to microsoft graph using a delegated scope so i'm going to be connecting using the connect mg graph command and i'm going to be specifying the scope the permission scopes i want my user to get in this case i'm gonna go and get mail.read and you know what i don't even need this here because i did update my my demo so i'm gonna go and do mail.read so let's do this here real quick i'm actually just gonna make sure i'm not connected to any other sessions i'll connect to microsoft graph it's going to prompt me for my username and password so in my case i'm already connected with my account connect i've acquired the actual token and now i can go in and do operations against the graph what i'm going to be doing here is i'm going to be calling it to the get mg user message commandlet and passing in my user the user i actually connected to microsoft graph with and i'm going to be retrieving the emails at least the top 10 emails for that user and i'm just going to be printing out the subject for those emails so let's run this here and i'll come back with the subject of the last 10 messages right most of them are actual pam privilege access management request but i can see that i managed to go and extract emails now if i try to do the same thing and get the emails for another user so good old adele in my demo tenant i'm going to go in here and try to connect to this and i'm going to get an access denied reason for this is because i've authenticated using a delegated scope which means that the token is only valid for the user scope that i connected with which means i'm only able to get my own emails right so i can't go and get information for other users now let's take a look at app-only authentication so i'm going to go in i'm going to disconnect here and what i've done is i've actually inside of i should have done this here instead inside of azure id i created a new app registration called nick powershell app only and for that app i've actually granted some application level permissions those are mail.readwrite that's the one we're really interested in these are going to be useful for other demos later on but essentially what i've done is i granted mail.read application right for that application in my powershell script what i'm going to do next is i'm actually going to go and authenticate using that app id right the client id here i do have a certificate that's installed and i'm going to connect that that tenant id so let's let me obtain that app only token um perfect yeah i already disconnected perfect so now let's do the same thing i'm going to go and i'm going to get the messages or the emails for the nic users so my account it's coming back with my 10 top emails but we were able to do that with delegated now if i go in and try to get the messages for adele i'll be able to get her email which are different than the ones nick had of course because i'm now authenticated as a service principal using app only permissions are the powershell modules pre-installed with azure shell i believe they are now i need to double check that i'll have to confirm that but last i checked and actually that should be fairly easy for for me to check i see vasa uh the eyes on the call based on if you don't mind just go in and double checking but last i heard the the microsoft graph modules were available with the azure cloud shell let's move on to uh another thing right so i did mention that any endpoints had powershell commandlets exposed for them so essentially so and so we can do crowd operations in this case here what i'm going to be doing is i'm going to be connecting using delegated permissions i'm going to be using the scope chat.read write which essentially allows me to send messages what i'm going to do is i'm going to go in and i'm going to be sending a new chat message to my admin user and the message is just going to be something like demo demoing posh graph sdk and today's date so if i go in and run this here this is again just to show you that it works for any crowd operations i'm going to connect with my account and it should if i go back here i did have teams open i should see there you go new message 11 28 11 28 it is my local time and you can see that i was able to actually send a message on behalf of the delegated users which is nick charlevoi in this case uh to my admin account great moving on um how do you find permissions this here is something we have been asking for months before they actually released it right so the partial graphics it was released if i remember correctly sometimes in 2020 this fine mg graph command was released with version 1.7 just a few months back but it allows you to go and discover the various commandlets based on urls and also identify what permissions your apps are going to be requiring based on the command list you're using let me give you an example so let's say you're going in and the first thing everybody should be doing when they're trying to learn microsoft graph is go to the graph explorer you go to the graph explorer and in my case i'm trying to go and understand all right i want to get all the security alerts from my environment so if i go in here i can see that the url for this is slash security slash alerts okay so that's the url for the graph rest apis so what i can do now is using this find mg graph command i can go in and say right find the commands that are associated with this uri that is the security slash alerts and if i run this it's going to come back and it's going to tell me all right here are the commandlets you're looking for the get ng security alert and the new mg security alert if we take this a step further i want to understand right that's all good but like what permissions do i actually need this is another example where we're going to be trying to get information about the get mg directory setting command right get mg directory setting is um is a way for me to actually be able to get different policies from my azure id so i'm going to go and run this but this time i'm going to go and select the permissions from the return so if i run this here it's going to come back and it's going to tell me all right if you're trying to use the get ng directory setting here are the permissions you need the reason why i have two by the way is because this is available on um so there's actually a new and a get there right but i'm going to be able to see that all right so the least permission you need is directory that access as user.all and it's always from left to right right the least like the the lowest level of permission you need is directory that access users.all and the permission that will grant you access to more than what you actually are looking for probably is the directory that read write all but it's always from left to right um thanks very soon so all right so i thought it was installed by default but i'll double check with the team but yeah all right so you could do an install module and just grab it in there and then it would be go into your local storage account and you'd be able to use it in the azure cloud shell right so that's for getting the actual uh permissions now how do you differentiate between the beta and the v1 endpoint let me connect again i'm going to be using a delegated scope i'm going to be using the directory the read write all so which is the top permission that i need i'm going to go and connect this prompt me for my username again get my token i'm all good now i'm going to go in and i'm actually going to try to call into the get mg directory setting command like we know this exists like we were able to get information about it so i'm going to go and run this right and it's going to come back with an error saying yeah that command like we don't recognize it as the name of the command line but i know it exists right why is that well that's because it's only available in the beta endpoint right now the way uh you can tell what current profile you're running partial under is by using the get ng profile so i can see that i'm currently connected or using the v1 profile what i need to do is i need to switch to beta and i can do this by doing select ng profile and then pass in the name better so that will actually switch my profile it will load different command let's based on my selection shouldn't be taking that long perfect now i can just confirm that yeah all right i'm now running better and if i go in and do get ng directory settings now i can actually get the information back and i can do things like set the group's naming policy i can go in and do the groups lifecycle management as well this is how you flip between v1 and beta um one other example that i think is extremely extremely interesting is being able to retrieve basic auth sign in info right with the upcoming deprecation of basic auth how can you can you actually create a script that will go and monitor all the sign-ins against your environment to detect those basic bot connections so what we're doing in this case here i'm going to be connecting using app only i'm going to be retrieving the all the logins from the audit login signing uh endpoint for the past seven days i can go do seven days um i can do 30 days 90 days 180. and i'm gonna be filtering that based on date but also whenever the the client was in the browser or was in the mobile app for mfa for example so let me just go and run this here and then this will return me a list of all the um actually i need to print my variable that would be helpful uh so those are all the basic art authentication uh sign-ins that happen against my environment right so very useful for you to be able to monitor and try to understand right like what's going to be at risk when we finally get that deprecation of basic odd through the modules are updated um so they're not automatically updated when we have new additions to the graph right so we do have release cycles those are normally every month month and a half i would say so it's not as soon as an endpoint is available that we have the support for microsoft graph um all right and then the last one is running reports okay so i'm going to be defining a type the local path on my computer that's demo report cvs csv sorry and then what i'm going to be doing is i'm going to go and use the reporting endpoint called mg report mailbox usage detail i'm going to run this here i'll come back with an error because essentially we we still have um some gaps in the powershell graph sdk when we're trying to actually stream data back to a file the problem in this case here is that i'm trying to get the data and then populate it inside of a csv file so that is still not working we are working on this with version 2.0 that's going to come shortly in the meantime what you can do though is you can go in and you can call the invoke ng draft request command so that will allow you to use the current context so your your security token is applicable here and you can call in directly into a url in my case i'm going to be calling it to the url that this command let is calling behind the scene which is the report slash get mailbox usage detail and i'm going to be passing in the output file so that here will actually get me the data i want and then what i can do is i can just read that csv and powder uh i'll put it to outgrew for those of you that are not familiar with outgrid view it's a very useful little commandlet that we have that where you can actually pipe any object into it and it will generate a net interface that lets you go and filter sort and do searches against your your powershell object so that's all for demos um i'm quickly browsing through the chat um so are all sdk commands running with delegated permissions or essentially it's the same as the graph right if we support delegated permissions for the graph endpoint we have it for for the powershell command if we support app only we do have it right so the the idea is that identify what endpoint is being called by that commandlet and then go in and you can go on the docks on microsoft.com find information about that endpoint it'll tell you right like you know how our articles are at the beginning of every page we have a table that will say delegated here are the permissions you need app only here the permissions you need as well yes i will be sharing my demos as well so this file here um i'll be removing my certificate thumbprint and tenant id uh from it but uh yes i'll share that with vessels and vessel you it's gonna be on you to figure out how you want to share it uh probably push all of the presentation as part of the blog post and blog post summaries of the recording so all good awesome excellent thanks um that's all folks so i know there might be other questions in the chat so i'll answer them directly in the chat i appreciate you joining the session and uh i'll pass it over to alex thanks folks awesome job thank you nick a really good set of components and automation that's just brilliant stuff on the graph

Channel: Microsoft Community Learning

Views: 8,659

Keywords: PnP, Dev, community, open-source, Microsoft, Teams, Microsoft Graph

Id: ib3BrVNQkFM

Length: 19min 28sec (1168 seconds)

Published: Wed Jul 06 2022