| title | Create accessPackageAssignmentPolicy |
|---|---|
| description | Create a new accessPackageAssignmentPolicy object in Microsoft Entra entitlement management. |
| ms.localizationpriority | medium |
| author | markwahl-msft |
| ms.subservice | entra-id-governance |
| doc_type | apiPageType |
| ms.date | 11/20/2024 |
Namespace: microsoft.graph
[!INCLUDE beta-disclaimer]
Create a new accessPackageAssignmentPolicy object in Microsoft Entra entitlement management.
[!INCLUDE national-cloud-support]
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
[!INCLUDE permissions-table]
[!INCLUDE rbac-entitlement-access-package-manager-write]
POST /identityGovernance/entitlementManagement/accessPackageAssignmentPolicies| Name | Description |
|---|---|
| Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
| Content-Type | application/json. Required. |
In the request body, supply a JSON representation of an accessPackageAssignmentPolicy object.
If successful, this method returns a 200-series response code and a new accessPackageAssignmentPolicy object in the response body.
A direct assignment policy is useful when access package assignment requests will only be created by an administrator, not by users themselves.
The following example shows a request to create an access package assignment policy. In this policy, no users can request, no approval is required, and there are no access reviews.
POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies
Content-type: application/json
{
"accessPackageId": "56ff43fd-6b05-48df-9634-956a777fce6d",
"displayName": "direct",
"description": "direct assignments by administrator",
"accessReviewSettings": null,
"requestorSettings": {
"scopeType": "NoSubjects",
"acceptRequests": true,
"allowedRequestors": []
},
"requestApprovalSettings": {
"isApprovalRequired": false,
"isApprovalRequiredForExtension": false,
"isRequestorJustificationRequired": false,
"approvalMode": "NoApproval",
"approvalStages": []
}
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "4c02f928-7752-49aa-8fc8-e286d973a965",
"accessPackageId": "56ff43fd-6b05-48df-9634-956a777fce6d",
"displayName": "direct",
"description": "direct assignments by administrator"
}The following example shows a more complex policy with two-stage approvals and access reviews.
The following example shows a request to create an access package assignment policy.
POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies
Content-type: application/json
{
"accessPackageId": "string (identifier)",
"displayName": "Users from connected organizations can request",
"description": "Allow users from configured connected organizations to request and be approved by their sponsors",
"canExtend": false,
"durationInDays": 365,
"expirationDateTime": null,
"requestorSettings": {
"scopeType": "AllExistingConnectedOrganizationSubjects",
"acceptRequests": true,
"allowedRequestors": []
},
"requestApprovalSettings": {
"isApprovalRequired": true,
"isApprovalRequiredForExtension": false,
"isRequestorJustificationRequired": true,
"approvalMode": "Serial",
"approvalStages": [
{
"approvalStageTimeOutInDays": 14,
"isApproverJustificationRequired": true,
"isEscalationEnabled": true,
"escalationTimeInMinutes": 11520,
"primaryApprovers": [
{
"@odata.type": "#microsoft.graph.groupMembers",
"isBackup": true,
"id": "string (identifier)",
"description": "group for users from connected organizations which have no external sponsor"
},
{
"@odata.type": "#microsoft.graph.externalSponsors",
"isBackup": false
}
],
"escalationApprovers": [
{
"@odata.type": "#microsoft.graph.singleUser",
"isBackup": true,
"id": "string (identifier)",
"description": "user if the external sponsor does not respond"
}
]
},
{
"approvalStageTimeOutInDays": 14,
"isApproverJustificationRequired": true,
"isEscalationEnabled": true,
"escalationTimeInMinutes": 11520,
"primaryApprovers": [
{
"@odata.type": "#microsoft.graph.groupMembers",
"isBackup": true,
"id": "string (identifier)",
"description": "group for users from connected organizations which have no internal sponsor"
},
{
"@odata.type": "#microsoft.graph.internalSponsors",
"isBackup": false
}
],
"escalationApprovers": [
{
"@odata.type": "#microsoft.graph.singleUser",
"isBackup": true,
"id": "string (identifier)",
"description": "user if the internal sponsor does not respond"
}
]
}
]
},
"accessReviewSettings": {
"isEnabled": true,
"recurrenceType": "quarterly",
"reviewerType": "Self",
"startDateTime": "2020-04-01T07:59:59.998Z",
"durationInDays": 25,
"reviewers": []
}
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "4c02f928-7752-49aa-8fc8-e286d973a965",
"accessPackageId": "string (identifier)",
"displayName": "Users from connected organizations can request",
"description": "Allow users from configured connected organizations to request and be approved by their sponsors"
}Questions configured in an assignment policy will be asked to requestors in scope of the policy. Their answers will be shown to their approvers. Question IDs are read-only and are included in the response by default.
The following example shows a request to create an access package assignment policy.
POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies
Content-type: application/json
{
"accessPackageId": "b2eba9a1-b357-42ee-83a8-336522ed6cbf",
"displayName": "Users from connected organizations can request",
"description": "Allow users from configured connected organizations to request and be approved by their sponsors",
"canExtend": false,
"durationInDays": 365,
"expirationDateTime": null,
"requestorSettings": {
"scopeType": "AllExistingConnectedOrganizationSubjects",
"acceptRequests": true
},
"requestApprovalSettings": {
"isApprovalRequired": true,
"isApprovalRequiredForExtension": false,
"isRequestorJustificationRequired": true,
"approvalMode": "SingleStage",
"approvalStages": [{
"approvalStageTimeOutInDays": 14,
"isApproverJustificationRequired": true,
"isEscalationEnabled": false,
"escalationTimeInMinutes": 11520,
"primaryApprovers": [{
"@odata.type": "#microsoft.graph.groupMembers",
"isBackup": true,
"id": "d2dcb9a1-a445-42ee-83a8-476522ed6cbf",
"description": "group for users from connected organizations which have no external sponsor"
},
{
"@odata.type": "#microsoft.graph.externalSponsors",
"isBackup": false
}
]
}
]
},
"questions": [{
"isRequired": false,
"text": {
"defaultText": "what state are you from?",
"localizedTexts": [{
"text": "¿De qué estado eres?",
"languageCode": "es"
}]
},
"@odata.type": "#microsoft.graph.accessPackageMultipleChoiceQuestion",
"choices": [{
"actualValue": "AZ",
"displayValue": {
"localizedTexts": [{
"text": "Arizona",
"languageCode": "es"
}]
}
}, {
"actualValue": "CA",
"displayValue": {
"localizedTexts": [{
"text": "California",
"languageCode": "es"
}]
}
}, {
"actualValue": "OH",
"displayValue": {
"localizedTexts": [{
"text": "Ohio",
"languageCode": "es"
}]
}
}],
"allowsMultipleSelection": false
}, {
"isRequired": false,
"text": {
"defaultText": "Who is your manager?",
"localizedTexts": [{
"text": "por qué necesita acceso a este paquete",
"languageCode": "es"
}]
},
"@odata.type": "#microsoft.graph.accessPackageTextInputQuestion",
"isSingleLineQuestion": false
}]
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "4c02f928-7752-49aa-8fc8-e286d973a965",
"accessPackageId": "string (identifier)",
"displayName": "Users from connected organizations can request",
"description": "Allow users from configured connected organizations to request and be approved by their sponsors",
"questions": [{
"id" : "BD3F6B95-458D-4BC8-A9A6-8D4B29F64F3D",
"isRequired": false,
"text": {
"defaultText": "what state are you from?",
"localizedTexts": [{
"text": "¿De qué estado eres?",
"languageCode": "es"
}]
},
"@odata.type": "#microsoft.graph.accessPackageMultipleChoiceQuestion",
"choices": [{
"actualValue": "AZ",
"displayValue": {
"localizedTexts": [{
"text": "Arizona?",
"languageCode": "es"
}]
}
}, {
"actualValue": "CA",
"displayValue": {
"localizedTexts": [{
"text": "California",
"languageCode": "es"
}]
}
}, {
"actualValue": "OH",
"displayValue": {
"localizedTexts": [{
"text": "Ohio",
"languageCode": "es"
}]
}
}],
"allowsMultipleSelection": false
}, {
"id" : "F652C13C-A660-4E4C-A1E0-CE9FEC6EE57A",
"isRequired": false,
"text": {
"defaultText": "Who is your manager?",
"localizedTexts": [{
"text": "por qué necesita acceso a este paquete",
"languageCode": "es"
}]
},
"@odata.type": "#microsoft.graph.accessPackageTextInputQuestion",
"isSingleLineQuestion": false
}]
}In the following example, the pre-defined customAccessPackageWorkflowExtension object is triggered when an access package assigned request is created and when it's granted. The identifier provided within the customExtension field is the customAccessPackageWorkflowExtension object's ID.
POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies
Content-type: application/json
{
"displayName": "extension-policy",
"description": "test",
"accessPackageId": "ba5807c7-2aa9-4c8a-907e-4a17ee587500",
"expiration": {
"type": "afterDuration",
"duration": "P365D"
},
"canExtend": false,
"requestApprovalSettings": null,
"requestorSettings": {
"acceptRequests": true,
"scopeType": "AllExistingDirectorySubjects",
"allowedRequestors": [],
"isOnBehalfAllowed": false
},
"accessReviewSettings": null,
"questions": [],
"customExtensionHandlers": [
{
"stage": "assignmentRequestCreated",
"customExtension": {
"id": "219f57b6-7983-45a1-be01-2c228b7a43f8"
}
},
{
"stage": "assignmentRequestGranted",
"customExtension": {
"id": "219f57b6-7983-45a1-be01-2c228b7a43f8"
}
}
]
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response. The customExtensionHandlers object isn't returned by default. To retrieve this object, use the GET method with $expand. For more information, see Retrieve the custom extension handlers for a policy
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "d0324cbb-24a2-4edb-acca-fee5384c6a5e",
"displayName": "extension-policy",
"description": "test",
"canExtend": false,
"durationInDays": 0,
"expirationDateTime": null,
"accessPackageId": "ba5807c7-2aa9-4c8a-907e-4a17ee587500",
"accessReviewSettings": null,
"questions": [],
"requestorSettings": {
"scopeType": "AllExistingDirectorySubjects",
"acceptRequests": true,
"allowedRequestors": []
},
"requestApprovalSettings": {
"isApprovalRequired": false,
"isApprovalRequiredForExtension": false,
"isRequestorJustificationRequired": false,
"approvalMode": "NoApproval",
"approvalStages": []
}
}Example 5: Create a policy and specify the stages to trigger predefined access package custom extensions
In the following example, the predefined accessPackageCustomWorkflowExtension object is triggered by the creation or approval of an access package assignment request. The identifier in the customExtension property corresponds to the ID of the accessPackageCustomWorkflowExtension object.
The following example shows a request.
POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies
Content-type: application/json
{
"displayName": "extension-policy",
"description": "test",
"accessPackageId": "ba5807c7-2aa9-4c8a-907e-4a17ee587500",
"expiration": {
"type": "afterDuration",
"duration": "P365D"
},
"canExtend": false,
"requestApprovalSettings": null,
"requestorSettings": {
"acceptRequests": true,
"scopeType": "AllExistingDirectorySubjects",
"allowedRequestors": [],
"isOnBehalfAllowed": false
},
"accessReviewSettings": null,
"questions": [],
"customExtensionStageSettings": [
{
"stage": "assignmentRequestCreated",
"customExtension": {
"id": "219f57b6-7983-45a1-be01-2c228b7a43f8"
}
},
{
"stage": "assignmentRequestGranted",
"customExtension": {
"id": "219f57b6-7983-45a1-be01-2c228b7a43f8"
}
}
]
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response. The customExtensionStageSettings object isn't returned by default. To retrieve this object, use the GET accessPackageAssignmentPolicy method with $expand. For more information, see Example 3: Retrieve the custom extension stage settings for a policy.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "d0324cbb-24a2-4edb-acca-fee5384c6a5e",
"displayName": "extension-policy",
"description": "test",
"canExtend": false,
"durationInDays": 0,
"expirationDateTime": null,
"accessPackageId": "ba5807c7-2aa9-4c8a-907e-4a17ee587500",
"accessReviewSettings": null,
"questions": [],
"requestorSettings": {
"scopeType": "AllExistingDirectorySubjects",
"acceptRequests": true,
"allowedRequestors": []
},
"requestApprovalSettings": {
"isApprovalRequired": false,
"isApprovalRequiredForExtension": false,
"isRequestorJustificationRequired": false,
"approvalMode": "NoApproval",
"approvalStages": []
}
}The following example shows how to create an access package policy with a verifiable credential requirement.
POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies
Content-type: application/json
{
"displayName": "policy-with-verified-id",
"description": "test",
"accessPackageId": "ba5807c7-2aa9-4c8a-907e-4a17ee587500",
"expiration": {
"type": "afterDuration",
"duration": "P365D"
},
"canExtend": false,
"requestApprovalSettings": null,
"requestorSettings": {
"acceptRequests": true,
"scopeType": "AllExistingDirectorySubjects",
"allowedRequestors": [],
"isOnBehalfAllowed": false
},
"accessReviewSettings": null,
"questions": [],
"customExtensionHandlers": [],
"verifiableCredentialSettings":
{
"credentialTypes":[{
"issuers": ["did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>..."],
"credentialType": "VerifiedCredentialExpert"
}]
}
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "d0324cbb-24a2-4edb-acca-fee5384c6a5e",
"displayName": "extension-policy",
"description": "test",
"canExtend": false,
"durationInDays": 0,
"expirationDateTime": null,
"accessPackageId": "ba5807c7-2aa9-4c8a-907e-4a17ee587500",
"accessReviewSettings": null,
"questions": [],
"requestorSettings": {
"scopeType": "AllExistingDirectorySubjects",
"acceptRequests": true,
"allowedRequestors": []
},
"requestApprovalSettings": {
"isApprovalRequired": false,
"isApprovalRequiredForExtension": false,
"isRequestorJustificationRequired": false,
"approvalMode": "NoApproval",
"approvalStages": []
},
"customExtensionHandlers": [],
"verifiableCredentialSettings": {
"credentialTypes":[{
"issuers": ["did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>..."],
"credentialType": "VerifiedCredentialExpert"
}]
}
}In the following example, the policy is created for an access package assignment that is determining the approver dynamically via a logic app called from a custom extension.
The following example shows a request.
POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/assignmentPolicies/
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/entitlementManagement/accessPackageAssignmentPolicies/$entity",
"displayName": "Dynamic approver policy",
"description": "Dynamic approver policy",
"canExtend": false,
"durationInDays": 0,
"expirationDateTime": null,
"accessPackageId": "fc29cdca-57f6-47e3-b20c-3fa18e4826ac",
"accessReviewSettings": null,
"questions": [],
"accessPackageNotificationSettings": {
"isAssignmentNotificationDisabled": false
},
"verifiableCredentialSettings": {
"credentialTypes": []
},
"requestorSettings": {
"scopeType": "AllExistingDirectorySubjects",
"acceptRequests": true,
"allowedRequestors": []
},
"requestApprovalSettings": {
"isApprovalRequired": true,
"isApprovalRequiredForExtension": false,
"isRequestorJustificationRequired": true,
"approvalMode": "SingleStage",
"approvalStages": [
{
"@odata.type": "#microsoft.graph.accessPackageDynamicApprovalStage",
"customExtension": {
"@odata.type": "#microsoft.graph.accessPackageAssignmentRequestWorkflowExtension",
"id": "52036a43-10b5-444d-a1a2-d4f240420239"
}
}
]
},
"customExtensionStageSettings": [
{
"stage": "assignmentRequestDeterminingApprovalRequirements",
"customExtension": {
"@odata.type": "#microsoft.graph.accessPackageAssignmentRequestWorkflowExtension",
"id": "52036a43-10b5-444d-a1a2-d4f240420239"
}
}
]
}
The following example shows the response. The customExtensionStageSettings object isn't returned by default. To retrieve this object, use the GET accessPackageAssignmentPolicy method with $expand. For more information, see Example 2: Retrieve the custom extension stage settings for a policy.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "d0324cbb-24a2-4edb-acca-fee5384c6a5e",
"displayName": "Dynamic approver policy",
"description": "Dynamic approver policy",
"canExtend": false,
"durationInDays": 0,
"expirationDateTime": null,
"accessPackageId": "fc29cdca-57f6-47e3-b20c-3fa18e4826ac",
"accessReviewSettings": null,
"questions": [],
"requestorSettings": {
"scopeType": "AllExistingDirectorySubjects",
"acceptRequests": true,
"allowedRequestors": []
},
"requestApprovalSettings": {
"isApprovalRequired": false,
"isApprovalRequiredForExtension": false,
"isRequestorJustificationRequired": false,
"approvalMode": "NoApproval",
"approvalStages": []
},
"customExtensionStageSettings": [
{
"stage": "assignmentRequestCreated",
"customExtension": {
"@odata.type": "#microsoft.graph.accessPackageAssignmentRequestWorkflowExtension",
"id": "52036a43-10b5-444d-a1a2-d4f240420239"
}
}
]
}