¶ Introduction
Microsoft provides a unified API to gain access to all of its cloud tooling through the Microsoft Graph API. Specifically, SOC.OS requires the ability to read security alerts from cloud security systems (including O365), listed here.
Setup involves registering SOC.OS as an application which can use the Microsoft Graph API. It should first be noted that permissions are granted to this application such that you can lock down access, meaning SOC.OS can only call the relevant security endpoints – SOC.OS will not have free access to your entire Microsoft cloud estate.
The process is outlined by Microsoft here, however, you only need to complete up to and including Step 3. This creates the relevant credentials for the application, which can then be sent over to the SOC.OS team to complete the setup. For Steps 1, 2, and 3 there is some information below which aids in the setup process, as there are a number of configuration options and some of the instructions may be unclear.
¶ Register your App
Instructions for registering your app can be found here.
This page offers a guide video and the steps required to create a new application. The settings required are as follows:
- Name: SOC.OS
- Supported account types: Accounts in this organizational directory only
- Redirect URI: Leave empty
¶ Configure Permissions for Microsoft Graph
Instructions to configure permissions for Microsoft Graph can be found here.
The full permissions reference is available here. The Security Permissions reference can be found in this section.
SOC.OS requires the ability to list alerts with permission type “Application”. Here, two Permissions are required:
- SecurityEvents.Read.All
- SecurityEvents.ReadWrite.All
It is unclear as to why both write and read permissions on security events in order for applications to just list alerts, but unfortunately our testing has shown that both are indeed required to do so.
SOC.OS does not carry out any write operations – it just reads the alerts listed.
To configure these permissions for SOC.OS, on the left side click:
Then:
Select Microsoft Graph:
Application Permissions:
Then select the two permissions under Security Events:
¶ Get Administrator Consent
Instructions on how get administrator consent can be found here.
This is easily achieved in the API Permissions tab:
By clicking Grant Admin Consent for…, which is to the right of the Add Permission Button:
This should result in a permissions list which looks like this:
At this point the application is configured to allow relevant security requests to the Microsoft Graph API. Finally, we need to create some credentials which SOC.OS will use to make requests to the API – specifically, it needs an Application (client) ID, Directory (tenant) ID and Application (client) Secret. To get these:
In the overview tab:
Keep note of the Application ID and Directory ID:
In the Certificates and Secrets tab:
Create a new client secret:
Name the client secret SOC.OS. Give it a reasonable expiry date (when it expires, a new secret will need to be generated and provided to the SOC.OS) – suggest 1+ years. Keep note of the secret generated.
Once you have completed the above and obtained an Application ID, Directory ID and Application Secret, we’ll need to receive these from you in a secure manner, we can provide access to a secure OneDrive location or via your preferred method.