Office 365 Management API Government Community Cloud (GCC) Integration Guide
cloud integrations microsoft office 365 gcc azure government
The Office 365 Management API provides auditing information about various user, admin, system, and policy actions and events from Office 365 and Azure Active Directory activity logs. Secureworks® Taegis™ XDR needs authorization from Azure AD and the Office 365 Management API in order to receive your data.
Important
You must turn on Office 365 audit logging for XDR to receive data from it. Audit logging for Office 365 is off by default. For more information, see Turn Office 365 audit log search on or off in the Microsoft docs.
For more information on the Office 365 Management Activity API, see Office 365 Management APIs Overview in the Microsoft docs.
Data Availability and Collection Times ⫘
Alerts are ingested using the Microsoft REST APIs on a polling basis. For information on data availability, see Office 365 and Azure Data Availability.
Data Provided from Integrations ⫘
Antivirus | Auth | CloudAudit | DHCP | DNS | Encrypt | HTTP | Management | Netflow | NIDS | Thirdparty | ||
---|---|---|---|---|---|---|---|---|---|---|---|---|
MS Office 365 | D, V | V | V |
Y = Normalized | D = Out-of-the-Box Detections | V = Vendor-Specific Detections
Note
XDR detectors are not guaranteed to be triggered, even if a data source's logs are normalized to a schema associated with a given detector. However, you can create Custom Alert Rules to generate alerts based on normalized data from a data source.
Register an Application in Azure ⫘
Note
The following steps assume you are logged in as a Tenant Admin.
- Register an application in the Azure portal.
- Name — Any descriptive string
- Supported account types — Accounts in this organizational directory only
Note the following values as they are used to create the integration in XDR:
- Directory (tenant) ID
- Application (client) ID
- Select Application Permissions to configure application permissions.
The following permissions are required:
- ActivityFeed.Read
- ActivityFeed.ReadDlp
- ServiceHealth.Read
-
Click Grant admin consent for <Azure tenant name>.
-
Provide credentials for the application by uploading a certificate.
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 .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
.
Or:
openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
Add Integration in XDR ⫘
- From the XDR left-hand side navigation, select Integrations → Cloud APIs → Add API Integration.
- Select the O365 / Azure card.
- Choose Authorize under Office 365 Government Community Cloud (GCC).
- Enter a name for the integration. This can be any string.
- Enter the Tenant ID and the Application Client ID from Step 1 in Register an application.
- Upload the certificate and its associated private key.
- Select Done to complete the integration.
Add O365 Management API Integrations
Follow-On ⫘
Complete the Link a Partner Process.