Get started with Azure AD entitlement management automation

What is entitlement management in Azure Active Directory?

Entitlement management oversees access assignments and reviews, expiration configuration and automation of the access request workflows. It is part of the Identity Governance feature within Azure AD to manage and control the access management lifecycle.

Nearly all organizations struggle with the same challenges to control internal and external resource access. Often, users may not know what they have access to -- and what they should have. Many times, users keep access to resources beyond what is necessary. These problems are compounded when external users require access until a project has been completed.

Azure AD entitlement management addresses these issues through the functionality to:

• create access packages;
• delegate ownership and control of the access packages;
• create policies with rules to let users request access;
• define who approves access and when the designated access expires; and
• allow affiliated organizations users to request access.

Entitlement management requires an Azure AD Premium P2 license. The license coverage depends on the scenario:  

• users with permission to request access packages;
• users who perform the actual request for access packages;
• users who can approve requests made to a particular access package;
• reviews of the user assignment requests made to an access package; and
• users directly granted access to specific access packages.

External users who perform specific actions will also require Premium P2 licensing, such as these actions: 

• guest users who can request an access package of resources;
• approvers of access requests for packages;
• guest users who review access package user assignments; and
• guest users with direct assignments to an access package.

Global administrators do not need an Azure AD Premium P2 license to perform the following tasks: 

• create catalogs
• create access package
• define policies
• delegate tasks

Understanding access packages

Access packages are a combination of resources that internal and external users need for work. A typical access package contains security groups, applications from Azure, SharePoint Online sites and the policies controlling access for the specified accounts. Packages can control the following:

• memberships of Azure AD security groups;
• user memberships for Microsoft 365 Groups and Microsoft Teams;
• user assignments for Azure AD applications; and
• membership of SharePoint Online sites.

An added benefit of using access packages is to assign licenses and manage role assignment access.

How policies work in access packages

An administration account defines the resources -- security groups, applications, sites and user roles – required. Access packages include either single or multiple policies. A policy represents the controls for assignment to the access package. Every policy ensures that only the appropriate users can request access and be approved, and that the access is limited based on the policy.

Within each defined policy, an administrator or access package manager controls:

• both internal and external users suitable for requesting access;
• the approvers for the requests;
• duration of an access assignment; and
• access assignment expiration.

How to use the Microsoft Graph for Azure AD entitlement management automation

The GUI management for entitlement management resides in the Azure portal, but understanding how to work with the Microsoft Graph APIs to execute identity governance actions is another way to perform the same tasks.

Before you can create access packages, you need to set the proper permissions by executing the following steps:

1. Navigate to the Graph Explorer URL: https://developer.microsoft.com/en-us/graph/graph-explorer.
2. Log in with a Global Administrator account.
3. Click the ellipsis icon by the account login and choose Select Permissions.
4. Select the User.ReadWrite.All, Group.ReadWrite.All and EntitlementManagement.ReadWrite.All permissions.
5. Consent to the permissions by selecting the Consent on behalf of your organization option.

Now with the proper permissions in place, you can create a user account and security group for the access package from the Graph Explorer, the tool you use to make requests and see responses against the Microsoft Graph REST API.

You will need to set the required URL. The method needs to be POST rather than GET because this creates or updates a resource. The content type will be application/json and then you will add the required body JSON to the Request body field and press the Run query button.

# Create User

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
"accountEnabled":true,
"displayName":"RequestAccount1",
"mailNickname":"RequestAccount1",
"userPrincipalName":"[email protected]",
"passwordProfile": {
"forceChangePasswordNextSignIn":true,
"password":"RequestPassword2021"
}
}

# Create Security Group

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
"description":"Access Package Group",
"displayName":"Access Package Group",
"mailEnabled":false,
"mailNickname":"accesspackagegrp",
"securityEnabIed":true
}

Save the unique IDs created for both the user and the group for later use.

Via the Graph Explorer, you can update the catalog with the resource by retrieving the catalog identifier, adding the group created earlier to the catalog, retrieving the catalog resource ID, getting the resource roles and making the access package to perform any assignments required.

# Retrieve the Catalog Identifier

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

Copy the Id of the catalog.

# Add the Group to the Retrieved Catalog

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

{
"catalogId":"4411c97c-eebb-43b4—93c1—b3e62a82c94d",
"requestType": "AdminAdd",
"justification": "",
"accessPackageResource": {
"displayName": "Access Package Group",
"description": "Access Package Group",
"resourceType": "AadGroup",
"originId": "e8b8680a-2b18-4810-bdff-96394b1658b8",
"originSystem": "AadGroup"
}
}

The Identity Governance component within the Azure portal will now display a single resource you can see by clicking into Catalog.

Clicking further will show the security group that was added by using the Graph API.

Execute the following to fetch the catalog details and the assigned security group.

# Retrieve the Catalog Resources

GET https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageCatalogs/4411c97c-eebb-43b4-93c1-b3e62a82c94d/accessPackageResources?$filter=(displayName eq 'Access Package Group')

 With all the resources in place, create the access package.

# Create the Access Package

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

{
"catalogId": "4411c97c-eebb-43b4-93c1-b3e62a82c94d",
"displayName": "Access Package Test",
"description": "Access Package Test"
}

 In the Identity Governance console within the Azure portal, click Access packages to show the new access package associated with the catalog and the specific role.

With the access package created, you can use the Graph API to show the access packages with information about the request types.

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

{
"requestType": "UserAdd",
"accessPackageAssignment": {
"targetId": "071cda8b—4171-4b7a—9708—588c58e54436",
"assignmentPolicyId": "83c0379f—f484-4621—8aa5-693f4df8f15a",
"accessPackageId": "168b4936-14b8-4634—9cfe—ccea6433c902"
}
}

In the Identity Governance console within the Azure portal, click on Access Packages, then choose the new access package. You can click into Assignments and see the requester account assigned the required permission.

While the Graph Explorer and Microsoft Graph APIs work as expected, the process is not simple and requires storing values for later use. Another method to ease this process is to build a PowerShell script that can be modified for future use.

Using the Microsoft Graph PowerShell for entitlement management

Administrators who want a more efficient method can also use Microsoft Graph PowerShell commands to handle these Azure AD entitlement management tasks.

To start, install the Microsoft Graph Identity Governance module for the necessary cmdlets to run entitlement management commands:

Install-Module -Name Microsoft.Graph.Identity.Governance

Identity governance is a complicated subject, and the module features more than 250 cmdlets. The following Microsoft site provides reference material for each command.  

The following script has several commands with notes for each section that create the access package without the need to execute multiple Graph API posts and retrievals from the Graph Explorer. The opening commands show how to get the user ID from the User Principal Name, which typically is the user's email address.

# Retrieve the user and group

$userid = (Get-MgUser -ConsistencyLevel eventual -Search '"UserPrincipalName:[email protected]"').Id

$user = Get-MgUser -UserId $userid
$group = Get-MgGroup -Filter "DisplayName eq 'Access Package Group'"

# Get the catalog

$catalog = Get-MgEntitlementManagementAccessPackageCatalog -Filter "DisplayName eq 'General'"

# Add the group to the catalog

$accessPackageResource = @{
  "originSystem" = "AadGroup "
  OriginId = "e8b8680a-2b18-4810-bdff-96394b1658b8"
}

$groupresource  = New-MgEntitlementManagementAccessPackageResourceRequest -CatalogId '4411c97c-eebb-43b4-93c1-b3e62a82c94d' -RequestType "AdminAdd" -AccessPackageResource $accessPackageResource

$packageresource = Get-MgEntitlementManagementAccessPackageCatalogAccessPackageResource -AccessPackageCatalogId '4411c97c-eebb-43b4-93c1-b3e62a82c94d' -Filter "DisplayName eq 'Access Package Group'"

$packagemember = Get-MgEntitlementManagementAccessPackageCatalogAccessPackageResourceRole -AccessPackageCatalogId '4411c97c-eebb-43b4-93c1-b3e62a82c94d' -Filter "originSystem eq 'AadGroup' and accessPackageResource/id eq 'f1ead293-dbf2-4891-9ac3-cec6c0b9474c' and DisplayName eq 'Member'"

# Create the Access Package

$accesspackage = New-MgEntitlementManagementAccessPackage -CatalogId '4411c97c-eebb-43b4-93c1-b3e62a82c94d'  -DisplayName 'Access Package Test'

To finish creating the access package, you can use the following commands: 

New-MgEntitlementManagementAccessPackageResourceRoleScope

New-MgEntitlementManagementAccessPackageAssignmentPolicy

These commands work the same as the Graph API calls to add groups, users and resources to the access package. After completing this, you can then issue an access request using PowerShell. 

New-MgEntitlementManagementAccessPackageAssignmentRequest -RequestType 'UserAdd' -AccessPackageId '0ec82874-dc98-485a-94be-1acfbe4af734' -AssignmentPolicyId '39f60c26-beaf-4f97-ba7f-ef1be762f5d4' -TargetId '071cda8b-4171-4b7a-9708-588c58e54436'

The Microsoft Graph PowerShell commands are more straightforward and have the added advantage of creating variables for the reusable values for easier management.