通过

使用权利管理 API 管理对资源的访问

  • 项目

Microsoft Entra权利管理允许你为组织中的员工和来宾大规模管理资源访问。 本教程介绍如何使用权利管理 API 创建内部用户可以请求的资源包。 API 提供了在Microsoft Entra 管理中心创建自定义应用的编程替代方法。

在本教程中，你将了解如何：

  • 创建用户可以自行请求的访问包。
  • 将组资源分配给访问包。
  • 请求访问包。

先决条件

若要完成本教程，需要：

  • 具有 Microsoft Entra ID P2 或 Microsoft Entra ID 治理 许可证的Microsoft Entra租户。
  • 租户中的测试来宾帐户和测试安全组。 安全组是本教程中的资源。 确保你是组的所有者或分配了组管理员角色。 在本教程中：
    • 用户具有 ID 007d1c7e-7fa8-4e33-b678-5e437acdcddc ，名为 Requestor1。
    • 该组具有 f4892fac-e81c-4712-bdf2-a4450008a4b0 ID，其中包含“Marketing group”说明和“Marketing resources”显示名称。
  • 使用至少具有标识治理管理员角色的帐户登录的 API 客户端（例如 Graph 资源管理器 ）
  • 委托的权限：
    • User.ReadWrite.All
    • Group.ReadWrite.All
    • EntitlementManagement.ReadWrite.All
  • [可选]匿名浏览器窗口。 稍后在本教程中登录。

注意

本教程中的一些步骤使用 beta 终结点。

步骤 1：将资源添加到目录并创建访问包

访问包是团队或项目所需的资源捆绑包，由策略管理。 访问包在称为目录的容器中定义。 目录可以引用访问包中使用的资源，例如组、应用和网站。 权利管理包括默认 General 目录。

在此步骤中，将在常规目录中创建 市场营销活动 访问包。

步骤 1.1：获取常规目录的标识符

获取 常规 目录的 ID。

请求

GET https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/catalogs?$filter=(displayName eq 'General')

响应

注意：为了提高可读性，可能缩短了此处显示的响应对象。

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/catalogs",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/entitlementManagement/catalogs?$select=catalogType,createdDateTime",
    "value": [
        {
            "id": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
            "displayName": "General",
            "description": "Built-in catalog.",
            "catalogType": "serviceDefault",
            "state": "published",
            "isExternallyVisible": true,
            "createdDateTime": "2023-04-13T14:43:19.44Z",
            "modifiedDateTime": "2023-04-13T14:43:19.44Z"
        }
    ]
}

步骤 1.2：将组添加到目录

在此步骤中，将“市场营销资源”组作为资源添加到 常规 目录。

如果你不是 originId 中引用的组的所有者，或者未分配组管理员角色，则此请求会失败并显示 403 Forbidden 错误代码。

请求

POST https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/resourceRequests
Content-type: application/json

{
  "catalogId":"cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
  "requestType": "AdminAdd",
  "justification": "",
  "accessPackageResource": {
    "resourceType": "AadGroup",
    "originId": "e93e24d1-2b65-4a6c-a1dd-654a12225487",
    "originSystem": "AadGroup"
  }
}

响应

在此响应中， ID 表示组的 ID 作为常规目录中的资源。 此 ID 不是组 ID。 记录此 ID。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/resourceRequests/$entity",
    "id": "44e521e0-fb6b-4d5e-a282-e7e68dc59493",
    "requestType": "AdminAdd",
    "requestState": "Delivered",
    "requestStatus": "Fulfilled",
    "catalogId": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
    "executeImmediately": false,
    "justification": "",
    "expirationDateTime": null
}

步骤 1.3：获取目录资源

在此步骤中，检索与添加到常规目录的组资源的 ID 匹配的资源的详细信息。

请求

GET https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/catalogs/cec5d6ab-c75d-47c0-9c1c-92e89f66e384/resources?$filter=originId eq 'e93e24d1-2b65-4a6c-a1dd-654a12225487'

响应

注意：为了提高可读性，可能缩短了此处显示的响应对象。

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/catalogs('cec5d6ab-c75d-47c0-9c1c-92e89f66e384')/resources",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/entitlementManagement/catalogs('<guid>')/resources?$select=attributes,createdDateTime",
  "value": [
    {
      "id": "4a1e21c5-8a76-4578-acb1-641160e076e8",
      "displayName": "Marketing resources",
      "description": "Marketing group",
      "originId": "e93e24d1-2b65-4a6c-a1dd-654a12225487",
      "originSystem": "AadGroup",
      "createdDateTime": "2024-03-26T09:44:50.527Z",
      "attributes": []
    }
  ]
}

步骤 1.4：获取资源角色

访问包将用户分配到资源的角色。 组的典型角色是 角色 Member 。 其他资源（如 SharePoint Online 网站和应用程序）可能具有许多角色。 访问包中使用的组的典型角色是 Member 角色。 在本教程后面部分，需要成员角色才能将资源角色添加到访问包。

在请求中，使用目录的 ID 和记录的目录中组资源的 ID ，以获取成员资源角色的 originId 。 记录 originId 属性的值，以便稍后在本教程中使用。

请求

GET https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/catalogs/ede67938-cda7-4127-a9ca-7c7bf86a19b7/resourceRoles?$filter=(originSystem eq 'AadGroup' and displayName eq 'Member' and resource/id eq '274a1e21c5-8a76-4578-acb1-641160e076e')&$expand=resource

响应

由于按 originId、显示名称和资源 ID 进行筛选，如果成功，则返回一个值，该值表示该组的“成员”角色。 如果未返回任何角色，检查目录和访问包资源的 ID 值。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/catalogs('ede67938-cda7-4127-a9ca-7c7bf86a19b7')/resourceRoles(resource())",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/entitlementManagement/catalogs('<guid>')/resourceRoles?$select=description,displayName",
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "displayName": "Member",
            "description": null,
            "originSystem": "AadGroup",
            "originId": "Member_e93e24d1-2b65-4a6c-a1dd-654a12225487",
            "resource@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/catalogs('ede67938-cda7-4127-a9ca-7c7bf86a19b7')/resourceRoles('00000000-0000-0000-0000-000000000000')/resource/$entity",
            "resource": {
                "id": "ec09e90e-e021-4599-a8c3-bce77c2b2000",
                "displayName": "Marketing resources",
                "description": "Marketing group",
                "originId": "e93e24d1-2b65-4a6c-a1dd-654a12225487",
                "originSystem": "AadGroup",
                "createdDateTime": "2023-04-13T14:43:21.43Z",
                "attributes": []
            }
        }
    ]
}

步骤 1.5：创建访问包

现在，你已有一个包含组资源的目录，并且想要在访问包中使用组成员的资源角色。 下一步是创建访问包。 获取访问包后，可以向其添加资源角色，并为用户如何请求访问该资源角色创建策略。 使用前面记录的目录的 ID 创建访问包。 记录访问包的 ID ，以便稍后在本教程中使用。

请求

POST https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages
Content-type: application/json

{
  "catalogId": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
  "displayName": "Marketing Campaign",
  "description": "Access to resources for the campaign"
}

响应

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/accessPackages/$entity",
    "id": "88203d16-0e31-41d4-87b2-dd402f1435e9",
    "catalogId": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
    "displayName": "Marketing Campaign",
    "description": "Access to resources for the campaign",
    "isHidden": false,
    "isRoleScopesVisible": false,
    "createdBy": "admin@contoso.com",
    "createdDateTime": "2024-03-26T17:36:45.411033Z",
    "modifiedBy": "admin@contoso.com",
    "modifiedDateTime": "2024-03-26T17:36:45.411033Z"
}

步骤 1.6：向访问包添加资源角色

请求

POST https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/88203d16-0e31-41d4-87b2-dd402f1435e9/accessPackageResourceRoleScopes
Content-type: application/json

{
  "role": {
    "originId":"Member_f4892fac-e81c-4712-bdf2-a4450008a4b0",
    "displayName":"Member",
    "originSystem":"AadGroup",
    "resource": {
      "id":"4a1e21c5-8a76-4578-acb1-641160e076e8",
      "resourceType":"Security Group",
      "originId":"f4892fac-e81c-4712-bdf2-a4450008a4b0",
      "originSystem":"AadGroup"
    }
  },
  "scope": {
    "originId":"f4892fac-e81c-4712-bdf2-a4450008a4b0",
    "originSystem":"AadGroup"
  }
}

响应

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/accessPackages('88203d16-0e31-41d4-87b2-dd402f1435e9')/accessPackageResourceRoleScopes/$entity",
  "id": "e081321b-2802-4834-a6ca-6f598ce3cdf7_6dbd2209-9d14-4c76-b92b-fcb00e835fe1",
  "createdDateTime": "2024-03-26T19:56:00.6320729Z",
}

访问包现在具有一个资源角色，即组成员身份。 该角色分配给具有访问包的任何用户。

步骤 1.7：创建访问包策略

创建访问包并添加了资源和角色后，可以通过创建访问包策略来确定谁可以访问它。 在本教程中，启用创建的 Requestor1 帐户，以请求访问包中的资源。 对于此任务，需要以下值：

  • accessPackageId 属性值的访问包的 ID
  • allowedRequestors 中 id 属性值的 Requestor1 用户帐户的 id

durationInDays 属性的值使 Requestor1 帐户能够访问访问包中的资源长达 30 天。 记录返回的 id 属性的值，以便稍后在本教程中使用。

请求

POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies
Content-type: application/json

{
  "accessPackageId": "88203d16-0e31-41d4-87b2-dd402f1435e9",
  "displayName": "Specific users",
  "description": "Specific users can request assignment",
  "accessReviewSettings": null,
  "durationInDays": 30,
  "requestorSettings": {
    "scopeType": "SpecificDirectorySubjects",
    "acceptRequests": true,
    "allowedRequestors": [
       {
         "@odata.type": "#microsoft.graph.singleUser",
         "isBackup": false,
         "id": "007d1c7e-7fa8-4e33-b678-5e437acdcddc",
         "description": "Requestor1"
       }
    ]
  },
  "requestApprovalSettings": {
    "isApprovalRequired": false,
    "isApprovalRequiredForExtension": false,
    "isRequestorJustificationRequired": false,
    "approvalMode": "NoApproval",
    "approvalStages": []
  }
}

响应

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignmentPolicies/$entity",
  "id": "db440482-1210-4a60-9b55-3ac7a72f63ba",
  "accessPackageId": "88203d16-0e31-41d4-87b2-dd402f1435e9",
  "displayName": "Specific users",
  "description": "Specific users can request assignment",
  "canExtend": false,
  "durationInDays": 30,
  "expirationDateTime": null,
  "createdBy": "admin@contoso.com",
  "createdDateTime": "2020-06-29T19:47:44.7399675Z",
  "modifiedBy": "admin@contoso.com",
  "modifiedDateTime": "2020-06-29T19:47:44.7555489Z",
  "accessReviewSettings": null,
  "requestorSettings": {
    "scopeType": "SpecificDirectorySubjects",
    "acceptRequests": true,
    "allowedRequestors": [
      {
        "@odata.type": "#microsoft.graph.singleUser",
        "isBackup": false,
        "id": "007d1c7e-7fa8-4e33-b678-5e437acdcddc",
        "description": "Requestor1"
      }
    ]
  },
  "requestApprovalSettings": {
    "isApprovalRequired": false,
    "isApprovalRequiredForExtension": false,
    "isRequestorJustificationRequired": false,
    "approvalMode": "NoApproval",
    "approvalStages": []
  }
}

步骤 2：请求访问权限

在此步骤中， Requestor1 用户帐户请求访问访问包中的资源。

若要请求访问包，需要提供以下值：

  • 为 targetId 属性的值创建的 Requestor1 用户帐户的 ID
  • assignmentPolicyId 属性的值的分配策略的 ID
  • accessPackageId 属性值的访问包的 ID

在响应中，状态为 Accepted ，状态为 Submitted。 记录返回的 id 属性的值，检查稍后请求的状态。

打开新的匿名浏览器会话，以 Requestor1 身份登录，这样就不会中断当前管理员会话。 或者，注销 Graph 资源管理器，以 Requestor1 身份登录。

请求

POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentRequests
Content-type: application/json

{
  "requestType": "UserAdd",
  "accessPackageAssignment":{
     "targetId":"007d1c7e-7fa8-4e33-b678-5e437acdcddc",
     "assignmentPolicyId":"db440482-1210-4a60-9b55-3ac7a72f63ba",
     "accessPackageId":"88203d16-0e31-41d4-87b2-dd402f1435e9"
  }
}

响应

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignmentRequests/$entity",
    "createdDateTime": null,
    "completedDate": null,
    "id": "a6bb6942-3ae1-4259-9908-0133aaee9377",
    "requestType": "UserAdd",
    "requestState": "Submitted",
    "requestStatus": "Accepted",
    "isValidationOnly": false,
    "expirationDateTime": null,
    "justification": null
}

注销并关闭匿名会话。

步骤 3：验证是否已分配访问权限

在此步骤中，确认 为 Requestor1 用户帐户分配了访问包，并且是 Marketing 资源组 的成员。 返回到 Graph 资源管理器中的管理员会话。

步骤 3.1：获取请求的状态

使用请求的 id 属性的值来获取其当前状态。 在响应中，你会看到状态更改为“ 已完成” ，状态更改为“ 已交付”。

请求

GET https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentRequests/a6bb6942-3ae1-4259-9908-0133aaee9377

响应

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignmentRequests/$entity",
  "createdDateTime": "2020-06-29T20:24:24.683Z",
  "completedDate": "2020-06-29T20:24:47.937Z",
  "id": "a6bb6942-3ae1-4259-9908-0133aaee9377",
  "requestType": "UserAdd",
  "requestState": "Delivered",
  "requestStatus": "FulfilledNotificationTriggered",
  "isValidationOnly": false,
  "expirationDateTime": null,
  "justification": null
}

步骤 3.2：获取访问包分配

使用创建的访问包策略的 ID 查看资源已分配给 Requestor1 用户帐户。

请求

GET https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignments?$filter=accessPackageAssignmentPolicy/Id eq 'db440482-1210-4a60-9b55-3ac7a72f63ba'&$expand=target,accessPackageAssignmentResourceRoles

响应

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignments",
  "value": [
    {
      "id": "a6bb6942-3ae1-4259-9908-0133aaee9377",
      "catalogId": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
      "accessPackageId": "88203d16-0e31-41d4-87b2-dd402f1435e9",
      "assignmentPolicyId": "db440482-1210-4a60-9b55-3ac7a72f63ba",
      "targetId": "2bc42425-6dc5-4f2a-9ebb-7a7464481eb0",
      "assignmentStatus": "Delivered",
      "assignmentState": "Delivered",
      "isExtended": false,
      "expiredDateTime": null,
      "target": {
         "id": "8586ddc8-0ff7-4c24-9c79-f192bc3566e3",
         "objectId": "2bc42425-6dc5-4f2a-9ebb-7a7464481eb0"
      },
      "accessPackageAssignmentResourceRoles": [
         {
            "id": "bdb7e0a0-a927-42ab-bf30-c5b5533dc54a",
            "originSystem": "AadGroup",
            "status": "Fulfilled"
         }
      ]
    }
  ]
}

步骤 3.3：获取组的成员

授予请求后，使用为“市场营销”资源组记录的 ID，查看 Requestor1 用户帐户是否已添加到该组。

请求

GET https://graph.microsoft.com/v1.0/groups/f4892fac-e81c-4712-bdf2-a4450008a4b0/members

响应：

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "value": [
    {
      "@odata.type": "#microsoft.graph.user",
      "id": "007d1c7e-7fa8-4e33-b678-5e437acdcddc",
      "deletedDateTime": null,
      "accountEnabled": true,
      "ageGroup": null,
      "businessPhones": [],
      "city": null,
      "createdDateTime": "2020-06-23T18:43:24Z",
      "creationType": null,
      "companyName": null,
      "consentProvidedForMinor": null,
      "country": null,
      "department": null,
      "displayName": "Requestor1",
      "employeeId": null,
      "faxNumber": null,
      "givenName": null,
      "imAddresses": [],
      "infoCatalogs": [],
      "isResourceAccount": null,
      "jobTitle": null,
      "legalAgeGroupClassification": null,
      "mail": null,
      "mailNickname": "Requestor1"
    }
  ]
}

步骤 4：清理资源

删除访问包分配

必须先删除对访问包的任何分配，然后才能将其删除。 使用之前记录的分配请求 的 ID 将其删除。

在删除访问包之前，请删除访问包的所有分配。 使用之前记录的分配请求 的 ID 将其删除。

POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentRequests
Content-type: application/json

{
  "requestType": "AdminRemove",
  "accessPackageAssignment":{
     "id": "a6bb6942-3ae1-4259-9908-0133aaee9377"
  }
}

响应

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignmentRequests/$entity",
    "createdDateTime": null,
    "completedDate": null,
    "id": "78eaee8c-e6cf-48c9-8f99-aae44c35e379",
    "requestType": "AdminRemove",
    "requestState": "Submitted",
    "requestStatus": "Accepted",
    "isValidationOnly": false,
    "expirationDateTime": null,
    "justification": null
}

删除访问包分配策略

使用之前记录的分配策略的 ID 将其删除。 请确保先删除所有分配。 请求会返回 204 No Content 响应代码。

DELETE https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies/6c1f65ec-8c25-4a45-83c2-a1de2a6d0e9f

删除访问包

使用之前记录的访问包的 ID 将其删除。 请求会返回 204 No Content 响应代码。

请求

DELETE https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackages/cf54c6ca-d717-49bc-babe-d140d035dfdd

总结

在本教程中，市场营销活动资源定义为可以访问其他资源的单个组中的成员身份。 它也可以是组、应用程序或 SharePoint Online 网站的集合。

相关内容