Microsoft Graph Security
This document provides guidance on how to integrate the Microsoft Graph securityAPI with Google Security Operations (Google SecOps).
Integration version: 20.0
This document refers to the Microsoft Graph security API. In theGoogle SecOps platform, the integration for Microsoft Graphsecurity API is calledMicrosoft Graph Security.
Before you begin
Before configuring the integration in the Google SecOpsplatform, complete the following steps:
Create the Microsoft Entra app.
Configure the API permissions for your application.
Create a client secret.
Create Microsoft Entra application
To create the Microsoft Entra application, complete the following steps:
Sign in to theAzure portal as a useradministrator or a password administrator.
SelectMicrosoft Entra ID.
Go toApp registrations> New registration.
Enter the name of the application.
In theRedirect URI field, enter
http://localhost/.ClickRegister.
Save theApplication (client) ID andDirectory (tenant) ID values touse them later for configuring the integration parameters.
Configure API permissions
To configure the API permissions for the integration, complete the followingsteps:
In Azure portal, go toAPI Permissions> Add a permission.
SelectMicrosoft Graph> Application permissions.
In theSelect Permissions section, select the following requiredpermissions:
User.ReadWrite.AllMail.ReadDirectory.ReadWrite.AllDirectory.AccessAsUser.AllSecurityEvents.ReadWrite.AllSecurityEvents.Read.All
ClickAdd permissions.
ClickGrant admin consent for
YOUR_ORGANIZATION_NAME.When theGrant admin consent confirmation dialog appears, clickYes.
Create client secret
To create a client secret, complete the following steps:
Navigate toCertificates and secrets> New client secret.
Provide a description for a client secret and set its expiration deadline.
ClickAdd.
Save the value of the client secret (not the secret ID) to use it as theSecret ID parameter value for configuring the integration.The client secret value is only displayed once.
Integrate the Microsoft Graph security API with Google SecOps
Important: If you make any changes to theApplication Permissions orAPI Permissions in your Microsoft Entra ID (Azure AD) App Registration afterconfiguring this integration (for example, adding a new permission for a job torun), you must regenerate and update your credentials inGoogle SecOps.This typically means:
- Generating a new client secret in your App Registration.
- Updating the client secret (and regenerating the refresh token, ifapplicable) in the Google SecOps integration configuration.
Failure to update will prevent new permissions from being applied, causingactions to fail.
The integration requires the following parameters:
| Parameter | Description |
|---|---|
Client ID | Required The client (application) ID of the Microsoft Entra application to use in the integration. |
Secret ID | Optional The client secret value of the Microsoft Entra application to use in the integration. |
Certificate Path | Optional If you use authentication based on certificates instead of the client secret, enter the path to the certificate on the Google SecOps server. |
Certificate Password | Optional If the authentication certificate that you use is password-protected, specify the password to open the certificate file. |
Tenant | Required The Microsoft Entra ID (tenant ID) value. |
Use V2 API | Optional If enabled, the connector will use V2 API endpoints. Note: the structure of the alerts and events will change. |
For instructions about configuring an integration inGoogle SecOps, seeConfigureintegrations.
You can make changes at a later stage if needed. After you configure anintegration instance, you can use it in playbooks. For more information aboutconfiguring and supporting multiple instances, seeSupporting multipleinstances.
Actions
For more information about actions, seeRespond to pending actions fromyour workdesk andPerform a manualaction.
Add Alert Comment
Use theAdd Alert Comment action to add a comment to the alert in MicrosoftGraph.
This action doesn't run on Google SecOps entities.
Action inputs
TheAdd Alert Comment action requires the following parameters:
| Parameter | Description |
|---|---|
Alert ID | Required The ID of the alert to update. |
Comment | Required The comment for the alert. |
Action outputs
TheAdd Alert Comment action provides the following outputs:
| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |
Output messages
TheAdd Alert Comment action can return the following output messages:
| Output message | Message description |
|---|---|
| The action succeeded. |
Error executing action "Add Alert Comment". Reason:ERROR_REASON | The action failed. Check the connection to the server, input parameters, or credentials. |
Script result
The following table lists the value for the script result output when usingtheAdd Alert Comment action:
| Script result name | Value |
|---|---|
is_success | True orFalse |
Get Administrator Consent
Use theGet Administrator Consent action to grant your application thepermissions at the Azure portal.
This action runs on all Google SecOps entities.
Action inputs
TheGet Administrator Consent action requires the following parameters:
| Parameter | Description |
|---|---|
Redirect URL | Required The redirect URL that you used when you registered in Azure portal. |
Action outputs
TheGet Administrator Consent action provides the following outputs:
| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Script result | Available |
Script result
The following table lists the value for the script result output when usingtheGet Administrator Consent action:
| Script result name | Value |
|---|---|
is_connected | True orFalse |
Get Alert
Use theGet Alert action to retrieve the properties and relationships of analert using the alert ID.
This action runs on all Google SecOps entities.
Action inputs
TheGet Alert action requires the following parameters:
| Parameter | Description |
|---|---|
Alert ID | Required The ID of the alert to retrieve details for. |
Action outputs
TheGet Alert action provides the following outputs:
| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Script result | Available |
JSON result
The following example shows the JSON result output received when using theGet Alert action:
{"feedback":"@odata.type: microsoft.graph.alertFeedback","recommendedActions":["String"],"networkConnections":[{"applicationName":"String","natDestinationPort":"String","destinationAddress":"String","localDnsName":"String","natDestinationAddress":"String","destinationUrl":"String","natSourceAddress":"String","sourceAddress":"String","direction":"@odata.type: microsoft.graph.connectionDirection","domainRegisteredDateTime":"String (timestamp)","status":"@odata.type: microsoft.graph.connectionStatus","destinationDomain":"String","destinationPort":"String","sourcePort":"String","protocol":"@odata.type: microsoft.graph.securityNetworkProtocol","natSourcePort":"String","riskScore":"String","urlParameters":"String"}],"cloudAppStates":[{"destinationServiceIp":"String","riskScore":"String","destinationServiceName":"String"}],"detectionIds":["String"],"id":"String (identifier)","category":"String","fileStates":[{"path":"String","riskScore":"String","name":"String","fileHash":{"hashType":"@odata.type: microsoft.graph.fileHashType","hashValue":"String"}}],"severity":"@odata.type: microsoft.graph.alertSeverity","title":"String","sourceMaterials":["String"],"comments":["String"],"assignedTo":"String","eventDateTime":"String (timestamp)","activityGroupName":"String","status":"@odata.type: microsoft.graph.alertStatus","description":"String","tags":["String"],"confidence":1024,"vendorInformation":{"providerVersion":"String","vendor":"String","subProvider":"String","provider":"String"},"userStates":[{"emailRole":"@odata.type: microsoft.graph.emailRole","logonId":"String","domainName":"String","onPremisesSecurityIdentifier":"String","userPrincipalName":"String","userAccountType":"@odata.type: microsoft.graph.userAccountSecurityType","logonIp":"String","logonDateTime":"String (timestamp)","logonType":"@odata.type: microsoft.graph.logonType","logonLocation":"String","aadUserId":"String","accountName":"String","riskScore":"String","isVpn":"true"}],"malwareStates":[{"category":"String","wasRunning":"true","name":"String","family":"String","severity":"String"}],"processes":[{"processId":1024,"integrityLevel":"@odata.type: microsoft.graph.processIntegrityLevel","name":"String","fileHash":{"hashType":"@odata.type: microsoft.graph.fileHashType","hashValue":"String"},"parentProcessId":1024,"createdDateTime":"String (timestamp)","commandLine":"String","parentProcessName":"String","accountName":"String","isElevated":"true","path":"String","parentProcessCreatedDateTime":"String (timestamp)"}],"azureTenantId":"String","triggers":[{"type":"String","name":"String","value":"String"}],"createdDateTime":"String (timestamp)","vulnerabilityStates":[{"cve":"String","severity":"String","wasRunning":"true"}],"hostStates":[{"isAzureAadRegistered":"true","riskScore":"String","fqdn":"String","isHybridAzureDomainJoined":"true","netBiosName":"String","publicIpAddress":"String","isAzureAadJoined":"true","os":"String","privateIpAddress":"String"}],"lastModifiedDateTime":"String (timestamp)","registryKeyStates":[{"processId":1024,"oldKey":"String","oldValueName":"String","valueType":"@odata.type: microsoft.graph.registryValueType","oldValueData":"String","hive":"@odata.type: microsoft.graph.registryHive","valueData":"String","key":"String","valueName":"String","operation":"@odata.type: microsoft.graph.registryOperation"}],"closedDateTime":"String (timestamp)","azureSubscriptionId":"String"}Script result
The following table lists the value for the script result output when usingtheGet Alert action:
| Script result name | Value |
|---|---|
alert_details | True orFalse |
Get Incident
Use theGet Incident action to obtain details of a security incident usingthe incident ID.
This action doesn't run on Google SecOps entities.
Action inputs
TheGet Incident action requires the following parameters:
| Parameter | Description |
|---|---|
Incident ID | Required The ID of the incident to obtain the details for. |
Action outputs
TheGet Incident action provides the following outputs:
| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |
Output messages
TheGet Incident action can return the following output messages:
| Output message | Message description |
|---|---|
| The action succeeded. |
Error executing action "Get Incident". Reason:ERROR_REASON | The action failed. Check the connection to the server, input parameters, or credentials. |
Script result
The following table lists the value for the script result output when usingtheGet Incident action:
| Script result name | Value |
|---|---|
is_success | True orFalse |
Kill User Session
Use theKill User Session action to invalidate all refresh tokens issued toapplications for a user by resetting thesignInSessionsValidFromDateTime userproperty to the current date and time.
This action runs on all Google SecOps entities.
Action inputs
TheKill User Session action requires the following parameters:
| Parameter | Description |
|---|---|
userPrincipalName| ID | Required The username or the userUnique ID value used in Microsoft Entra ID. |
Action outputs
TheKill User Session action provides the following outputs:
| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Script result | Available |
Script result
The following table lists the value for the script result output when usingtheKill User Session action:
| Script result name | Value |
|---|---|
is_success | True orFalse |
List Alerts
Use theList Alerts action to list available alerts in Microsoft Graph.
This action runs on all Google SecOps entities.
The filtering process happens on the Microsoft Graph API side. For productsthat publish alerts to Microsoft Graph and don't support filtering, MicrosoftGraph adds all alerts to the response as if the alerts have passed the filter.
Action inputs
TheList Alerts action requires the following parameters:
| Parameter | Description |
|---|---|
Filter Key | Optional Specify the key that needs to be used to filter alerts. Note: "Title" option is not supported in the V2 API. |
Filter Logic | Optional The filter logic to apply. The filter logic is based on the The possible values are as follows:
The default value is |
Filter Value | Optional The value to use in the filter. If you select If you select If don't set a value, the filter doesn't apply. The filter logic is based on the |
Max Records To Return | Optional The number of records to return for every action run. The default value is 50. |
Action outputs
TheList Alerts action provides the following outputs:
| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |
JSON result
The following example shows the JSON result output received when using theList Alerts action:
{"id":"ID","azureTenantId":"TENANT_ID","azureSubscriptionId":null,"riskScore":null,"tags":[],"activityGroupName":null,"assignedTo":null,"category":"ImpossibleTravel","closedDateTime":null,"comments":[],"confidence":null,"createdDateTime":"2022-04-29T13:10:59.705Z","description":"Sign-in from an atypical location based on the user's recent sign-ins","detectionIds":[],"eventDateTime":"2022-04-29T11:36:59.1520667Z","feedback":null,"incidentIds":[],"lastEventDateTime":null,"lastModifiedDateTime":"2022-04-30T14:44:43.4742002Z","recommendedActions":[],"severity":"medium","sourceMaterials":[],"status":"newAlert","title":"Atypical travel","vendorInformation":{"provider":"IPC","providerVersion":null,"subProvider":null,"vendor":"Microsoft"},"alertDetections":[],"cloudAppStates":[],"fileStates":[],"hostStates":[],"historyStates":[],"investigationSecurityStates":[],"malwareStates":[],"messageSecurityStates":[],"networkConnections":[],"processes":[],"registryKeyStates":[],"securityResources":[],"triggers":[],"userStates":[{"aadUserId":"b786d3cf-e97d-4511-b61c-0559e9f4da75","accountName":"example.user","domainName":"example.com","emailRole":"unknown","isVpn":null,"logonDateTime":"2022-04-29T11:36:59.1520667Z","logonId":null,"logonIp":"203.0.113.194","logonLocation":"1800 Amphibious Blvd, Mountain View, CA 94045","logonType":null,"onPremisesSecurityIdentifier":null,"riskScore":null,"userAccountType":null,"userPrincipalName":"example.user@example.com"},{"aadUserId":"b786d3cf-e97d-4511-b61c-0559e9f4da75","accountName":"example.user","domainName":"example.com","emailRole":"unknown","isVpn":null,"logonDateTime":"2022-04-29T11:15:00Z","logonId":null,"logonIp":"192.0.2.160","logonLocation":"ES","logonType":null,"onPremisesSecurityIdentifier":null,"riskScore":null,"userAccountType":null,"userPrincipalName":"example.user@example.com"}],"uriClickSecurityStates":[],"vulnerabilityStates":[]}Output messages
TheList Alerts action can return the following output messages:
| Output message | Message description |
|---|---|
| The action succeeded. |
Error executing action "List Alerts". Reason:ERROR_REASON | The action failed. Check the connection to the server, input parameters, or credentials. |
Script result
The following table lists the value for the script result output when usingtheList Alerts action:
| Script result name | Value |
|---|---|
alerts_details | ALERT_DETAILS |
List Incidents
Use theList Incidents action to list the security incidents from MicrosoftGraph based on the criteria provided.
This action doesn't run on Google SecOps entities.
Action inputs
TheList Incidents action requires the following parameters:
| Parameter | Description |
|---|---|
Filter Key | Optional Specify the key that needs to be used to filter alerts. Note: "Title" option is not supported in the V2 API. |
Filter Logic | Optional The filter logic to apply. The filter logic is based on the The possible values are as follows:
The default value is |
Filter Value | Optional The value to use in the filter. If you select If you select If don't set a value, the filter doesn't apply. The filter logic is based on the |
Max Records To Return | Optional The number of records to return for every action run. The default value is 50. |
Action outputs
TheList Incidents action provides the following outputs:
| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |
Output messages
TheList Incidents action can return the following output messages:
| Output message | Message description |
|---|---|
| The action succeeded. |
Error executing action "List Incidents". Reason:ERROR_REASON | The action failed. Check the connection to the server, input parameters, or credentials. |
Script result
The following table lists the value for the script result output when usingtheList Incidents action:
| Script result name | Value |
|---|---|
is_success | True orFalse |
Ping
Use thePing action to test the connectivity to Microsoft Graph.
This action doesn't run on Google SecOps entities.
Action inputs
None.
Action outputs
ThePing action provides the following outputs:
| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Script result | Available |
Script result
The following table lists the value for the script result output when usingthePing action:
| Script result name | Value |
|---|---|
is_success | True orFalse |
Update Alert
Use theUpdate Alert action to update an editable alert property.
This action runs on all Google SecOps entities.
Action inputs
TheUpdate Alert action requires the following parameters:
| Parameter | Description |
|---|---|
Alert ID | Required The ID of the alert to update. |
Assigned To | Optional The name of the analyst the alert is assigned to for triage, investigation, or remediation. |
Closed Date Time | Optional Time at which the alert was closed. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'. Note: this parameter is not supported in the V2 version of API. |
Comments | Optional Analyst comments on the alert (for customer alert management), separated by comma. This method can update the comments field with the following values only: Closed in IPC, Closed in MCAS. Note: in V2 version of API this parameter works as a string and a single comment will be added to the Alert. |
Feedback | Optional Analyst feedback on the alert. Possible values are: unknown, truePositive, falsePositive, benignPositive. Note: in V2 version of API this parameter is mapped to "classification" and has the following possible values: unknown, falsePositive, truePositive, informationalExpectedActivity, unknownFutureValue. |
Status | Optional The alert lifecycle status. The possible values are as follows:
|
Tags | Optional User-definable labels that can be applied to an alert. Separated by comma. Note: this parameter is not supported in the V2 version of API. |
Action outputs
TheUpdate Alert action provides the following outputs:
| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Enrichment table | Not available |
| JSON result | Not available |
| Script result | Available |
Script result
The following table lists the value for the script result output when usingtheUpdate Alert action:
| Script result name | Value |
|---|---|
is_updated | True orFalse |
Connectors
For detailed instructions on how to configure a connector inGoogle SecOps, seeIngest your data(connectors).
Microsoft Graph Security Connector
Use theMicrosoft Graph Security Connector to ingest alerts that arepublished in the Microsoft Graph security API as Google SecOps alerts.The connector periodically connects to the Microsoft Graph security endpoint andpulls a list of incidents that are generated for a specific period.
TheMicrosoft Graph Security Connector requires the following parameters:
| Parameter | Description |
|---|---|
Product Field Name | Required The name of the field where the product name is stored. The default value is |
Event Field Name | Required The field name used to determine the event name (subtype). The default value is |
Script Timeout (Seconds) | Required The timeout limit (in seconds) for the Python process running the current script. The default value is 30 seconds. |
Environment Field Name | Optional The name of the field where the environment name is stored. If the environment field isn't found, the environment is set to |
Pattern | Optional A regular expression pattern to run on the value found in the Use the default value If the regular expression pattern is null or empty, or the environment value is null, the final environment result is |
Client ID | Required The client (application) ID of the Microsoft Entra application to use in the integration. |
Client Secret | Optional The client secret value of the Microsoft Entra application to use in the integration. |
Certificate Path | Optional If you use authentication based on certificates instead of the client secret, enter the path to the certificate on the Google SecOps server. |
Certificate Password | Optional If the authentication certificate that you use is password-protected, specify the password to open the certificate file. |
Azure Active Directory ID | Required The Microsoft Entra ID (tenant ID) value. |
Offset Time In Hours | Required The number of hours before now to fetch alerts from. The default value is 120 hours. |
Fetch Alerts only from | Optional A comma-separated list of providers to pull alerts from Microsoft Graph. If you set the 'Fetch Alerts only from' parameter to Office 365 Security and Compliance, the connector doesn't support multiple values in the Alert Statuses to fetch or Alert Severities to fetch parameters. If 'Use V2 API' is enabled, then this parameter will work with 'serviceSource' property of the alert. |
Alert Statuses to fetch | Required A comma-separated list of alert statuses for the Google SecOps server to retrieve. The possible values are as follows: |
Alert Severities to fetch | Required A comma-separated list of alert severities for the Google SecOps server to retrieve. The possible values are as follows: |
Max Alerts Per Cycle | Optional The maximum number of alerts to process in a one-connector iteration. The default value is 50. |
Proxy Server Address | Optional The address of the proxy server to use. |
Proxy Username | Optional The proxy username to authenticate with. |
Proxy Password | Optional The proxy password to authenticate with. |
Use V2 API | Optional If enabled, the connector will use V2 API endpoints. Note: the structure of the alerts and events will change. Additionally, the 'Fetch Alerts only from' parameter will require different values to be provided. |
Connector rules
The connector doesn't support the dynamic list or blocklist rules.
The connector supports proxies.
Microsoft Graph Office 365 Security and Compliance Connector
Use theMicrosoft Graph Office 365 Security and Compliance Connector toingest the Office 365 Security and Compliance alerts using the Microsoft GraphAPI.
TheMicrosoft Graph Office 365 Security and Compliance Connector requiresthe following parameters:
| Parameter | Description |
|---|---|
Product Field Name | Required The name of the field where the product name is stored. The default value is |
Event Field Name | Required The field name used to determine the event name (subtype). The default value is |
Script Timeout (Seconds) | Required The timeout limit (in seconds) for the Python process running the current script. The default value is 30 seconds. |
Environment Field Name | Optional The name of the field where the environment name is stored. If the environment field isn't found, the environment is set to |
Environment Regex Pattern | Optional A regular expression pattern to run on the value found in the Use the default value If the regular expression pattern is null or empty, or the environment value is null, the final environment result is |
Client ID | Required The client (application) ID of the Microsoft Entra application to use in the integration. |
Client Secret | Optional The client secret value of the Microsoft Entra application to use in the integration. |
Certificate Path | Optional If you use authentication based on certificates instead of the client secret, enter the path to the certificate on the Google SecOps server. |
Certificate Password | Optional If the authentication certificate that you use is password-protected, specify the password to open the certificate file. |
Azure Active Directory ID | Required The Microsoft Entra ID (tenant ID) value. |
Verify SSL | Optional If selected, the integration verifies that the SSL certificate for the connection to the Microsoft Graph server is valid. Selected by default. |
Offset Time In Hours | Required The number of hours before now to fetch alerts. The default value is 120 hours. |
Alert Statuses to fetch | Optional A comma-separated list of alert statuses for the Google SecOps server to retrieve. The possible values are as follows: |
Alert Severities to fetch | Optional A comma-separated list of alert severities for the Google SecOps server to retrieve. The possible values are as follows: |
Max Alerts Per Cycle | Required The maximum number of alerts to process in a one-connector iteration. The default value is 50. |
Proxy Server Address | Optional The address of the proxy server to use. |
Proxy Username | Optional The proxy username to authenticate with. |
Proxy Password | Optional The proxy password to authenticate with. |
Connector rules
The connector doesn't support the dynamic list or blocklist rules.
The connector supports proxies.
Need more help?Get answers from Community members and Google SecOps professionals.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.