Articles, Blog

How to Use the Microsoft Secure Score API

August 29, 2019


Stu Clark: Hi. I’m Stu Clark, a Program Manager on the Microsoft 365 Security team. And I want to give you a quick tour of using the API that Microsoft Secure Score offers. As you’ve seen in our previous videos, we offer you multiple ways to look at your score over time and analyze the controls that are making up your total score. Not many people also know, though, that using the API you can get to a next level of granularity and really start to dig in to what controls are influencing your score. So, what we’re going to do is we’re going to talk you through the API. We’re going to talk about a couple of important document locations. And then we’re going to walk through a PowerShell script that actually shows you how to use the API. And we’ll export the data into a JSON format, so we can start to manipulate it. So, the API itself is based off the Microsoft Graph framework. It’s housed on Graph. And as you can see here on the screen, the implementation is very simple. We only allow you to have one parameter within the API. And that’s known as period. Period is an integer between 1 and 90 which basically represents the number of days’ worth of data you wish to bring back. So if you wish to bring back 30 days’ worth of Secure Score data, you would specify 30 in the period parameter. And then when you run the command, it would bring that back. So, implementation is literally making the REST command, specifying your period, and you would then have a JSON blob that actually represents your data that we can now start to manipulate. There’s two important document locations to be aware of. One is the GitHub repo we provide. In here you’ll find a mixture of scripts from PowerShell to Azure, ranging in complexity from the most simple to the most complex. So, I strongly encourage you recommend browsing these sites. You will see a location further down in this video. We also offer you a very complex page which shows you how to do the implementation via an Azure-hosted app that you create. Again, that’s a very advanced paper. But it takes you through everything you will need to know. So, what we’re going to do now, we’re going to hop into PowerShell. And we’re actually going to do this. I will take you through the PowerShell script. And we will start to see how the data flows. The script you see now is a basic PowerShell script that uses the API. This very script you can find on the GitHub repo I mentioned earlier in the video. Now, there’s a couple of important things that we need to worry about if we’re going to edit this file and use it for your tenant. So, let’s a look at those now. The most important one here at the top is specifying your tenant ID. This is obviously crucial because we want the Secure Score data to come back from the correct tenant. You need to make sure you have a couple of prerequisite installations completed, which are basically the ADAL forms that we need to do authorization against Azure. As we step through the code itself, you will see this line here called a Client ID. Now, a Client ID is basically an application that is registered in Azure. So, the way Azure works is you have to grant consent for applications to authorize against it. This particular Client ID is the well- known ID for PowerShell. So as we’re using PowerShell, this is important for us to have specified in here. The rest of the parameters basically just tell us that we’re going to be using Microsoft Graph. We want to send a login request using the tenant name that we specified earlier on. As we scroll further down the script we can see it is, as I described, very basic. When we get down to the meat of it here, executing the REST query, you can see literally what we do. So, as I mentioned, we used the REST command, tenant scores. And here I’m specifying a period of 90. So, what I will do, I will change this to 30 for the purposes of this demonstration. All we then do is take the data that we defined earlier on in a PowerShell script, and we pass it that command. We invoke RestMethod, send it to the URL, send our authorization header, and then the results will come back. The final thing we do is then we convert this file to JSON, and we export it out, so we can start to manipulate it. Now, what I’ve done in this demonstration is, I’ve created a break point. So when I run the script, I can show you what the data looks like and the level of granularity that you’ll be able to find in here. So, let’s run this and take a look. So, the first thing is I get prompted for my username, which I will just enter. Now, I will be prompted for my password. Now, the script is off running and is now issuing that REST command against the environment. So, as you can see, we’ve hit the break point in the script, which basically means it’s paused where I wanted it to pause. Now, as you can see, the results from the REST query I invoked have come back to this variable called data. So, let’s take a look at data and see what’s in there. So, this data variable is the JSON blob that has all of your data for your Secure Score. Each object in the blob is a particular day. And as we go through it, it shows us the tenant ID and then starts to bring out the Secure Score data. So, we can see your licensed user count, your active count, what your current score is, what your maximum score is, across the thing. Where it gets really exciting for us in terms of how we want to do reporting later on, we bring you back the details of the individual scores as well. So, UserMFA we bring back. And we show you what the score is for an individual control. So, you can then start to implement that by importing it into a local reporting solution you have, or a sim, or anything else where you’d like to store this data and report on it. So, that’s a high-level view of the API and how to access it. Check out our other videos on how to now use this data in Power BI for advanced reporting. Thanks for watching.

No Comments

Leave a Reply