Access the Microsoft Graph with a script

In a recent article I showed how to connect to the Microsoft Graph in a web browser:

Using the Microsoft Graph Explorer

I also showed how you could do the same:

Using Interactive PowerShell

This article is going to focus on how you can do the same thing but directly via a script that won’t prompt you for credentials.

Before running this script you’ll need to follow the Using Interactive PowerShell article and set up an app in your Azure AD.

image

image

During that process you’ll need to record three things that will be used here:

1. Application ID

2. Tenant ID

3. Client secret

I borrowed the connection piece of this script from:

https://www.lee-ford.co.uk/getting-started-with-microsoft-graph-with-powershell/

which I found really handy in helping me understand all this. You can download my script from my GitHub repository here:

https://github.com/directorcia/Office365/blob/master/graph-connect.ps1

You’ll need to enter your own Application ID, Tenant ID and Client secret in the variables section. After that, all you need to do is run the script. The results for the query of /security/alerts will end up in a variable called $query which you can view. The actual content of the alerts you’ll find in $query.content.

image

This Graph connection script should now allow you to connect to the Microsoft Graph for a tenant and start running queries and returning values for entries in there. At the moment it only queries security alerts, but you can modify it to query anything in the Graph for your tenant.

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.

SNAGHTML55ab07

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

image

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

image

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

image

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

image

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.

image

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.

image

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

image

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

image

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.

image

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.

image

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

image

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

image

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.

image

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.

image

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.

 image

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.

image

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.

image

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.

image

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.

image

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

image

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

image

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!

image

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

image

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.


Using the Microsoft Graph Explorer

According to:

https://docs.microsoft.com/en-us/graph/overview

the Microsoft Graph is:

The gateway to data and intelligence in Microsoft 365. Microsoft Graph provides a unified programmability model that you can use to take advantage of the tremendous amount of data in Office 365, Enterprise Mobility + Security, and Windows 10.

In essence, it can give you access to a range of data about your Microsoft cloud environment. You can explore this data quickly and easily via a web page.

image

If you navigate to the URL:

https://developer.microsoft.com/en-us/graph/graph-explorer

You will see the Microsoft Graph Explorer as shown above. You can then select the button on the left to Sign in with Microsoft using your Microsoft 365 credentials.

image

You will then be prompted to login to your tenant as normal, after which you will see a consent acceptance as shown above. This is basically granting the logged in user access to the areas of the Microsoft Graph for your tenant. Select Accept to continue.

image

You should again see the Graph Explorer as shown above but in the top left you should now see the account you used to sign in. Just below that you will notice a hyperlink modify permissions which you should select if you want to access different areas of the Graph information for your tenant.

In this case, if you want to access security alerts from the Graph you’ll need to select this.

image

Scroll down through the window that appears and check the following two options as shown above:

SecurityEvents.ReadAll

SecurityEvents.RewadWrite.All

Then select the Modify Permissions button at the bottom of the screen.

image

You’ll then be prompted to log back into the tenant again because the permissions you require have changed and are only updated after you login to a session.

When you do re-login, you’ll be greet with a consent window again as shown above for the additional security permissions you just selected. Select Accept to continue. This consent option only appears once if you select to accept.

image

If you go back in and look at your permissions you’ll see the ones you selected are now Consented as shown above.

image

If you change the URL line in the Explorer to read:

https://graph.microsoft.com/v1.0/security/alerts

and then select the Run Query button to the right, after a few moments you will see the Response Preview area below fill with information.

image

If you take a close look at this information you’ll see that it contains security alert information. The case above from Microsoft Cloud App Security (MCAS) and reports “Activity from an Infrequent country” as you can see.

Why is this important? Couldn’t you view this same information from the admin console? Probably, but using the Graph provides a since entry point to queries for all this kinds of information, from all different sources in you tenant. You don’t need to jump between different browser windows. You don’t need to load different PowerShell modules. It is all in one place that you can query through a web request. Now, doing this via a browser and the Graph Explorer is only designed to show you what is possible using the Graph. Not only can we browse information using the Graph Explorer as shown here, you can also use PowerShell. That will be the subject of upcoming articles, and that is where things start to get really interesting!

Need to Know podcast–Episode 204

I’m back from MVP Summit and we have a huge amount of news to cover off in this episode. You’ll hear about the latest in Office 365 ATP, Windows Virtual Desktop, the new Microsoft Edge Browser and so much more. So much in fact that we had to hold a lot of material off until our next episode. However, don’t fear, you’ll get the most important stuff right here, so tune in and let us know what you think.

Podcast recording done using Microsoft Teams

Take a listen and let us know what you think – feedback@needtoknow.cloud

You can listen directly to this episode at:

https://ciaops.podbean.com/e/episode-204-the-prodigal-host-returns/

Subscribe via iTunes at:

https://itunes.apple.com/au/podcast/ciaops-need-to-know-podcasts/id406891445?mt=2

The podcast is also available on Stitcher at:

http://www.stitcher.com/podcast/ciaops/need-to-know-podcast?refid=stpr

Don’t forget to give the show a rating as well as send us any feedback or suggestions you may have for the show.

Resources

@contactbrenton

@directorcia

CIAOPS Patron Program

New Edge Browser – https://blogs.windows.com/msedgedev/2019/04/08/microsoft-edge-preview-channel-details/

Shared Computer Access comes to M365 Business – https://blog.ciaops.com/2019/03/19/microsoft-365-business-adds-shared-computer-activation-sca-rights/

New Office 365 ATP licenses – https://docs.microsoft.com/en-us/office365/servicedescriptions/office-365-advanced-threat-protection-service-description

Office 365 ATP Automated response – https://techcommunity.microsoft.com/t5/Security-Privacy-and-Compliance/Bolster-efficiency-of-security-teams-with-new-Automated-Incident/ba-p/392773

Window Virtual Desktop now in public preview – https://azure.microsoft.com/en-au/blog/windows-virtual-desktop-now-in-public-preview-on-azure/?WT.mc_id=reddit-social-marouill

Getting Started with Windows Virtual Desktop – https://techcommunity.microsoft.com/t5/Windows-IT-Pro-Blog/Getting-started-with-Windows-Virtual-Desktop/ba-p/391054

25% of Phishing email bypass Office 365 default security – https://www.bleepingcomputer.com/news/security/25-percent-of-phishing-emails-bypass-office-365-default-security/

Your approach to Office 365 needs to change – https://www.loryanstrant.com/2019/04/03/your-approach-to-office-365-administration-needs-to-change/

CIAOPS Techwerks 5–Melbourne May 10

bw-car-vehicle

Hot on the heels of a successful CIAOPS Techwerks 4 in Perth in April, Techwerks 5 will move to Melbourne on Friday the 10th of May. The course is limited to 15 people and you can sign up and reserve your place now! You reserve a place by send me an email (director@ciaops.com) expressing you interest.

The content of these events is driven by the attendees. That means we cover exactly what people want to see and focus on doing hands on, real world scenarios. Attendees can vote on topics they’d like to see covered prior to the day and we continue to target exactly what the small group of attendees wants to see. Thus, this is an excellent way to get really deep into the technology and have all the questions you’ve been dying to know answered. Typically, the event produces a number of best practice take aways for each attendee. So far, the greatest votes are for deeper dives into Intune, security and PowerShell configuration and scripts, however that isn’t finalised until the day.

Recent testimonial – “I just wanted to say a big thank you to Robert for the Brisbane Techworks day. It is such a good format with each attendee asking what matters them and the whole interactive nature of the day. So much better than death by PowerPoint.” – Mike H.

The cost to attend is:


Patron Level Price inc GST
Gold Enterprise Free
Gold $ 33
Silver $ 99
Bronze $176
Non Patron $399

To learn more about the benefits of the CIAOPS Patron program visitwww.ciaopspatron.com.

To register, simply email me – director@ciaops.com and I’ll take care of everything from there.

The CIAOPS Techwerks events are run regularly in major Australian capital cities, so if you can’t make this one or you aren’t in Perth on that date, stay tuned for more details and announcements soon. If you are interested in signing up please contact me via emails (director@ciaops.com) and I can let you know all the details as well as answer any questions you may have about the event.

I hope to see you there.

Define an IP range in Cloud App Security

image

For me, Office 365 Cloud App Security is a must have add on for any Microsoft or Office 365 tenant as I have spoken about here:

A great security add on for Microsoft 365

As with all services, once you have enabled it you need to do some customisation to get the best from it. The first thing you should do is define your ‘corporate’ IP addresses. These typically refer to your on premises environment.

The first step in defining these is to access Office 365 Cloud App security, which you can do from the Microsoft 365 Security Center. Once at the home page, select the COG in the top right hand corner.

image

That should reveal a menu like you see above. From this menu select the option IP address ranges.

image

Then select the Category option in the middle of the page and the option for Corporate.

image

You will then see an IP address ranges that have been defined as ‘corporate’ already. To add more ranges simply select the + (plus) button in the upper right. Doing show will provide you a dialog box like shown above where you can now enter the appropriate details.

Why is defining your ‘corporate’ IP addresses important? It helps prevent false positives, especially when you have multiple locations. This is handy when you start setting up rules in Office 365 Cloud App Security, you can easily use the ‘corporate’ definition to designate your known environment. It means also that when you add new locations you don;t have to go and change all your rules, just add top the ‘corporate’ IP range list.

Locking installed apps to Windows Store only

image

If you go into your settings in Windows 10 and select Apps you should see the above dialog.

image

You can see the options that are available to you as shown above. You’ll see that one of the options available is Allow apps from Store only. Although not a fool-proof security option but setting this would reduce the chances of malware executing on the desktop because the only method of installation is from the Microsoft curated Store. A random piece of malware, delivered via email say, could not execute since it doesn’t come from the Microsoft Store I would suggest.

image

Using Intune we can apply this setting across a range of Windows 10 desktops using a Windows 10 Device Restriction Policy as you see above. Simply locate the App Store option, then Apps from store only and set the value to Require as shown.

In a short period of time, once the policy has deployed, those devices will only be able to install software from the Microsoft Store, preventing installation from anywhere else and hopefully also preventing malware installations.

The good thing about this restriction is the user can still be a local administrator of their machine if you desire and installations will be restricted. The other good things is that it is policy based, which means it is easy to turn on and off as required or exclude users if need be.

As I said earlier, it is not a fool proof method of preventing malware being installed on a Windows 10 desktop, but would certainly make it much more difficult. In this day and age, we need all the help we can get to counter the threats. Hopefully, this will help.

Enabling Microsoft Stream transcribing

image

Every plan in Microsoft 365 and just about every plan in Office 365 includes Microsoft Stream, which is a private video hosting service from Microsoft. Stream is also integrated into Microsoft Teams, so that, if you record a meeting in Teams it is automatically saved in Stream for replay later. You can also transcribe anything spoken in the video to searchable text within Stream.

You may however find that this automatic captioning is not enabled by default in Stream. To see whether it is, simply connect to your tenant via PowerShell and run the command:

get-CsTeamsMeetingPolicy -Identity global

In the results look for the line:

AllowTranscription

as shown above. If it is set to False, run the command:

Set-CsTeamsMeetingPolicy -Identity Global -AllowTranscription $True

to enable Stream transcription. Note, that it may take a little while for the policy to be applied.

Now, when you upload a video to Stream or record a meeting in Teams any speech should be transcribed for you automatically.