Using interactive PowerShell to access the Microsoft Graph

I recently published an article on how you can browse the Microsoft Graph directly from a web page here:

using the Microsoft Graph Explorer

The next step is to start working with the Microsoft Graph using PowerShell.

This article was recently published by Microsoft:

IT Pros can now easily connect to Microsoft Graph Security with the PowerShell Module!

and one of the confusing things I found where it talks about “Registering your application”, which you need to do successfully before you can run all the PowerShell commands.

Now if I find that confusing I’m sure others will also, as there is a bit of trick in setting it up correctly. So here is what you need to do, step by step, to actually get it all working.

Login to https://portal.azure.com using you Microsoft 365 credentials. Navigate to Azure Active Directory from the list of items on the left.

From the options available on the left select App registration (Preview).

From the pane on the right select New registration at the top of the page.

Give the new application a name. Here I have called it Graph. Next hit the Register button at the bottom.

You should now see the Overview of the app. On the right hand side save both the Application (client) ID and Directory (tenant) ID as you will need these later.

Here’s the bit that isn’t that clear in the existing documentation. Select the Authentication option from the menu and then on the right check the option

urn:ietf:wg:oauth:2.0:oob

From what I can work out, normally apps need to return to a location after using Azure AD authentication. However, because we will be using an interactive PowerShell session, the selected option will simply return there. Again, not really clear in the documentation I read.

You don’t need to make any other changes on the page but ensure you now select Save in the top left.

Next, select the Certificates and secrets option on the left. On the pane that appears on the right select + New client secret.

Give the secret a name and an expiry period and select Add.

You should then see you new secret and the actual value of that secret to the right as shown above. You will need to copy this secret value and keep it secure. treat it like a password.

You will see a banner across the top of the pane telling you that this is only time you get to see the value of the secret in the clear. After you navigate away, you’ll no longer be able to simply copy and paste the complete entry, so do it now and save the secret somewhere secure as you will need it down the track.

Now select API permissions on the left. You should see text Microsoft Graph is hyperlinked, so select this. This means your app already has some basic access to the Microsoft Graph, here just user read right. If the Microsoft Graph entry isn’t visible for some reason you can select the + Add a permission button at the top and then select Microsoft Graph from the following page. Hopefully however, the Microsoft Graph hyperlink will already be there.

There are two boxes at the top of the page. Ensure the left hand (Delegated permissions) one is selected first.

Scroll through the list of permissions in the bottom section until you find the heading SecurityEvents and expand it as shown.

Select both options as shown:

SecurityEvents.Read.All

SecurityEvents.ReadWrite.All

Once these options have been select, press the Update permissions at the bottom of the page.

You’ll be returned to the permission summary page as shown. You should now see the additional permissions you added displayed. You will however note a warning icon next to them as well as a banner across the top informing you that you need to consent to these. We’ll do that shortly, however we want to add some more permissions, so again select the hyperlinked text Microsoft Graph.

This time ensure the box on the right (Application permissions) is selected.

In essence, think of the box on the left (Delegated permissions) as permission for interactive sessions like typing commands into the PowerShell manually. that requires a user to login each time. The right box (Application permissions) however, is going to allow operations without the need for an interactive user login. Thus, we can run a PowerShell script and not be prompted for login. thus, while we are in here it is a good idea to set up both sets of permissions to give you the flexibility later.

 

As before, scroll through the list of permissions below. Locate the SecurityEvents heading, expand this and select:

SecurityEvents.Read.All

SecurityEvents.ReadWrite.All

Once selected, press the Update permissions button at the bottom of the page to save the changes.

You are again returned to the summary page where you should see all the permissions added. You should see permissions of type Delegated and Application for the security events. A set for each.

If you scroll to the bottom of the page you should see a Grant consent section as shown. Select the Grant admin consent for tenant button below. This means all users will have the permissions you just created. If you don’t do this, then they will have to consent the first time they access the Microsoft Graph using this method.

You should see the above prompt asking you to confirm that you will be consenting for all users in the tenant. Select Yes to continue.

In a few moments, your permission screen should show all green as shown above.

As a final check in the portal, select the Owners option on the left and ensure the appropriate users are listed here. These people will basically have the permissions to edit the application settings, like what has just been configured.

Now you can run an elevated PowerShell window and type:

install-module microsoftgraphsecurity

Once that has installed successfully you can run:

get-graphsecurityalert

Because this is an interactive PowerShell session you’ll need to login to the tenant. A login prompt will appear as shown, however be careful here. You enter your user login AND the Application ID from the app just created in the Azure AD portal here. That is the really long string of digits in the Overview part of the application you just added in Azure AD NOT the user password!

You’ll then be prompted for the user password and MFA if configured

If all of that is good then you should get results as shown above. Now you can continue on with your interactive PowerShell session and all the great stuff in the microsoftgraphsecurity module. Yeah!

The main trick is selecting the urn:ietf:wg:oauth:2.0:oob option as the Redirect URI when configuring the app.

You may have noticed that we have used the Application ID here but not the Application secret. That is because this is an interactive session where the user is required to login in first. if we don’t want to be prompted for a login we need to use the Application secret. That process will be covered in an up coming article so stay tuned.