Skip to content

Microsoft Graph Security API v2 Integration Guide🔗

The following instructions are for configuring an integration of Microsoft Graph Security API v2 logs to facilitate ingestion into Secureworks® Taegis™ XDR. For more information, see the Microsoft Graph Security API Overview.

Important

These instructions are for the Microsoft Graph Security API v2 integration, which uses Alerts v2 (Alerts and incidents). Microsoft has deprecated the v1 version and will discontinue it by April 2026. We recommend that you integrate this version.

Important

If you currently use the Graph Security API v1 integration, you should review the coverage differences between v1 and v2 to ensure that any functionality available in v1 but not in v2 is accounted for, as the APIs are not functionally equivalent.

Known Coverage Gaps🔗

We have identified the following areas where the legacy integration provides more comprehensive data than v2:

  • Entra Identity Protection: The legacy integration provides more extensive data coverage than v2. To address this gap, customers may consider using the Microsoft Risk Detections integration as a supplementary data source.
  • O365 Security and Compliance: The legacy integration offers more detailed information than v2. For broader coverage in this area, customers may consider implementing the Microsoft O365 Management API integration alongside v2.

Additional Considerations🔗

We do not maintain a comprehensive list of all provider states or coverage differences with v2, as Microsoft’s schema and support model are subject to frequent change.

For specific questions regarding provider coverage or functionality differences, customers should consult Microsoft directly as the API provider.

Security Alerts from Graph Security API v2 Endpoint🔗

Microsoft has implemented security analysis across many different products. XDR retrieves those Microsoft alerts in real time and presents them in XDR as detections.

These alerts include those from:

  • Microsoft Entra ID Protection
  • Microsoft 365 Defender
  • Microsoft Defender for Cloud Apps
  • Microsoft Defender for Endpoint
  • Microsoft Defender for Identity
  • Microsoft Defender for Office 365
  • Microsoft Purview Data Loss Prevention
  • Microsoft Purview Insider Risk Management

Note

Microsoft Defender for Identity alerts are available via the Microsoft Defender for Cloud Apps integration. This means you will get Microsoft Defender for Identity alerts only if you have joined Unified SecOps and connected Microsoft Defender for Identity to Microsoft Defender for Cloud Apps. Learn more about how to integrate Microsoft Defender for Identity and Microsoft Defender for Cloud Apps.

Alerts are ingested using the Microsoft REST APIs on a polling basis, with new data being requested every minute. For information on data availability, see Office 365 and Azure Data Availability.

Note

XDR relays alerts provided by the Graph Security API. This does not include the raw telemetry needed to provide enrichment, context, and propriety analytics. Alert-only integration does provide single pane of glass views but does not include the information required for deep analysis. Where possible, it is preferred to add integrations where supporting telemetry for alerts is available.

The availability of these security products depends on which Microsoft subscriptions and licensing you have and what you have authorized XDR to access. For more information, see Use the Microsoft Graph security API.

Note

Some alerts originating from Office 365 may appear in data from both the O365 Management and MS Graph Security.

Data Provided from Integration🔗

Normalized Data Out-of-the-Box Detections Vendor-Specific Detections
MS Graph Security API v2     Antivirus, CloudAudit, Email, Thirdparty

Microsoft Graph Security API v2 Integration Instructions🔗

Register an Application in Azure🔗

  1. Register an application in the Azure portal.

    • Name — Any descriptive string
    • Supported account types — Accounts in this organizational directory only

    Note

    Record the following values as they are used to create the integration in XDR:

    • Directory (tenant) ID
    • Application (client) ID

  2. Configure application permissions. The following permissions are required:

    • SecurityAlert.Read.All (application permission)
    • SecurityIncident.Read.All (application permission)
    • User.Read (permission automatically delegated to MS Graph)

    API Permissions

  3. Click Grant admin consent for <Azure tenant name>.

  4. Provide credentials for the application by uploading a certificate.

Important

Certificates will expire and need to be renewed both with Microsoft Entra ID and with XDR to allow for continued functionality before their expiration date.

Important

XDR supports ONLY the Privacy-Enhanced Mail (PEM) format. More information on the PEM format can be found in RFC 7468.

Encrypted keys and client secrets are NOT supported.

Note

Self-signed certificates are supported.

Use one of the following commands to generate a self-signed PEM (.pem extension) certificate using PowerShell or OpenSSL:

# Prompt user for input

$certname = Read-Host -Prompt "Enter certificate name"
$keyname = Read-Host -Prompt "Enter key name"
$mypwd = Read-Host -Prompt "Enter password" -AsSecureString
$location = Read-Host -Prompt "Enter location"
$cert = New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
Export-PfxCertificate -Cert $cert -FilePath "$location\$certname.pfx" -Password $mypwd
Install-Module -Name PSPKI -Scope CurrentUser
Import-Module -Name PSPKI
Convert-PfxToPem -InputFile "$location\$certname.pfx" -Outputfile "$location\$certname.pem"
# Read the PEM file content

$pemContent = Get-Content "$location\$certname.pem" -Raw
# Extract private key and certificate

$privateKey = $pemContent -replace "(?ms).*?(-----BEGIN PRIVATE KEY-----.+?-----END PRIVATE KEY-----).*", '$1'
$certificate = $pemContent -replace "(?ms).*?(-----BEGIN CERTIFICATE-----.+?-----END CERTIFICATE-----).*", '$1'
# Save private key and certificate to separate files

$privateKey | Set-Content "$location\$keyname.pem"
$certificate | Set-Content "$location\$certname.pem"
Write-Host "Files located at: $location"
pause

Note

Copy and paste the preceding code into a text file, save the file with a .ps1 extension (e.g., CertGen.ps1), and run the script using PowerShell.

Note

Depending on the PowerShell version being used, you may need to replace -Subject with -SubjectName if there are any errors with -Subject.

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem

Add Integration in XDR🔗

  1. From the Taegis Menu, go to Integrations → Cloud APIs.

  2. Click Add an Integration from the top of the page.

    Add an Integration

  3. From the Optimized tab, click Office 365/Azure.

    Create the Integration

  4. Choose Set Up under Graph Security API v2.

  5. Enter a name for the integration. This can be any string.
  6. Enter the Tenant ID and the Application Client ID from Step 1 in the Register an Application in Azure section.
  7. Upload the certificate and its associated private key.
  8. Select Done to complete the integration with XDR.

Advanced Search Using the Query Language🔗

Distinguishing Graph Security v1 and v2 Events🔗

To search for all Graph Security v2 events:

where ingest.product.name = 'GRAPH_ALERTS' and ingest.product.version = 'v2'

To search for all Graph Security v1 events:

where ingest.product.name = 'GRAPH_ALERTS' and ingest.product.version = 'Legacy'