View, add, and remove assignments for an access package in entitlement management

In entitlement management, you can see who is assigned to access packages, their policy, status, and user lifecycle (preview). If an access package has an appropriate policy, you can also directly assign user to an access package. This article describes how to view, add, and remove assignments for access packages.

Prerequisites

To use entitlement management and assign users to access packages, you must have one of the following licenses:

• Microsoft Entra ID P2
• Enterprise Mobility + Security (EMS) E5 license
• Microsoft Entra ID Governance subscription

View who has an assignment

1. Sign in to the Microsoft Entra admin center as at least an Identity Governance Administrator.

   Tip

   Other least privilege roles that can complete this task include the Catalog owner, Access Package manager, and the Access Package assignment manager.

2. Browse to Identity governance > Entitlement management > Access package.

3. On the Access packages page, open an access package.

4. Select Assignments to see a list of active assignments.

   

5. Select a specific assignment to see more details.

6. To see a list of assignments that didn't have all resource roles properly provisioned, select the filter status and select Delivering.

   You can see more details on delivery errors by locating the user's corresponding request on the Requests page.

7. To see expired assignments, select the filter status and select Expired.

8. To download a CSV file of the filtered list, select Download.

View assignments programmatically

View assignments with Microsoft Graph

You can also retrieve assignments in an access package using Microsoft Graph. A user in an appropriate role with an application that has the delegated EntitlementManagement.Read.All or EntitlementManagement.ReadWrite.All permission can call the API to list accessPackageAssignments. An application that has the application permission EntitlementManagement.Read.All or EntitlementManagement.ReadWrite.All permission can also use this API to retrieve assignments across all catalogs.

Microsoft Graph will return the results in pages, and will continue to return a reference to the next page of results in the @odata.nextLink property with each response, until all pages of the results are read. To read all results, you must continue to call Microsoft Graph with the @odata.nextLink property returned in each response until the @odata.nextLink property is no longer returned, as described in paging Microsoft Graph data in your app.

While an Identity Governance Administrator can retrieve access packages from multiple catalogs, if user or application service principal is assigned only to catalog-specific delegated administrative roles, the request must supply a filter to indicate a specific access package, such as: $filter=accessPackage/id eq '00001111-aaaa-2222-bbbb-3333cccc4444'.

View assignments with PowerShell

You can also retrieve assignments to an access package in PowerShell with the Get-MgEntitlementManagementAssignment cmdlet from the Microsoft Graph PowerShell cmdlets for Identity Governance module version 2.1.x or later module version. This script illustrates using the Microsoft Graph PowerShell cmdlets module version 2.4.0 to retrieve all assignments to a particular access package. This cmdlet takes as a parameter the access package ID, which is included in the response from the Get-MgEntitlementManagementAccessPackage cmdlet. Be sure when using the Get-MgEntitlementManagementAccessPackage cmdlet to include the -All flag to cause all pages of assignments to be returned.

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "EntitlementManagement.Read.All"
$accesspackage = Get-MgEntitlementManagementAccessPackage -Filter "displayName eq 'Marketing Campaign'"
if ($null -eq $accesspackage) { throw "no access package"}
$assignments = @(Get-MgEntitlementManagementAssignment -AccessPackageId $accesspackage.Id -ExpandProperty target -All -ErrorAction Stop)
$assignments | ft Id,state,{$_.Target.id},{$_.Target.displayName}

The preceding query returns expired and delivering assignments along with delivered assignments. If you wish to exclude expired or delivering assignments, you can use a filter that includes the access package ID and the state of the assignments. This script illustrates using a filter to retrieve only the assignments in state Delivered for a particular access package. The script will then generate a CSV file assignments.csv, with one row per assignment.

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "EntitlementManagement.Read.All"
$accesspackage = Get-MgEntitlementManagementAccessPackage -Filter "displayName eq 'Marketing Campaign'"
if ($null -eq $accesspackage) { throw "no access package"}
$accesspackageId = $accesspackage.Id
$filter = "accessPackage/id eq '" + $accesspackageId + "' and state eq 'Delivered'"
$assignments = @(Get-MgEntitlementManagementAssignment -Filter $filter -ExpandProperty target -All -ErrorAction Stop)
$sp = $assignments | select-object -Property Id,{$_.Target.id},{$_.Target.ObjectId},{$_.Target.DisplayName},{$_.Target.PrincipalName}
$sp | Export-Csv -Encoding UTF8 -NoTypeInformation -Path ".\assignments.csv"

Directly assign a user

In some cases, you might want to directly assign specific users to an access package so that users don't have to go through the process of requesting the access package. To directly assign users, the access package must have a policy that allows administrator direct assignments.

1. Sign in to the Microsoft Entra admin center as at least an Identity Governance Administrator.

   Tip

   Other least privilege roles that can complete this task include the Catalog owner, Access Package manager, and the Access Package assignment manager.

2. Browse to Identity governance > Entitlement management > Access package.

3. On the Access packages page, open an access package.

4. In the left menu, select Assignments.

5. Select New assignment to open Add user to access package.

   

6. In the Select policy list, select a policy that the users' future requests and lifecycle will be governed and tracked by. If you want the selected users to have different policy settings, you can select Create new policy to add a new policy.

7. Once you select a policy, you are able to add users to select the users you want to assign this access package to, under the chosen policy.

   Note

   If you select a policy with questions, you can only assign one user at a time.

8. Set the date and time you want the selected users' assignment to start and end. If an end date isn't provided, the policy's lifecycle settings are used.

9. Optionally provide a justification for your direct assignment for record keeping.

10. If the selected policy includes additional requestor information, select View questions to answer them on behalf of the users, then select Save.

    

    

11. Select Add to directly assign the selected users to the access package.

    After a few moments, select Refresh to see the users in the Assignments list.

Directly assign any user (Preview)

Entitlement management also allows you to directly assign external users to an access package to make collaborating with partners easier. To do this, the access package must have a policy that allows users not yet in your directory to request access.

1. Sign in to the Microsoft Entra admin center as at least an Identity Governance Administrator.

   Tip

   Other least privilege roles that can complete this task include the Catalog owner, Access Package manager, and the Access Package assignment manager.

2. Browse to Identity governance > Entitlement management > Access package.

3. On the Access packages page, open an access package.

4. In the left menu, select Assignments.

5. Select New assignment to open Add user to access package.

6. In the Select policy list, select a policy that allows that is set to For users not in your directory

7. Select Any user. You're able to specify which users you want to assign to this access package.

8. Enter the user’s Name (optional) and the user’s Email address (required).

   Note

   • The user you want to add must be within the scope of the policy. For example, if your policy is set to Specific connected organizations, the user’s email address must be from the domain(s) of the selected organization(s). If the user you are trying to add has an email address of jen@foo.com but the selected organization’s domain is bar.com, you won't be able to add that user to the access package.
   • Similarly, if you set your policy to include All configured connected organizations, the user’s email address must be from one of your configured connected organizations. Otherwise, the user won't be added to the access package.
   • If you wish to add any user to the access package, you'll need to ensure that you select All users (All connected organizations + any external user) when configuring your policy.

9. Set the date and time you want the selected users' assignment to start and end. If an end date isn't provided, the policy's lifecycle settings are used.

10. Select Add to directly assign the selected users to the access package.

11. After a few moments, select Refresh to see the users in the Assignments list.

Directly assigning users programmatically

Assign a user to an access package with Microsoft Graph

You can also directly assign a user to an access package using Microsoft Graph. A user in an appropriate role with an application that has the delegated EntitlementManagement.ReadWrite.All permission, or an application with the EntitlementManagement.ReadWrite.All application permission, can call the API to create an accessPackageAssignmentRequest. In this request, the value of the requestType property should be adminAdd, and the assignment property is a structure that contains the targetId of the user being assigned.

Assign a user to an access package with PowerShell

You can assign a user to an access package in PowerShell with the New-MgEntitlementManagementAssignmentRequest cmdlet from the Microsoft Graph PowerShell cmdlets for Identity Governance module version 2.1.x or later module version. This script illustrates using the Microsoft Graph PowerShell cmdlets module version 2.4.0.

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "EntitlementManagement.ReadWrite.All"
$accesspackage = Get-MgEntitlementManagementAccessPackage -Filter "displayname eq 'Marketing Campaign'" -ExpandProperty "assignmentpolicies"
if ($null -eq $accesspackage) { throw "no access package"}
$policy = $accesspackage.AssignmentPolicies[0]
$userid = "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
$params = @{
   requestType = "adminAdd"
   assignment = @{
      targetId = $userid
      assignmentPolicyId = $policy.Id
      accessPackageId = $accesspackage.Id
   }
}
New-MgEntitlementManagementAssignmentRequest -BodyParameter $params

You can also assign multiple users that are in your directory to an access package using PowerShell with the New-MgBetaEntitlementManagementAccessPackageAssignment cmdlet from the Microsoft Graph PowerShell cmdlets for Identity Governance module version 2.4.0 or later. This cmdlet takes as parameters

• the access package ID, which is included in the response from the Get-MgEntitlementManagementAccessPackage cmdlet,
• the access package assignment policy ID, which is included in the policy in the assignmentpolicies field in the response from the Get-MgEntitlementManagementAccessPackage cmdlet,
• the object IDs of the target users, either as an array of strings, or as a list of user members returned from the Get-MgGroupMember cmdlet.

For example, if you want to ensure all the users who are currently members of a group also have assignments to an access package, you can use this cmdlet to create requests for those users who don't currently have assignments. This cmdlet will only create assignments; it doesn't remove assignments for users who are no longer members of a group. If you wish to have the assignments of an access package track the membership of a group and add and remove assignments over time, use an automatic assignment policy instead.

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "EntitlementManagement.ReadWrite.All,Directory.Read.All"
$members = @(Get-MgGroupMember -GroupId "a34abd69-6bf8-4abd-ab6b-78218b77dc15" -All)

$accesspackage = Get-MgEntitlementManagementAccessPackage -Filter "displayname eq 'Marketing Campaign'" -ExpandProperty "assignmentPolicies"
if ($null -eq $accesspackage) { throw "no access package"}
$policy = $accesspackage.AssignmentPolicies[0]
$req = New-MgBetaEntitlementManagementAccessPackageAssignment -AccessPackageId $accesspackage.Id -AssignmentPolicyId $policy.Id -RequiredGroupMember $members

If you wish to add an assignment for a user who isn't yet in your directory, you can use the New-MgBetaEntitlementManagementAccessPackageAssignmentRequest cmdlet from the Microsoft Graph PowerShell cmdlets for Identity Governance beta module version 2.1.x or later beta module version. This script illustrates using the Microsoft Graph beta profile and Microsoft Graph PowerShell cmdlets module version 2.4.0. This cmdlet takes as parameters

• the access package ID, which is included in the response from the Get-MgEntitlementManagementAccessPackage cmdlet,
• the access package assignment policy ID, which is included in policy in the assignmentpolicies field in the response from the Get-MgEntitlementManagementAccessPackage cmdlet,
• the email address of the target user.

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "EntitlementManagement.ReadWrite.All"
$accesspackage = Get-MgEntitlementManagementAccessPackage -Filter "displayname eq 'Marketing Campaign'" -ExpandProperty "assignmentPolicies"
if ($null -eq $accesspackage) { throw "no access package"}
$policy = $accesspackage.AssignmentPolicies[0]
$req = New-MgBetaEntitlementManagementAccessPackageAssignmentRequest -AccessPackageId $accesspackage.Id -AssignmentPolicyId $policy.Id -TargetEmail "sample@example.com"

Remove an assignment

You can remove an assignment that a user or an administrator had previously requested.

1. Sign in to the Microsoft Entra admin center as at least an Identity Governance Administrator.

2. Browse to Identity governance > Entitlement management > Access package.

3. On the Access packages page, open an access package.

4. In the left menu, select Assignments.

5. Select the check box next to the user whose assignment you want to remove from the access package.

6. Select the Remove button near the top of the left pane.

   

   A notification appears informing you that the assignment has been removed.

Remove an assignment programmatically

Remove an assignment with Microsoft Graph

You can also remove an assignment of a user to an access package using Microsoft Graph. A user in an appropriate role with an application that has the delegated EntitlementManagement.ReadWrite.All permission, or an application with the EntitlementManagement.ReadWrite.All application permission, can call the API to create an accessPackageAssignmentRequest. In this request, the value of the requestType property should be adminRemove, and the assignment property is a structure that contains the id property identifying the accessPackageAssignment being removed.

Remove an assignment with PowerShell

You can remove a user's assignment in PowerShell with the New-MgEntitlementManagementAssignmentRequest cmdlet from the Microsoft Graph PowerShell cmdlets for Identity Governance module version 2.1.x or later module version. This script illustrates using the Microsoft Graph PowerShell cmdlets module version 2.4.0.

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "EntitlementManagement.ReadWrite.All"
$accessPackageId = "9f573551-f8e2-48f4-bf48-06efbb37c7b8"
$userId = "11bb11bb-cc22-dd33-ee44-55ff55ff55ff"
$filter = "accessPackage/Id eq '" + $accessPackageId + "' and state eq 'Delivered' and target/objectId eq '" + $userId + "'"
$assignment = Get-MgEntitlementManagementAssignment -Filter $filter -ExpandProperty target -all -ErrorAction stop
if ($assignment -ne $null) {
   $params = @{
      requestType = "adminRemove"
      assignment = @{ id = $assignment.id }
   }
   New-MgEntitlementManagementAssignmentRequest -BodyParameter $params
}

Next steps

• Change request and settings for an access package
• View reports and logs