咨询Microsoft Entra自定义目录角色Graph API正确的Payload结构

基础请求信息 #

• 请求方法：POST
• 端点：https://graph.microsoft.com/v1.0/directoryRoles
• 权限要求：需Directory.ReadWrite.All应用权限或Directory.AccessAsUser.All委托权限（均需管理员同意）

正确Payload示例 #

{
  "displayName": "自定义应用管理员",
  "description": "负责管理指定企业应用的专属管理员角色",
  "rolePermissions": [
    {
      "allowedResourceActions": [
        "microsoft.directory/applications/basic/read",
        "microsoft.directory/applications/standard/update",
        "microsoft.directory/applications/credentials/update"
      ],
      "condition": null
    }
  ]
}

关键字段说明 #

• displayName：角色的显示名称，必须唯一，长度限制1-64字符
• description：角色的功能描述，长度限制1-1024字符
• rolePermissions：数组类型，每个元素对应一组权限配置
  • allowedResourceActions：字符串数组，填入Microsoft Entra支持的合法权限动作（可参考内置角色权限列表获取有效值）
  • condition：可选字段，用于配置基于属性的访问控制规则，无需时设为null

常见Payload错误排查 #

• 错误：The displayName is already in use
  • 原因：角色名称与现有内置/自定义角色重复，需修改displayName
• 错误：Invalid allowedResourceActions value
  • 原因：权限动作名称拼写错误，需核对确保是官方支持的权限值
• 错误：Missing required field
  • 原因：遗漏displayName、description或rolePermissions等必填字段，需补充完整

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