如何获取Azure AD/Entra ID中自定义目录角色的成员变更（Delta）

问题描述 #

在Entra ID中创建自定义角色后，调用GET https://graph.microsoft.com/v1.0/directoryRole/delta无法检测到该角色；尝试通过POST https://graph.microsoft.com/v1.0/directoryRoles传入roleTemplateId激活角色时，收到以下错误：

{
  "error": {
    "code": "Request_BadRequest",
    "message": "Could not resolve request to a valid role template. A valid value must be specified for 'displayName' or 'roleTemplateId'.",
    "details": [
      {
        "code": "PropertyRequired",
        "message": "Could not resolve request to a valid role template. A valid value must be specified for 'displayName' or 'roleTemplateId'.",
        "target": "roleTemplateId"
      }
    ],
    "innerError": {
      "date": "2023-11-24T04:18:34",
      "request-id": "c2ff8f89-a856-4e53-b0ec-a6d80c7437fd",
      "client-request-id": "c2ff8f89-a856-4e53-b0ec-a6d80c7437fd"
    }
  }
}

需要实现：检测自定义角色、获取分配给该角色的目录对象的变更（Delta）。

解决方案 #

1. 区分内置角色与自定义角色的API范围 #

directoryRole系列API仅针对内置Entra ID角色，自定义角色属于roleManagement/directory范畴，两者端点不通用。你使用POST /directoryRoles激活自定义角色的方式是错误的，该端点仅用于实例化内置角色模板。

2. 确认自定义角色定义存在 #

先调用以下API验证自定义角色已创建成功：

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions

在返回结果中找到目标自定义角色，记录其id（即roleDefinitionId），此ID为后续操作的核心参数。

3. 创建自定义角色分配（关联目录对象） #

自定义角色无需“激活”，只需完成角色分配即可生效。调用以下API为角色分配用户/组/服务主体：

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments
Content-Type: application/json

{
  "principalId": "<目标用户/组/服务主体的ID>",
  "roleDefinitionId": "<自定义角色的roleDefinitionId>",
  "directoryScopeId": "/" // 全局范围，可替换为特定目录范围ID
}

4. 查询自定义角色及分配的Delta变更 #

• 自定义角色定义的变更（如权限修改）：

  GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions/delta
  

• 自定义角色分配的变更（新增/移除分配对象）：

  GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/delta?$filter=roleDefinitionId eq '<自定义角色的roleDefinitionId>'
  

  通过$filter参数可精准筛选目标自定义角色的分配变更记录。

内容的提问来源于stack exchange，提问作者Taslim Arif