如何通过Microsoft Graph API创建自定义安全属性变更通知订阅及接收通知？

一、创建自定义安全属性的变更通知订阅 #

要通过Microsoft Graph API创建针对用户/组自定义安全属性的变更通知订阅，按以下步骤操作：

1. 配置所需权限 #

确保你的应用已获得Directory.Read.All或Directory.ReadWrite.All应用权限，且已完成管理员同意。

2. 发送订阅创建请求 #

向https://graph.microsoft.com/v1.0/subscriptions发送POST请求，请求体需包含以下关键参数：

• changeType：设为updated（自定义安全属性变更属于资源更新事件）
• notificationUrl：你的公网可访问的Webhook回调地址
• resource：针对用户设为/users，针对组设为/groups
• expirationDateTime：订阅有效期（最长3天，需后续续订）
• clientState：自定义密钥，用于验证通知合法性
• includeResourceData：设为true可在通知中返回变更后的属性数据

请求示例：

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "updated",
  "notificationUrl": "https://your-public-domain.com/webhook-handler",
  "resource": "/users",
  "expirationDateTime": "2024-05-20T18:23:45.9356913Z",
  "clientState": "your-unique-client-secret",
  "includeResourceData": true,
  "additionalData": {
    "securityEnabledOnly": false
  }
}

3. 完成回调地址验证 #

创建订阅时，Graph会向你的notificationUrl发送一个GET请求，携带validationToken参数。你需要立即返回该token作为响应体，状态码设为200，否则订阅创建失败。

二、排查未收到变更通知的问题 #

如果未收到自定义安全属性更新的通知，按以下方向排查：

• 检查订阅状态：调用GET https://graph.microsoft.com/v1.0/subscriptions/{subscription-id}，确认status为enabled。若为disabled，查看failureReason字段获取具体失败原因。
• 验证回调地址可用性：确保回调地址公网可访问，无防火墙/代理拦截，且能正常接收POST请求（可通过工具模拟测试）。
• 确认属性变更触发条件：只有当自定义安全属性的值实际发生变化（如从无到有、值修改）时才会触发通知，重复设置相同值不会触发。
• 核对权限配置：确认应用已获得正确的权限且完成管理员同意，权限不足会导致无法检测到属性变更。
• 检查订阅有效期：若订阅已过期，需重新创建订阅并设置新的expirationDateTime。
• 调整additionalData参数：若securityEnabledOnly设为true，仅安全启用的用户/组变更会触发通知，若需覆盖所有用户/组，需设为false。
• 查看日志记录：在Azure AD应用注册的审计日志或应用日志中，查找通知发送失败的记录，定位具体问题。

内容的提问来源于stack exchange，提问作者David Jones