Tutorial: Manage access to resources in Microsoft Entra entitlement management using Microsoft Graph PowerShell
Managing access to all the resources that employees need, such as groups, applications, and sites, is an important function for organizations. You want to grant employees the right level of access they need to be productive and remove their access when it's no longer needed. Microsoft Entra entitlement management using Microsoft Graph PowerShell enables you to manage this type of access.
In this tutorial, you'll create a package of resources for a marketing campaign that internal users can use for self-service requests. Requests don't require approval and users' access expires after 30 days. Here, the marketing campaign resources are just membership in a single group, but it could be a collection of groups, applications, or SharePoint Online sites.
Prerequisites
To successfully complete this tutorial, make sure you have the required prerequisites:
Microsoft Graph PowerShell SDK is installed. Follow the installation guide for more info on how to do this.
To use Microsoft Entra entitlement management, you must have Microsoft Entra ID Governance subscriptions for your organization's users. Some capabilities within this feature may operate with a Microsoft Entra ID P2 subscription.
Entitlement management is available in the beta and v1 modules of Microsoft Graph PowerShell. This tutorial uses the beta module. Ensure that you have both Microsoft.Graph and Microsoft.Graph.Beta modules installed.
Microsoft Graph PowerShell using a global administrator role and the appropriate permissions. The
User.ReadWrite.All,Group.ReadWrite.All, andEntitlementManagement.ReadWrite.Alldelegated permissions are required. To set the permissions in Microsoft Graph PowerShell, run;Connect-MgGraph -Scopes "User.ReadWrite.All", "Group.ReadWrite.All", "EntitlementManagement.ReadWrite.All"Select Consent on behalf of your organization before accepting in the sign-in dialog box.
Step 1: Create a user account and a group
In this step, you'll create a group named Marketing resources in the directory that is the target resource for entitlement management. You'll also create a user account that is set up as an internal requestor.
Create a user account
Create a user account that you'll use later to request access to the resources in the access package.
When you make these calls, change contoso.onmicrosoft.com to the domain name of your tenant. You can find tenant information on the Microsoft Entra overview page. Record the value of the returned Id property to use later.
$passwordProfile =@{
Password = 'Contoso1234'
ForceChangePasswordNextSignIn = $true
}
New-MgUser -DisplayName 'Requestor1' -PasswordProfile $passwordProfile -AccountEnabled -MailNickName 'Requestor1' -UserPrincipalName 'Requestor1@contoso.onmicrosoft.com'
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- --------
6c42590f-fcf0-4922-bac6-205f7c6aa89c Requestor1 Requestor1@contoso.onmicrosoft.com Member
Create a group
Create a group named Marketing resources that is the target resource for entitlement management.
New-MgGroup -DisplayName 'Marketing resources' -Description 'Marketing resources' -MailEnabled: $False -MailNickName 'markres' -SecurityEnabled
Id DisplayName Description GroupTypes
-- ----------- ----------- ----------
87553228-0d72-4138-890b-36e683f883b7 Marketing resources Marketing resources {}
Step 2: Add resources to a catalog and create an access package
An access package is a bundle of resources that a team or project needs and is governed by policies. Access packages are defined in containers called catalogs. Catalogs can reference resources such as groups, apps, and sites that are used in the access package.
In this step, create a Marketing Campaign access package in the General catalog.
Get the catalog identifier
To add resources to a catalog, you must first get its identifier. If you're using the general catalog, run the following command to get its Id. If you're using a different catalog, change the filter value in the request to the name of your catalog. Record the returned Id property to use later.
Get-MgBetaEntitlementManagementAccessPackageCatalog -Filter "DisplayName eq 'General'" |
Format-List
AccessPackageResourceRoles :
AccessPackageResourceScopes :
AccessPackageResources :
AccessPackages :
CatalogStatus : Published
CatalogType : ServiceDefault
CreatedBy : Azure AD
CreatedDateTime : 1/13/2022 6:47:56 AM
Description : Built-in catalog.
DisplayName : General
Id : 88d3e491-5247-4209-9b56-c4c95d9694e9
IsExternallyVisible : True
ModifiedBy : Azure AD
ModifiedDateTime : 1/13/2022 6:47:56 AM
AdditionalProperties : {}
The output should only contain the catalog whose name you provided in the request. If there are no values returned, check that the name of the catalog is correct before you proceed.
Add the group to the catalog
To add the group that you created to the catalog, provide the following property values:
- CatalogId - Specifies the Id of the catalog that you're using.
- RequestType - Set to
AdminAdd. - AccessPackageResource - Represents the resource. This resource should contain two properties: OriginSystem should be
AadGroupand OriginId is the identifier of the group.
$accessPackageResource = @{
"originSystem" = "AadGroup "
OriginId= "87553228-0d72-4138-890b-36e683f883b7"
}
New-MgBetaEntitlementManagementAccessPackageResourceRequest -CatalogId '88d3e491-5247-4209-9b56-c4c95d9694e9' -RequestType "AdminAdd" -AccessPackageResource $accessPackageResource | Format-List
AccessPackageResource : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageResource
CatalogId : 88d3e491-5247-4209-9b56-c4c95d9694e9
ExecuteImmediately : False
ExpirationDateTime :
Id : 5f32e397-18f2-4e5b-9e5e-d17097684442
IsValidationOnly :
Justification :
RequestState : Delivered
RequestStatus : Fulfilled
RequestType : AdminAdd
Requestor : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageSubject1
AdditionalProperties : {[@odata.context, https://graph.microsoft.com/beta/$metadata#identityGovernance/entitlementManagement/accessPackageResourceRequests/$entity]}
The request state indicates the outcome of whether the service was able to add the resource to the catalog. The value is Delivered if the resource was added.
Get catalog resources
In later steps, you'll need the Id that was assigned to the group resource in the catalog. This identifier represents the group as a resource in the catalog and is different from the group identifier itself in Microsoft Graph PowerShell. To get the resource, provide the Id of the catalog and filter by the display name of the group.
Get-MgBetaEntitlementManagementAccessPackageCatalogAccessPackageResource -AccessPackageCatalogId '88d3e491-5247-4209-9b56-c4c95d9694e9' -Filter "DisplayName eq 'Marketing resources'" | Format-List
AccessPackageResourceEnvironment : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageResourceEnvironment
AccessPackageResourceRoles :
AccessPackageResourceScopes :
AddedBy : admin@contoso.onmicrosoft.com
AddedOn : 4/5/2022 11:33:44 AM
Attributes : {}
Description : Marketing resources
DisplayName : Marketing resources
Id : 0a358d7b-42d9-48c5-8455-df23dcaff2ad
IsPendingOnboarding : False
OriginId : 87553228-0d72-4138-890b-36e683f883b7
OriginSystem : AadGroup
ResourceType : Security Group
Url : https://account.activedirectory.windowsazure.com/r?tenantId=06f6521d-c18c-460a-8656-fa82e81aa94b#/manageMembership?objectType=Group&objectId=87553228-0d72-4138-890b-36e683f883b7
AdditionalProperties : {}
Get resource roles
The access package assigns users to the roles of a resource. The typical role of a group used in an access package is the member role. You'll need the member role when you add a resource role to the access package.
In this command, use the Id of the catalog and the Id of the group resource you recorded in the previous step to get the OriginId of the member resource role.
Get-MgBetaEntitlementManagementAccessPackageCatalogAccessPackageResourceRole -AccessPackageCatalogId '88d3e491-5247-4209-9b56-c4c95d9694e9' -Filter "originSystem eq 'AadGroup' and accessPackageResource/id eq '0a358d7b-42d9-48c5-8455-df23dcaff2ad' and DisplayName eq 'Member'"
Id Description DisplayName OriginId OriginSystem
-- ----------- ----------- -------- ------------
00000000-0000-0000-0000-000000000000 Member Member_87553228-0d72-4138-890b-36e683f883b7 AadGroup
If successful, a single record is returned which represents the member role of that group. If no roles are returned, check the Id values of the catalog and the access package resource.
Create the access package
At this point, you have a catalog with a group resource, and you know that you'll use the resource role of group member in the access package. The next step is to create the access package. After creating the access package, you can add the resource role to it and create a policy for how users can request access to that resource role. You use the Id of the catalog that you recorded earlier to create the access package. Record the Id of the access package to use later. In this step, you create a Marketing Campaign access package in the General catalog.
New-MgBetaEntitlementManagementAccessPackage -CatalogId '88d3e491-5247-4209-9b56-c4c95d9694e9' -DisplayName 'Marketing Campaign'|
Format-List
AccessPackageAssignmentPolicies :
AccessPackageCatalog : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageCatalog1
AccessPackageResourceRoleScopes :
AccessPackagesIncompatibleWith :
CatalogId : 88d3e491-5247-4209-9b56-c4c95d9694e9
CreatedBy : admin@contoso.onmicrosoft.com
CreatedDateTime : 4/5/2022 11:40:59 AM
Description :
DisplayName : Marketing Campaign
Id : 08173ced-8eae-4023-8433-cb85f29e7726
IncompatibleAccessPackages :
IncompatibleGroups :
IsHidden : False
IsRoleScopesVisible : False
ModifiedBy : admin@contoso.onmicrosoft.com
ModifiedDateTime : 4/5/2022 11:40:59 AM
AdditionalProperties : {[@odata.context, https://graph.microsoft.com/beta/$metadata#identityGovernance/entitlementManagement/accessPackages/$entity]}
Add a resource role to the access package
Add the member role of the group resource to the access package. Provide the Id of the access package, Id of the group catalog resource for the accessPackageResource, and the OriginId of the Member role that you previously recorded.
$accessPackageResource = @{
"id"= '0a358d7b-42d9-48c5-8455-df23dcaff2ad'
"resourceType" ='Security Group'
"originId"= '87553228-0d72-4138-890b-36e683f883b7'
"originSystem"= 'AadGroup'
}
$accessPackageResourceRole = @{
"originId"= 'Member_87553228-0d72-4138-890b-36e683f883b7'
"displayName" = 'Member'
"originSystem" = 'AadGroup'
"accessPackageResource" = $accessPackageResource
}
$accessPackageResourceScope = @{
"originId" = '87553228-0d72-4138-890b-36e683f883b7'
"originSystem" ='AadGroup'
}
New-MgBetaEntitlementManagementAccessPackageResourceRoleScope -AccessPackageId '08173ced-8eae-4023-8433-cb85f29e7726' -AccessPackageResourceRole $accessPackageResourceRole -AccessPackageResourceScope $accessPackageResourceScope | Format-List
AccessPackageResourceRole : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageResourceRole
AccessPackageResourceScope : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageResourceScope
CreatedBy : admin@contoso.onmicrosoft.com
CreatedDateTime : 4/5/2022 11:48:35 AM
Id : 970ea023-669d-49a5-ae4b-642b3c6f403c_fea332ec-06e3-4c35-ad87-c97d79c3bf9b
ModifiedBy : admin@contoso.onmicrosoft.com
ModifiedDateTime : 4/5/2022 11:48:35 AM
AdditionalProperties : {[@odata.context, https://graph.microsoft.com/beta/$metadata#identityGovernance/entitlementManagement/accessPackages('08173ced-8eae-4023-8433-cb85f29e7726')/accessPackageResourceRoleScopes/$entity]}
This access package now has one resource role, which is a group membership. The role is assigned to any user who has the access package.
Create an access package policy
After creating the access package and adding resources and roles, you can decide who can access it by creating an access package policy. Enable the Requestor1 user account that you created in step 1 to request access to the resources in the access package. For this task, you need these values:
- Id of the access package for the value of the accessPackageId property.
- Id of the Requestor1 user account for the value of the id property in the allowedRequestors.
The value of the DurationInDays property enables the Requestor1 account to access the resources in the access package for 30 days. Record the value of the Id property that is returned to use later.
$allowedRequestors = @(@{
"@odata.type" = '#microsoft.graph.singleUser'
"isBackup" = $false
"id"= '6c42590f-fcf0-4922-bac6-205f7c6aa89c'
"description" = 'Requestor1'
})
$requestorSettings =@{
"scopeType" = 'SpecificDirectorySubjects'
"acceptRequests" = $true
"allowedRequestors" = $allowedRequestors
}
$requestApprovalSettings = @{
"isApprovalRequired" = $false
"isApprovalRequiredForExtension" =$false
"isRequestorJustificationRequired"= $false
"approvalMode"= 'NoApproval'
"approvalStages"= '[]'
}
New-MgBetaEntitlementManagementAccessPackageAssignmentPolicy -AccessPackageId '08173ced-8eae-4023-8433-cb85f29e7726' -DisplayName 'Specific users' -Description 'Specific users can request assignment' -DurationInDays 30 -RequestorSettings $requestorSettings -RequestApprovalSettings $requestApprovalSettings | Format-List
AccessPackage : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackage
AccessPackageCatalog : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageCatalog1
AccessPackageId : 08173ced-8eae-4023-8433-cb85f29e7726
AccessReviewSettings : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAssignmentReviewSettings
CanExtend : True
CreatedBy : admin@contoso.onmicrosoft.com
CreatedDateTime : 4/5/2022 11:53:36 AM
Description : Specific users can request assignment
DisplayName : Specific users
DurationInDays : 30
ExpirationDateTime :
Id : 4acf0d48-49b1-495b-816e-58933c9a9e64
ModifiedBy : admin@contoso.onmicrosoft.com
ModifiedDateTime : 4/5/2022 11:53:36 AM
Questions : {}
RequestApprovalSettings : Microsoft.Graph.PowerShell.Models.MicrosoftGraphApprovalSettings
RequestorSettings : Microsoft.Graph.PowerShell.Models.MicrosoftGraphRequestorSettings
AdditionalProperties : {[@odata.context, https://graph.microsoft.com/beta/$metadata#identityGovernance/entitlementManagement/accessPackageAssignmentPolicies/$entity]}
Step 3: Request access
In this step, Requestor1 user account you created in step 1 requests access to the resources in the access package.
To request access, you need to provide these values:
- TargetId - Specifies the ID of the Requestor1 user account that you created.
- AssignmentPolicyId - Specifies the ID of the assignment policy.
- AccessPackageId - Specifies the ID of the access package.
- RequestType - Specifies the type of request. For a non-administrator user to request to create their own assignment for either a first assignment or renew assignment, the value of the requestType property is
UserAdd.
New-MgBetaEntitlementManagementAccessPackageAssignmentRequest -RequestType 'UserAdd' -AccessPackageId '08173ced-8eae-4023-8433-cb85f29e7726' -AssignmentPolicyId '4acf0d48-49b1-495b-816e-58933c9a9e64' -TargetId '6c42590f-fcf0-4922-bac6-205f7c6aa89c'
Id CompletedDate CreatedDateTime ExpirationDateTime IsValidationOnly Justification RequestState RequestStatus RequestType
-- ------------- --------------- ------------------ ---------------- ------------- ------------ ------------- -----------
bff7d893-dc69-4f69-ae9f-24ce60531c37 False Submitted Accepted UserAdd
Step 4: Validate that access has been assigned
In this step, confirm that the Requestor1 user account was assigned the access package and that they're now a member of the Marketing resources group.
Use the administrator account to see the status of the request.
Get the status of the request
Use the Id property of the request to get the current status of it. The request state should be Delivered and request status Fulfilled.
Get-MgBetaEntitlementManagementAccessPackageAssignmentRequest -AccessPackageAssignmentRequestId '2276a78f-b1a1-471c-b69f-04649b2aaa92'| Format-List
AccessPackage : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackage
AccessPackageAssignment : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageAssignment
Answers : {}
CompletedDate : 4/5/2022 12:05:31 PM
CreatedDateTime : 4/5/2022 12:05:25 PM
ExpirationDateTime :
Id : 2276a78f-b1a1-471c-b69f-04649b2aaa92
IsValidationOnly : False
Justification :
RequestState : Delivered
RequestStatus : FulfilledNotificationTriggered
RequestType : UserAdd
Requestor : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageSubject1
Schedule : Microsoft.Graph.PowerShell.Models.MicrosoftGraphRequestSchedule
AdditionalProperties : {[@odata.context, https://graph.microsoft.com/beta/$metadata#identityGovernance/entitlementManagement/accessPackageAssignmentRequests/$entity], [customExtensionHandlerInstances, System.Object[]]}
Get access package assignments
Use the Id of the access package policy that you created to see that resources have been assigned to the Requestor1 user account.
Get-MgBetaEntitlementManagementAccessPackageAssignment -Filter "(AccessPackageAssignmentPolicy/Id eq '4acf0d48-49b1-495b-816e-58933c9a9e64')" | Format-List
AccessPackage : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackage
AccessPackageAssignmentPolicy : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageAssignmentPolicy
AccessPackageAssignmentRequests :
AccessPackageAssignmentResourceRoles :
AccessPackageId : 08173ced-8eae-4023-8433-cb85f29e7726
AssignmentPolicyId : 4acf0d48-49b1-495b-816e-58933c9a9e64
AssignmentState : Delivered
AssignmentStatus : Delivered
CatalogId : 88d3e491-5247-4209-9b56-c4c95d9694e9
ExpiredDateTime :
Id : eff960a2-6b20-4611-81c2-cb3d183584d9
IsExtended : False
Schedule : Microsoft.Graph.PowerShell.Models.MicrosoftGraphRequestSchedule
Target : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAccessPackageSubject1
TargetId : 6c42590f-fcf0-4922-bac6-205f7c6aa89c
AdditionalProperties : {}
Get the members of the group
After the request has been granted, you can use the Id that you recorded for the Marketing resources group to see that the Requestor1 user account has been added to it.
Get-MgGroupMember -GroupId '87553228-0d72-4138-890b-36e683f883b7'
Id DeletedDateTime
-- ---------------
6c42590f-fcf0-4922-bac6-205f7c6aa89c
Step 5: Clean up the resources
In this step, remove the changes you made and delete the Marketing Campaign access package.
Remove an access package assignment
You must delete any assignments to the access package before you can delete it. Use the Id of the assignment request that you recorded to delete the access package itself.
New-MgBetaEntitlementManagementAccessPackageAssignmentRequest -RequestType 'AdminRemove' -AccessPackageAssignmentId 'eff960a2-6b20-4611-81c2-cb3d183584d9'
Id CompletedDate CreatedDateTime ExpirationDateTime IsValidationOnly Justification RequestState RequestStatus RequestType
-- ------------- --------------- ------------------ ---------------- ------------- ------------ ------------- -----------
8b8e68a8-609c-4535-a9fd-f49713e46e6f False Submitted Accepted AdminRemove
Delete the access package assignment policy
To delete the assignment policy, use the Id of the assignment policy that you previously recorded. Make sure all assignments are removed first.
Remove-MgBetaEntitlementManagementAccessPackageAssignmentPolicy -AccessPackageAssignmentPolicyId '4acf0d48-49b1-495b-816e-58933c9a9e64'
Delete the access package
Use the Id of the access package that you previously recorded to delete it.
Remove-MgBetaEntitlementManagementAccessPackage -AccessPackageId '08173ced-8eae-4023-8433-cb85f29e7726'
Delete the user account
Delete the Requestor1 user account.
Remove-MgUser -UserId '6c42590f-fcf0-4922-bac6-205f7c6aa89c'
Delete the group
Delete the Marketing resources group.
Remove-MgGroup -GroupId '87553228-0d72-4138-890b-36e683f883b7'
Next steps
- Learn more on entitlement management.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for