Home

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.

api.jpg

 

  • Patch support, allowing you to flag controls as 3rd 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-ser....

 

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 31st, 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!

 

31 Comments
Super Contributor

Maybe someone needs such API. But the simplest thing is missing - updating secure score via regular checking of related reports and not having to go through secure score flyouts.

Senior Member

Hi this great update for Graph API

 

My experiences

This works like a charm when using delegated permissions (user token is used to fetch the data) - Trying directly with Application Permissions, aka     grant_type client_credentials is able to request the endpoint, but returns empty value for the data.

 

Permissions for the app are: 

roles": [
"SecurityEvents.Read.All",
"SecurityEvents.ReadWrite.All",

  ],

 

Could somebody on MS end test the same using the same flow?

 

Br, Joosua 

 

 

Senior Member

Hi Anthony,

 

I'm seeing the same behaviour as @Joosua_ Santasalo where querying through direct application permissions returns empty values.

 

As this is in preview, I'm assuming that this is a work in progress, but can you help clarify this either way please?

 

Abul

Senior Member
I did some fiddler debugging, and found out that with Client_Credentials flow results in HTTP response 206 - with warning header 199 - "Microsoft/SecureScore/*/*" - Maybe there needs to be some different content type set. Will continue testing, and report back here :)
Occasional Contributor

Hi,

 

about the localization how will this work? Our product is in many languages and we want to control in which language the information is returned.

 

For example:

 

https://graph.microsoft.com/beta/security/secureScoreControlProfiles

 

is now returning information in english. How do we specify that we want the information in spanish?

Hi Christian,

 

To get the localized text you insert into the header the Accept-Language: parameter

 

Example - 

GET https://graph.microsoft.com/beta/security/secureScoreControlProfiles

Authorization: {{token}}

Accept-Language: fr

Occasional Contributor
Regular Visitor

We need to programmatically access the scores for the criteria displayed on secure score portal. We came across securescore endpoint/ method of graph API in beta version to get the secure score. We observed that securescore from graph API doesn’t render score for all the criteria displayed in secure score portal. 

 

Could you please suggest a way by which we can get the score of all the criteria programmatically. 

 

Below are the criteria for which we are not getting data using secure score graph API:

1.     Require PC and mobile devices to have advanced security configurations

2.     Enable Enhanced Jailbreak Detection in Microsoft Intune

3.     Mark devices with no Microsoft Intune Compliance Policy assigned as Non-Compliant

4.     Review blocked devices report weekly

5.     Require PC and Mobile devices to be patched, have anti-virus, and firewalls enabled

6.     Enable audit data recording

7.     Set outbound spam notifications

8.     Enable Information Rights Management (IRM) service

9.     Do not use transport rule to external domains

10.  Do not use transport white lists

11.  Review permissions & block risky OAuth applications connected to your corporate environment

12.  Discover risky and non-compliant Shadow IT applications used in your organization

13.  Set automated notification for new OAuth applications connected to your corporate environment

14.  Enable Office 365 Cloud App Security Console

15.  Set automated notifications for new and trending cloud applications in our organization

16.  Identify Shadow IT application usage in your organization by automating log upload from firewalls

17.  Detect Insider Threat, Compromised account, and Brute force attempts in cloud applications

18.  Set custom activity policy for your organization to discover suspicious usage patterns in cloud apps

19.  Do not use mail forwarding rules to external domains

20.  SPO Sites have classification policies          

21.  Do not allow anonymous calendar sharing

22.  Do not allow external domain skype communications      

23.  Do not allow calendar details sharing

24.  Tag documents in SharePoint 

 

Also the secure score gives only score data but no specific details like detailed information ex. It doesn’t provide all the admin MFA accounts for which MFA is not enabled for Enable MFA for Azure AD privileged roles. Is there a way to get such data programmatically (without using MSOnline)

Regular Visitor

We are using securescore endpoint of graph API in beta version to programatically get data and have noticed several discrepancies which are listed below:

 

1. The number of element in controlScores of the response varies on daily basis i.e. in the response json, count of elements in controlscores json fluctuates. We were getting 59 elements on 12-November-2018 which reduced to 51 on 14-November-2018. The elements which went missing were - BlockLegacyAuthentication, AltInfoIncomplete, MFARegistration, UserRiskPolicy, SigninRiskPolicy, UserMFA, AdminMFA, SelfServicePasswordReset.

 

response json -

  {"value": [...

"controlScores": [

{...

{

"controlCategory": "Identity",

"controlName": "ManyAdmins", ....

 

2. We identified that the score data was not reliable for few of the scores calculated. e.x. element with name ManyAdmins had a score of zero as the count of admin was zero, however we had 5 admins for the account. The count and score was correct 2 days back.

 

 

API URL: https://graph.microsoft.com/beta/security/secureScores?$top=1

Microsoft

Hi Himanshu,

 

The discrepancy in score is due to a service issue on the Microsoft side that caused the score for some controls to be unavailable for a few days. If you send me a private message with your tenant details, we can take a look at it and see if it is fixed now.

 

Thanks!

 

Jeff

Regular Visitor

Hi Jeff,

Thanks for the update.

I have messaged you the tenant ID. Also is there any update/info on the previous question.

Regular Visitor

 Hi Jeff,

As per discussion over private message, as you have suggested that whatever controls we don't get in secure score api response, it is safe to assume that the score for those controls are zero. Also as I had pointed earlier that we do get controls with zero score thus it's a bit enigmatic that few of the scores are not present in response.

Regular Visitor

Hi,

Can someone please update on the 2 issues I have raised on this page regarding securescore graph API.

Microsoft

Hello Himanshu,

 

For 1. as discussed over PM, whatever controls we don't get in secure score API response, it is safe to assume that the score for those controls are zero. 

 

For 2, that was due to a data issue that has since been resolved, the control should be scored correctly now.

 

Thanks!

 

Jeff

Regular Visitor

The license for Graph API mentions that we should not request more than minimum amount of data. What is this minimum amount? I could not find any limit in documentations. Also, is there any defined limit for request throttling? What is the minimum number of requests that can be considered safe (within limits)?

Regular Visitor

Thanks Jeff for the assistance.

As secureScore gives all the controls based on Office 365 services that are used, it is not possible to identify if the score for a control is zero or the corresponding service is not used.

This seems to be a limitation of the API. Are there any plans to resolve this?

Microsoft

tbhasme, that's a general Graph question, I will ask someone from the Graph Team to respond.

 

Himanshu, that's a limitation of the API but we recognize the need and are adding this functionality. Await our next blog post!

Regular Visitor

Hey Jeff,

 

Any update over the limits info? The general throttling limits listed here https://developer.microsoft.com/en-us/office/blogs/throttling-coming-to-outlook-api-and-microsoft-gr... does not talk about limits over 'security' api. There is also no mention of content limit anywhere.

 

Microsoft

tbhasme, I've followed up with the Graph folks. Send me a PM with your email address and I will connect you.

Regular Visitor

@Jeff Sun I have messaged my id in PM.

Regular Visitor

Hi,

We re-mediated the changes as suggested in the secure score control metadata API but we don't see any changes in score.

We have made a lot of changes and its been more that 48 hours but the score is constant.  Can someone please assist why the scores are not updated even after 48 hours .

Below are few of the changes that we made:

1. Enable Enhanced Jailbreak Detection in Microsoft Intune

2. Create a Microsoft Intune Configuration Profile for iOS

3. Activate mobile device management services

4. Require mobile devices to use encryption

These are few of the several changes that I have made but has no effect on the score.

Please let me know if tenant-id needs to be shared over DM.

We also observe same behavior on securescore.office.com portal which provides the secure score.

 

 

Microsoft

@Himanshu Singh, thanks for your feedback, there is definitely an issue here. Please share your tenant id and all the controls which you've found this issue over DM and I can file bugs on them to our dev team.

Deleted
Not applicable
@Jeff Sun - Do you have any ETA on when functionality to programmatically return status on -all- controls (not just the ones that can be used) will be released? Thanks in advance!
Microsoft

@Deleted, you can get all controls with the SecureScoreControlProfile entity. There is no plan to return all controls in the SecureScores entity at this time.

Deleted
Not applicable
Bummer - thanks for the info.
Regular Visitor

@Jeff Sun

Thanks for replying. I have DM the tenant ID and controls to look into this issue.

Regular Visitor

Hi @Jeff Sun 

As per secure score API, we are not compliant to some of the configuration recommendations. We are not able to follow the remediation steps to be compliant. Could you please suggest detailed and concise steps to remediate and be compliant as the provided steps are not clear/complete:
1. Do not allow external domain skype communications
2. Set custom activity policy for your organization to discover suspicious usage patterns in cloud apps
3. Review permissions & block risky OAuth applications connected to your environment
4. Set automated notification for new OAuth applications connected to your corporate environment
5. Review RMS device access report weekly
6. Review RMS usage report weekly
7. Review blocked devices report weekly
8. Require all devices to have advanced security configurations
9. Require all devices to be patched, have anti-virus, and firewalls enabled
10. SPO Sites have classification policies
11. Tag documents in SharePoint
12. Register all users for multi-factor authentication

Regular Visitor

@Jeff Sun,

As I had already shared the tenant ID and few controls here is entire list for which score is not getting updated after 48 hours

Below are the controls for which we made 48 hours back and still we are not compliant i.e. score has not changed:

  1. Require mobile devices to use alphanumeric password.
  2. Review blocked devices report weekly
  3. Activate mobile device management services
  4. Require mobile devices to use encryption
  5. Require mobile devices to lock if inactive
  6. Require mobile devices to manage email profile
  7. Require mobile devices to have minimum password length
  8. Require mobile devices to never expire passwords
  9. Require mobile devices to use a password
  10. Reduce mobile device password re-use
  11. Require mobile devices to block access and report policy violations
  12. Block jail broken or rooted mobile devices from connecting
  13. Do not allow simple passwords on mobile devices
  14. Require mobile devices to wipe on multiple sign-in failures
  15. Activate Information Rights Management (IRM) services
  16. Do not use mail forwarding rules to external domains
  17. Review malware detections report weekly
  18. Use non-global administrative roles
  19. Set up Office 365 ATP Safe Attachments
  20. Set up Office 365 ATP Safe Links to verify URLs
  21. Enable self-service password reset
  22. Set up versioning on SharePoint online document libraries
  23. Set outbound spam notifications

 

 

Microsoft

@Himanshu Singh, thanks for the feedback. For the 12 controls which you are unable to follow the remediation steps that are listed in the Secure Score, please work with support on those controls to help you configure them. They are the experts :)

Occasional Contributor

Hello Team,

 

I tried using the link: https://github.com/OfficeDev/O365-Cloud-Sec-Tooling/tree/master/Securescore and attempted to use S2S call and while running the script I get below error. Is this something that anyone here can help me with?:-
Invoke-RestMethod : The remote server returned an error: (400) Bad Request.
At line:1 char:1

  • Invoke-RestMethod -Method Get -Uri $ssAPI -Headers $headerParams
  •   + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException
      + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

 

Thanks,

Shivani

Microsoft

@Shivani_ra, that is the old API which we are planning on deprecating at the end of January this year. Please look at using the new API which is documented in this blogpost.