We love that the community has great discussions on Microsoft Secure Score.  One of the topics we hear from you and other organizations is on the Secure Score API.  This is a great way to programmatically access Secure Score data.  Over the past year and a half, we have received a lot of feedback on the API and the Microsoft 365 Security Engineering team is pleased to announce the availability and preview of the new Microsoft 365 Secure Score API.

 

As part of building the new API we also wanted to provide it in other languages.  In doing this work for the API, it also gave us localization of the Secure Score interface.  The localization of the interface is starting to roll out.

 

What’s new?

The new API is based on much of your feedback and has a host of changes to enable new scenarios.  At a high level they are:

• Integrated into the Security Graph API, allowing easier permission scoping.
• Support for filtering methods such as $top=2 or explicit control access.
• Dual entities, an entity for bringing back just the score data and an entity for bringing back control metadata such as Title, Descriptions and Threats etc.

 

• Patch support, allowing you to flag controls as 3^rd Party or Ignore.
• New fields, such as “assignedTo” and “tenantNote”.
• Support for delegated admin rights.
• Available in the Microsoft Graph Explorer.
• Localization will start to appear over the next few weeks. The first languages will be Czech, Danish, Dutch, French, German, Hungarian, Italian, Japanese, Korean, and Spanish.

 

Why did we use the security API and connect with Microsoft Intelligent Security Graph?

The Intelligent Security Graph is a unified platform for combatting cyberthreats. It powers real-time threat protection for Microsoft products and services and supports an ecosystem of integrated solutions.

 

The security API in Microsoft Graph makes it easy to connect with those solutions in the Intelligent Security Graph. It allows you to more readily realize and enrich the value of these solutions.

 

We see three common business scenarios driving consumption of the Secure Score API through the Microsoft Intelligent Security Graph:

• Monitor, track and report on your configuration baseline and score in downstream reporting tools.
• 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.

 

Getting Started

Acquiring the Secure Score data from the API requires you to setup a few pre-requisites.

First, you should choose your consumption model.  If you plan to have a non-user-interactive application to retrieve data from the API, you should opt for the Service-To-Service Authentication model. Reference information about this model is located at https://docs.microsoft.com/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 API, you should opt for the user OAuth model. Reference information about this model is located here.  If you are a CSP application developer partner you can also find information here.

 

Second, you will need to register your application in Azure Active Directory in order to call the API.  You need to grant the SecurityEvents.Read.All and SecurityEvents.ReadWrite.All permission scopes. See here for further details.

 

Now you’re ready to access the API.  For more details on how to use it, head over to:

https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/security-api-overview

https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/securescores

 

We hope you all enjoy the new API and start using it right away.  For those of you who are currently using the original API, we recommend that you migrate to the new one before January 31^st, 2019 as we will deprecate it at that time.

 

If you have any questions, thoughts, comments on the new API please share them with us below. 

 

Thanks for continuing to use Microsoft Secure Score!