次の方法で共有


エンタイトルメント管理 API を使用してリソースへのアクセスを管理する

Microsoft Entraエンタイトルメント管理を使用すると、従業員が生産性を高める必要があるリソースへのアクセスを管理できます。 このチュートリアルでは、エンタイトルメント管理 API を使用して、内部ユーザーが自分自身を要求するリソースのパッケージを作成します。 API は、Microsoft Entra 管理センターを使用するのではなく、カスタム アプリを作成するためのプログラムによる代替手段です。

このチュートリアルでは、以下を実行する方法について説明します。

  • ユーザーがセルフサービス要求できるアクセス パッケージを作成します。
  • アクセス パッケージにグループ リソースを割り当てます。
  • アクセス パッケージを要求する

前提条件

このチュートリアルを完了するには、次のリソースと特権が必要です。

  • Microsoft Entra ID P2 またはMicrosoft Entra ID ガバナンス ライセンスが有効になっている、作業Microsoft Entraテナント。 これらのライセンスは、このチュートリアルの機能に対して十分です。
  • テナント内のテスト ゲスト アカウントとテスト セキュリティ グループ。 セキュリティ グループは、このチュートリアルのリソースです。 必ず、グループの所有者であるか、グループ 管理者 ロールが割り当てられている必要があります。 このチュートリアルでは、次の操作を行います。
    • ユーザーは ID 007d1c7e-7fa8-4e33-b678-5e437acdcddc を持ち、 という名前 Requestor1です。
      • [省略可能]新しい匿名ブラウザー ウィンドウを開きます。 このチュートリアルの後半でサインインします。
    • グループには、"マーケティング グループ" の説明と "マーケティング リソース" の表示名を持つ ID があります f4892fac-e81c-4712-bdf2-a4450008a4b0
  • 少なくとも ID ガバナンス管理者ロールを持つアカウントを使用して、Graph エクスプローラー などの API クライアントにサインインします。
  • 委任されたアクセス許可を自分に付与します。 User.ReadWrite.AllGroup.ReadWrite.All、および EntitlementManagement.ReadWrite.All

注:

このチュートリアルのいくつかの手順では、エンドポイントを beta 使用します。

手順 1: カタログにリソースを追加し、アクセス パッケージを作成する

アクセス パッケージは、チームまたはプロジェクトが必要とするリソースのバンドルであり、ポリシーで管理されます。 アクセス パッケージは、カタログと呼ばれるコンテナーで定義されます。 カタログは、アクセス パッケージで使用されるリソース (グループ、アプリ、サイトなど) を参照できます。 エンタイトルメント管理には、既定 General のカタログが含まれています。

この手順では、一般カタログに Marketing Campaign アクセス パッケージを作成します。

手順 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: カタログにグループを追加する

このチュートリアルでは、リソースは ID を持つセキュリティ グループです e93e24d1-2b65-4a6c-a1dd-654a12225487

作成したグループをカタログに追加するには、次のプロパティ値を指定します。

  • catalogId - 使用しているカタログの ID
  • originId - 作成したグループの ID

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 でフィルター処理したため、成功した場合は、そのグループのメンバー ロールを表す 1 つの値が返されます。 ロールが返されない場合は、カタログの 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 つ追加されました。 ロールは、アクセス パッケージを持つすべてのユーザーに割り当てられます。

手順 1.7: アクセス パッケージ ポリシーを作成する

アクセス パッケージを作成し、リソースとロールを追加したら、アクセス パッケージ ポリシーを作成してアクセスできるユーザーを決定できます。 このチュートリアルでは、作成した Requestor1 アカウントを有効にして、アクセス パッケージ内のリソースへのアクセスを要求します。 このタスクには、次の値が必要です。

  • accessPackageId プロパティの値のアクセス パッケージの id
  • allowedRequestorsid プロパティの値の 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 ユーザー アカウントにアクセス パッケージが割り当てられ、現在は マーケティング リソース グループのメンバーであることを確認します。 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: リソースをクリーンアップする

この手順では、行った変更を削除し、 Marketing Campaign アクセス パッケージを削除します。

アクセス パッケージの割り当てを削除する

アクセス パッケージを削除する前に、アクセス パッケージへの割り当てを削除する必要があります。 以前に記録した割り当て要求の 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

まとめ

このチュートリアルでは、マーケティング キャンペーン リソースは 1 つのグループのメンバーシップであり、他のリソースにアクセスできます。 リソースには、グループ、アプリケーション、または SharePoint Online サイトのコレクションを指定することもできます。

このチュートリアルの機能は、Microsoft Entra ID P2 またはMicrosoft Entra ID ガバナンス ライセンスでサポートされています。 ただし、その他の高度なエンタイトルメント管理機能には、追加のライセンスが必要です。 詳細については、「ガバナンス ライセンスの基礎Microsoft Entra ID」を参照してください。