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.

MSP Microsoft Partner MFA request

I’m not a Managed Service Provider (MSP) but there are lot of them inside the CIAOPS Patron community so I understand the challenges they have. Their role is typically to provide managed of customers technology, including things like Microsoft 365 and Azure. To perform that role they will typically need global administrator access to the clients tenant. They may need this access across multiple tenants.

Best practices is always to ensure you secure global administrator access via Multi Factor Authentication (MFA). This means, when you log into an account you’ll be prompted to verify your identity using a second factor like a code from an app on a mobile device. As I have detailed previously:

Using multiple authenticator apps with a single Microsoft 365 user account

you can have multiple ‘tokens’ to verify an account. If you want all of these tokens to be unique the current Azure AD arrangements are:

“Your users can now have up to five devices across the Authenticator app, software OATH tokens, and hardware OATH tokens.”

per – https://techcommunity.microsoft.com/t5/Azure-Active-Directory-Identity/Hardware-OATH-tokens-in-Azure-MFA-in-the-cloud-are-now-available/ba-p/276466

That arrangement is generally fine if only one person is logging into an account but is a problems if you an MSP.

Why? Because you’ll typically have multiple technicians all needing to potentially manage a customers account. You want them to do this from a single global administrator account, however you want each technician to use a different token when they login. That way, if a technicians device gets lost or a technician leaves you merely revoke that one unique token. So, in the case where an MSP needs more than 5 tokens (say 1 for MSP and 4 for technicians) there is going to be an issue. For example what happens when you have 7 technicians say? Yes, there are ways around this but they are messy, cumbersome and inefficient as well as being more insecure I would suggest.

The ask here then is for the ability to increase the amount of tokens beyond 5 for a single account. I would suggest that perhaps the best way to accomplish this is only via a unique PowerShell command and not via the GUI. I also however suggest that a better idea would be to have a new unique global admin role in a tenant, say called “Partner Global Administrator”, that would allow more than 5 tokens. No other administrator could have this enabled, only this unique account. I would also suggest that this unique “Partner Global Administrator” also only be available in tenants that use CSP program from Microsoft. Thus, if the MSP is a CSP partner they will see this special role in the tenant. They then run a PowerShell script if needed and the number of tokens available on that account is increased up to say 20.

I also think that there is number of other benefits that a special “Partner Global Administrator” role could provide but for this request I want to stick to allowing the number security tokens be increased beyond 5.

I believe this request will help the many MSPs globally who manage a significant number of tenants for customers. Making it easier for MSPs to be secure and manage multiple customers more efficiently is a win for everyone.

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/

A Microsoft Partner benefits request

action-adult-advice-1120344

One of the great things about being a Microsoft Partner is that you can get access to NFR (Not For Resale) software. This is great for testing and evaluation. Typically with the Microsoft Cloud services, partners get access to Office 365 E3 and around $100 of Azure credits each month.

These benefits have been in place for a long time and I would like to suggest some consideration for change. Why? Well, many partners are now selling a variety of different licenses, including Microsoft 365 which contains a variety of different service offerings. Many of these are now very different from the standard Office 365 that partners currently receive as NFR.

Just having access to a ‘generic’ Office 365 E3 can make it challenging when it comes to fully understanding what functionality different licenses may or may not contain. For example, to really evaluate what an F (Firstline) license does you really need to play with it and see it in action, especially if you are potentially recommending these to customers.

With so many different licenses now available it is not possible to give one of each to partners. However, I suggest that a workable solution maybe to provided partners with an amount of licensing ‘credits’ that they can use to provision what they. For example, maybe an Office 365 E5 license is 75 points and a Microsoft 365 Business is 25 points. Those two combined then up to the allocated 100 points. Or perhaps 2 x Microsoft 365 Business Licenses (50 points in total) + 2 x Microsoft 365 Firstline licenses (say 30 points in total) and then 1 x Azure AD Premium P1 at 20 points. Again, all of these add up to the requisite 100 points of an allocation.

Adopting this method would also allow partners to mix and match as required. Thus, if they already had 100 points of licenses allocated, they would need to drop one so they could test something like the Firstline SKUs. Then when they are finished they could cancel those Firstline SKUs and go back to what they had originally.

Thus, as long as the allocated license ‘value’ does not exceed 100 ,partners are free to pick and choose whatever they wish within those limitations. For partners who have higher competency levels, then that base 100 point level could be raised.

Focusing on Azure credits now, I don’t believe the current $100 is enough given things like Azure AD Domain services alone for a month exceed this value. If you are looking to build and evaluate something like the new Windows Virtual Desktop Services in Azure, $100 simply isn’t going to allow you to really do that all. I would suggest that a more suitable figure these days would be around the $300 – $500 mark. I’m also sure that perhaps if partners were to become certified in Azure then they could be recognized with additional credits?

Hopefully, this request reaches the ears of someone at Microsoft in the Partner ecosystem as I think that it has been quite a while since partner benefits have been examined. I would like to think Microsoft is looking at better ways to enable their partners to sell a greater variety of the software that is now available. If you are a Microsoft Partner and you like my suggestion, please share it and let others know that we want to sell more Microsoft solution but we new approach to the benefits we are entitled too I believe.  

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.