Listen to this Post
Introduction:
Microsoft Defender for Identity has elevated its automation capabilities with a powerful new Graph API, enabling security teams to programmatically initiate critical remediation actions against compromised accounts. This integration is a game-changer for orchestrating incident response, allowing for seamless integration with SOAR platforms and custom scripts to contain threats at machine speed, drastically reducing mean time to response (MTTR) for identity-based attacks.
Learning Objectives:
- Understand the core remediation actions available through the new Defender for Identity Graph API.
- Learn how to construct and authenticate API calls to Microsoft Graph for security automation.
- Integrate these API calls into practical scripts for automated incident response playbooks.
You Should Know:
1. API Endpoint and Authentication Primer
Before invoking any actions, you must authenticate and obtain an access token. This is typically done using a registered Azure AD App with the appropriate `IdentityRiskyUser.ReadWrite.All` permission.
Request an OAuth2 access token using a client credential flow (service principal) curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ -d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=https://graph.microsoft.com/.default&grant_type=client_credentials' \ 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
This `curl` command requests an access token from the Microsoft Identity Platform. Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, and `YOUR_TENANT_ID` with your Azure AD application’s details. The token returned in the response must be included in the `Authorization` header of all subsequent API calls to Microsoft Graph (Authorization: Bearer <token>).
2. Identifying Risky Users
The first step in any remediation workflow is to identify the compromised account. The `identityRiskEvents` endpoint can be queried to fetch high-risk users.
Fetch recent high-risk users (filtering and querying is highly recommended) curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ "https://graph.microsoft.com/v1.0/identityProtection/riskDetections?`$filter=riskLevel eq 'high'"
This command queries the Graph API for risk detections with a ‘high’ risk level. The response is a JSON object containing an array of detections, each with a unique `id` and associated userId. This `userId` is crucial for initiating remediation actions on the correct account.
3. Initiating a Force Password Reset
One of the most immediate actions to contain a credential compromise is to force a password reset. This invalidates the current credentials.
Force a password reset for a specific user ID
curl -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"action":"forcePasswordReset"}' \
"https://graph.microsoft.com/v1.0/identityProtection/riskyUsers/YOUR_USER_ID/invokeAction"
This API call targets a specific risky user (YOUR_USER_ID obtained from the previous detection call) and invokes the `forcePasswordReset` action. The API will respond with a status code; a `204 No Content` typically indicates success.
4. Revoking All Active Sessions
To immediately terminate an attacker’s active session, use the `revokeAllSessions` action. This signs the user out from all applications and browsers across all devices.
Revoke all active sessions for a compromised user
curl -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"action":"revokeAllSessions"}' \
"https://graph.microsoft.com/v1.0/identityProtection/riskyUsers/YOUR_USER_ID/invokeAction"
This is a critical containment step that disrupts an ongoing attack. It’s important to note that the user will need to re-authenticate to access any resources afterward.
5. Disabling a Compromised Account
For the most severe cases, where you need to completely isolate the threat, disabling the account is the definitive action.
Disable a user account
curl -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"action":"disable"}' \
"https://graph.microsoft.com/v1.0/identityProtection/riskyUsers/YOUR_USER_ID/invokeAction"
This action will prevent the user from signing in entirely. It should be used when you have high confidence the account is fully compromised and other remediation steps are insufficient. Re-enabling requires the `enable` action.
6. Marking a User as Compromised
You can also proactively mark a user as compromised based on internal telemetry or threat intelligence, triggering other automated responses in your ecosystem.
Manually mark a user as compromised
curl -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"action":"markUserAsCompromised","compromisedDateTime":"2024-08-19T12:00:00Z"}' \
"https://graph.microsoft.com/v1.0/identityProtection/riskyUsers/YOUR_USER_ID/invokeAction"
This command adds a manual risk detection, which can be used to kick off automated playbooks even if Microsoft’s algorithms haven’t yet flagged the user.
7. Integrating into a Python SOAR Script
Automation is key. Here’s a basic Python script skeleton that ties detection to remediation.
import requests
import json
<ol>
<li>Authenticate and get token
tenant_id = "YOUR_TENANT"
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_SECRET"
auth_url = f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
auth_data = {
'client_id': client_id,
'client_secret': client_secret,
'scope': 'https://graph.microsoft.com/.default',
'grant_type': 'client_credentials'
}
auth_response = requests.post(auth_url, data=auth_data)
token = auth_response.json().get('access_token')</p></li>
<li><p>Fetch high-risk users
graph_url = "https://graph.microsoft.com/v1.0/identityProtection/riskDetections"
headers = {'Authorization': f'Bearer {token}'}
params = {'$filter': "riskLevel eq 'high'"}
response = requests.get(graph_url, headers=headers, params=params)
risky_users = response.json().get('value', [])</p></li>
<li><p>Remediate for each user
for user in risky_users:
user_id = user['userId']
remediate_url = f"https://graph.microsoft.com/v1.0/identityProtection/riskyUsers/{user_id}/invokeAction"
payload = {"action": "forcePasswordReset"} Choose appropriate action
remediate_response = requests.post(remediate_url, headers=headers, json=payload)
print(f"Remediation for {user_id}: {remediate_response.status_code}")
This script demonstrates a fundamental automated playbook: it authenticates, fetches a list of high-risk users, and automatically forces a password reset for each one. This can be expanded with error handling, logging, and logic to choose different actions based on the specific risk details.
What Undercode Say:
- The shift towards Graph API-driven remediation signifies a major leap in closing the loop between detection and response, moving from manual intervention to true, programmable SOAR.
- Security teams must now prioritize API integration skills and service principal management alongside traditional security knowledge to fully leverage modern XDR platforms like Microsoft Defender.
This API is not just a new feature; it’s a fundamental shift in operational philosophy. It demands that security professionals become proficient in automation and scripting. The ability to instantly contain a threat the moment it’s detected, without waiting for a human to click a button, is a powerful force multiplier. It reduces the attacker’s dwell time from minutes to milliseconds. However, this power comes with responsibility. Automating disruptive actions like account disablement requires extremely high confidence in the underlying detection signals to avoid causing business disruption. Organizations must develop robust playbooks that combine multiple telemetry sources before triggering the most severe actions automatically.
Prediction:
The release of this API will accelerate the adoption of fully automated identity threat response playbooks, making manual remediation a legacy practice within two years. This will force a convergence of security and DevOps roles, creating a high demand for “Security Automation Engineers” who can code against security APIs. We will see a corresponding evolution in attacker tactics, focusing on persistence mechanisms that can survive automated account resets and disabling, such as deploying stealthier backdoors or targeting service accounts with different security policies.
🎯Let’s Practice For Free:
IT/Security Reporter URL:
Reported By: Markolauren Defenderforidentity – Hackers Feeds
Extra Hub: Undercode MoN
Basic Verification: Pass ✅
