Using the Office 365 Secure Score API
The Office 365 Security Engineering team is pleased to announce the availability of the Office 365 Secure Score API. This API is fully integrated into the Microsoft Graph. If you are wondering what the Office 365 Secure Score is, get the low down here, or visit the experience here: https://securescore.office.com.
Why Collect Secure Score Data?
We think there are at least four possible business scenarios driving consumption of the Secure Score through an API:
- Monitor and report on your secure score in downstream reporting tools.
- Track your security configuration baseline.
- Integrate the data into compliance or cybersecurity insurance applications.
- Integrate Secure Score data into your SIEM or CASB to drive a hybrid or multi-cloud framework for security analytics.
Get The Data
Acquiring the secure score data from the API in a secure way requires you to setup a few pre-requisites.
- First, you should choose your consumption model. The pre-requisites fulfill both requirements, but you'll need slightly different implementations depending on your scenario.
- If you plan to have a non-user-interactive application retrieve data from the Secure Score API, you should opt for the Service-To-Service Authentication model. Reference information about this model is located here: /en-us/azure/active-directory/develop/active-directory-protocols-oauth-service-to-service
- If your application will require an administrator to provide their logon credentials each time you pull data from the Secure Score API, you should opt for the user OAuth model. Reference information about this model is located here: /en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code
- Second, you will need to register your application in Azure Active Directory (AAD) in order to call the Secure Score API. The steps to create this application are below:
- Navigate to AAD Portal, select your desired directory, click applications, click Add, Add a new application your org is developing:
-
- Pick a sign-on URL, and an App ID URI. You'll need the former in your consent grant URL, and the latter isn't used in our demo, but will need to be a proper URI format.
- When you click the check-box, you'll get the configure page for your new application. There are only a couple steps left! Take note of the ClientID and the Sign-On URL in the upper portion.
- Note the Client ID, Setup a secret, add a new application at the bottom, select Microsoft Graph and then add Read all usage reports permissions to your application.
- Save at the bottom. Then on the saved application configuration page, copy and paste the saved secret key to a safe and secure location. You'll need this in your service-to-service application configuration to get an OAuth token later.
- Once you have completed the application registration, you will now need to grant your application consent to pull data from the Secure Score API. The format of this URL looks like the Base URL model below. Actual URL sample is below that. When you follow that URL, you'll be asked for your admin credentials, and then asked for consent for Read all usage reports and sign in and read user profile (in order for the API to verify your role in the tenancy). Click accept, and you'll be all set!
- Base URL: https://login.microsoftonline.com/common/oauth2/authorize?response_type=id_token&client_id=YOURCLIENTIDHERE&redirect_uri=YOURREDIRECTURLHERE&prompt=consent
- Example for test application: https://login.microsoftonline.com/common/oauth2/authorize?response_type=id_token&client_id=6de5993b-4f67-4bfc-b755-57cea754b3c0&redirect_uri=https://portal.office.com&prompt=consent
Now that you have fulfilled all the pre-requisites, you are ready to pull the data! In the future, we'll provide sample C# code samples, and links to partners that have completed integrations, but for now, we've worked up two quick PowerShell scripts that demonstrate the two authentication models. All sample code and documentation about the Secure Score API can be found here: https://github.com/OfficeDev/O365-Cloud-Sec-Tooling
Get Secure Score with Interactive Logon: https://github.com/OfficeDev/O365-Cloud-Sec-Tooling/blob/master/Securescore/GetSecureScoreFromAPI-ADAL.ps1
This script will install a local ADAL library from GIT, then do a local prompt for credentials. If your global admin account requires MFA, this implementation will respect that. You will need to populate your Client ID and Redirect URL from above in the function called "Get-AuthenticationResult". The script currently dumps out the last 9 days of Secure Score results to the console. You can edit (a local copy of) the script to do anything else you like, including converting to CSV, or integrating into a different data store. Note that as of this publishing, the API is still in Beta. Come back in the near future to acquire an updated version of the script with the non-Beta URL.
Get Secure Score with Service-to-Service OAuth Application: https://github.com/OfficeDev/O365-Cloud-Sec-Tooling/blob/master/Securescore/GetSecureScoreAPI-S2S.ps1 and https://github.com/OfficeDev/O365-Cloud-Sec-Tooling/blob/master/Securescore/ConfigForSecureScoreAPI.json
This script requires you to populate the JSON file with your Client ID, your Application Secret, your Tenant Domain, and Tenant GUID. The PowerShell script imports the config file, acquires a token, then calls the API and retrieves the last 9 days of results. Note that as of this publishing, the API is still in Beta. Come back in the near future to acquire an updated version of the script with the non-Beta URL.
What is in the API?
The Secure Score API has one REST method:
https://graph.microsoft.com/v1.0/reports/getTenantSecureScores(period=1)/content
Where 'period=X' with X representing an integer value between 1 and 90, indicating the number of days historical data you wish to query from today's date.
Prerequisites
One of the following scopes is required to execute this API: Reports.Read.All
HTTP request
GET https://graph.microsoft.com/v1.0/reports/getTenantSecureScores(period=1)/content
Optional query parameters
If no parameters are specified, default method with no parameters will return most recent 1 results.
| Name | Value | Description |
| period | Integer | Integer indicating number of days of score results to retrieve starting from current date. |
Request headers
| Header | Value |
| Authorization | Bearer .Required. |
| Content-Type | Application/json |
Request body
Do not supply a request body for this method
Response
If successful, this method returns a 200 OK response code version object and collection of score data objects for every Secure Score control in the response body.
Example
Request
GET https://graph.microsoft.com/v1.0/reports/getTenantSecureScores(period=1)/content
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"value":[
{
"tenantId":"12bce6d0-bfeb-4a82-abe6-98ccf3196a11",
"createdDateTime":"2016-10-16T00:00:00+00:00",
"licensedUsersCount":28,
"activeUsersCount":0,
"secureScore":115,
"organizationMaxScore":243,
"accountScore":33,
"dataScore":45,
"deviceScore":37,
"enabledService":[
“exchange”,
“lync”,
“sharepoint”,
“OD4B”,
“Yammer”
],
"controlScores":[{
"AdminMFA":[
{
"score":"21"},
},
{
"maxScore":"50"
},
{
"count":"9"
},
{
"total":"16"
}
],
[{
…
}]
}],
"averageSecureScore":16.5588017,
"averageMaxScore":237.017166,
"averageAccountScore":3.69947028,
"averageDataScore":12.7047329,
"averageDeviceScore":0.154599056
}],
[{
…
}]
}