Microsoft Graph Security connector setup

Polls Microsoft Defender alerts and incidents plus Microsoft Secure Score posture from Microsoft Graph. The connector is read-only and emits raw Graph objects.

What you need first

Requirement	Details
Microsoft tenant	Global / commercial, GCC High, or DoD
Entra administrator	Access to register an application and grant tenant-wide admin consent
Product licenses	Microsoft Defender XDR for incidents; the relevant Defender and Microsoft 365 products for alerts and Secure Score data
Application details	Directory (tenant) ID, application (client) ID, and client secret

Microsoft Entra activity, sign-in, and identity-risk logs are intentionally excluded. Route those sources to Event Hubs and configure the Azure Event Hubs connector.

---

1. Register a Microsoft Entra application

1. Sign in to the Microsoft Entra admin center.
2. Go to Applications → App registrations → New registration.
3. Name the app (for example, Perpetual Microsoft Graph Security).
4. Choose Accounts in this organizational directory only.
5. Click Register. No redirect URI is required.
6. Copy the Application (client) ID and Directory (tenant) ID from Overview.

Add Microsoft Graph application permissions

1. Open API permissions → Add a permission.
2. Choose Microsoft Graph → Application permissions. Do not choose delegated permissions.
3. Add only the permissions required by the streams you plan to enable:

Perpetual setting	Microsoft Graph API	Application permission	Licensing / availability
Defender alerts	/v1.0/security/alerts_v2	SecurityAlert.Read.All	Requires the relevant Microsoft Defender products to produce alerts.
Defender incidents	/v1.0/security/incidents?$expand=alerts	SecurityIncident.Read.All	Requires Microsoft Defender XDR. Each raw incident includes nested alerts.
Secure Scores	/v1.0/security/secureScores	SecurityEvents.Read.All	Results depend on the Microsoft services licensed and enabled in the tenant.
Secure Score control profiles	/v1.0/security/secureScoreControlProfiles	SecurityEvents.Read.All	Results depend on the Microsoft services licensed and enabled in the tenant.

4. Click Grant admin consent for [your organization].

Do not add any ReadWrite permission. The connector performs only GET requests.

Create a client secret

1. Go to Certificates & secrets → Client secrets → New client secret.
2. Add a description and expiration that match your organization's rotation policy.
3. Copy the secret value immediately. Microsoft displays it only once.

---

2. Perpetual credential

1. Log in to Perpetual. Open Settings from the user/org control at the bottom left of the sidebar (click your name → Settings), then go to Credentials → New Credential.
2. Choose OAuth 2.0 Client Credentials.
3. Fill in:

Field	Value
Name	Unique identifier using letters, digits, and underscores only (for example, microsoft_graph_security).
Allowed URL patterns	Use the value for your Microsoft cloud from the table below.
Token URL	Use the URL for your Microsoft cloud and replace <tenant-id> with the Directory (tenant) ID from step 1.
Client ID	Application (client) ID from step 1.
Client Secret	Client secret value from step 1.
Scopes	Use the scope for your Microsoft cloud from the table below.

Microsoft cloud	Allowed URL patterns	Token URL	Scopes
Global / commercial	*.microsoft.com, *.microsoftonline.com	https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token	https://graph.microsoft.com/.default
US Government L4 / GCC High	*.microsoft.us, *.microsoftonline.us	https://login.microsoftonline.us/<tenant-id>/oauth2/v2.0/token	https://graph.microsoft.us/.default
US Government L5 / DoD	*.microsoft.us, *.microsoftonline.us	https://login.microsoftonline.us/<tenant-id>/oauth2/v2.0/token	https://dod-graph.microsoft.us/.default

4. Save the credential.

Microsoft Graph operated by 21Vianet in China is not supported.

---

3. Create the Microsoft Graph Security connector

1. Go to Datasets → Connectors → Create Connector.
2. Select Microsoft Graph Security.
3. Connector name: enter a unique identifier using letters, numbers, and underscores.
4. Configure:
   • Microsoft Graph API access: select the OAuth credential from step 2.
   • Poll interval (minutes): leave the default 5 unless you have a specific reason to change it.
   • Microsoft cloud: select the cloud matching the credential and tenant:
     • global — Global / commercial
     • usGovernmentL4 — US Government L4 / GCC High
     • usGovernmentL5 — US Government L5 / DoD
   • Enable at least one stream:

Perpetual setting	Raw dataset	Notes
Defender alerts	microsoft.graph.alerts	Individual Defender alert objects.
Defender incidents	microsoft.graph.incidents	Correlated incidents with nested alerts.
Secure Scores	microsoft.graph.secureScores	Daily Secure Score records.
Secure Score control profiles	microsoft.graph.secureScoreControlProfiles	Current control-profile snapshots.

5. Optionally check Deploy to schedule the connector immediately after save.
6. Save.

The first run backfills roughly the last 24 hours for alerts, incidents, and Secure Score. Secure Score control profiles take a complete current-state snapshot.

Because polling state is cloud-specific, create a new connector instead of changing Microsoft cloud after collection starts.

If both alerts and incidents are enabled, alert content can appear once as an alert record and again inside an expanded incident. This intentional overlap preserves the raw API responses and Microsoft's incident correlation.

---

Polling behavior

• Recommended schedule: every five minutes.
• Initial lookback for alerts, incidents, and Secure Score: 24 hours.
• Alerts and incidents: each completed watermark is re-read with a 15-minute overlap. The connector stores exact id plus lastUpdateDateTime pairs for that overlap, suppresses an identical or older version, and emits the same ID again when Microsoft reports a newer version.
• Secure Score: each poll rechecks the previous two days and stores exact score IDs, covering late publication without re-emitting the same daily score.
• Catch-up: alert and incident watermarks advance by at most one hour per frozen query window; Secure Score advances by at most one day. These bounds keep the exact ID cache limited to a known time range even during a long backfill.
• Delivery: inclusive time boundaries and at-least-once transport semantics. The state-backed ID cache prevents ordinary overlap and expired-page restart duplicates, but a reset or loss of connector state can replay records.
• Late-arrival limit: an alert or incident first exposed more than 15 minutes behind the completed watermark is outside the polling overlap. For Microsoft data sources that support Event Hubs, use the Event Hubs ingestion path instead of timestamp polling.
• Pagination: one page per enabled stream per round so a busy stream cannot starve the others.
• Incidents: always requested with $expand=alerts and emitted as one raw incident object.
• Secure Score: Microsoft publishes a daily scoring record; the connector treats each record as time-based event data.
• Secure Score control profiles: full refresh no more than once per UTC day. IDs are retained while a paginated snapshot is active so an expired page restart does not repeat profiles within that snapshot.
• Disabled streams retain their saved state. Re-enabling a stream resumes its previous position.

Troubleshooting

401 Unauthorized

• Confirm the credential uses the tenant and login host for the selected cloud.
• Confirm the .default scope uses the selected Graph host, not the Office 365 Management Activity API.
• Check that the client secret has not expired and that the access token audience matches the selected Graph host.

403 Forbidden

• Compare enabled toggles with the permission matrix and confirm each permission is an Application permission.
• Grant admin consent after changing permissions.
• Defender alerts and incidents require the underlying Defender products and licenses. Permission consent alone does not produce data.

Empty datasets

• Confirm the selected feature has produced records within Microsoft's retention period and the connector's time window.
• Defender alerts and incidents only exist for enabled Defender products.
• Secure Score content depends on the services enabled and licensed in the tenant.

429 or transient 5xx

The connector honors Retry-After and otherwise retries with jittered exponential backoff, up to three attempts when the Lambda deadline permits. Persistent throttling isolates the affected stream and returns a partial run when another stream made progress.

Choosing the Microsoft ingestion path

The Microsoft data surfaces use different APIs and delivery models and can run independently:

• Microsoft Graph Security supplies Defender alert and correlated incident objects plus Secure Score posture.
• Azure Event Hubs is the supported path for Microsoft Entra audits, sign-ins, identity-risk logs, and Defender XDR Advanced Hunting event streams. Event Hub records are not byte-for-byte Microsoft Graph objects.
• Office 365 Audit remains necessary for unified audit activity from Exchange, SharePoint, OneDrive, Teams, Purview/DLP, and other Microsoft 365 workloads.

Defender XDR Event Streaming sends Advanced Hunting tables such as AlertInfo, AlertEvidence, device, email, identity, and cloud-app events. Those tables supplement rather than replace Graph alerts and incidents; Event Streaming does not provide the same correlated incident resource.

This connector does not include Entra activity or identity risk, Advanced Hunting, remediation or other write operations, threat-intelligence catalogs, Defender inventory, China cloud endpoints, or Microsoft Graph beta APIs.

Microsoft references

• Microsoft Graph security API overview
• Microsoft Secure Score resource
• Microsoft Entra logs available for streaming
• Microsoft Defender XDR streaming API
• Microsoft Graph national cloud deployments
• Microsoft Graph throttling guidance