次の方法で共有

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:

  1. Monitor and report on your secure score in downstream reporting tools.
  2. Track your security configuration baseline.
  3. Integrate the data into compliance or cybersecurity insurance applications.
  4. 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.
  • 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:

registerapp

    • Pick an App Name, pick your implementation flavor:

nameapp

    • 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.

appproperties

  • 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.

configureapp

  • 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.

setupperms

grantconsent

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

}],

[{

…

}]

}