Create a new access package in entitlement management
An access package enables you to do a one-time setup of resources and policies that automatically administers access for the life of the access package. This article describes how to create a new access package.
Overview
All access packages must be put in a container called a catalog. A catalog defines what resources you can add to your access package. If you don't specify a catalog, your access package will be put into the general catalog. Currently, you can't move an existing access package to a different catalog.
An access package can be used to assign access to roles of multiple resources that are in the catalog. If you're an administrator or catalog owner, you can add resources to the catalog while creating an access package. If you're an access package manager, you can't add resources you own to a catalog. You're restricted to using the resources available in the catalog. If you need to add resources to a catalog, you can ask the catalog owner.
All access packages must have at least one policy for users to be assigned to the access package. Policies specify who can request the access package and also approval and lifecycle settings. When you create a new access package, you can create an initial policy for users in your directory, for users not in your directory, for administrator direct assignments only, or you can choose to create the policy later.
Here are the high-level steps to create a new access package.
In Identity Governance, start the process to create a new access package.
Select the catalog you want to create the access package in.
Add resource roles from resources in the catalog to your access package.
Specify an initial policy for users that can request access.
Specify any approval settings.
Specify lifecycle settings.
Start new access package
Prerequisite role: Global administrator, Identity Governance administrator, User administrator, Catalog owner, or Access package manager
Sign in to the Azure portal.
Select Azure Active Directory and then select Identity Governance.
In the left menu, select Access packages.
Select New access package.
Basics
On the Basics tab, you give the access package a name and specify which catalog to create the access package in.
Enter a display name and description for the access package. Users will see this information when they submit a request for the access package.
In the Catalog drop-down list, select the catalog you want to create the access package in. For example, you might have a catalog owner that manages all the marketing resources that can be requested. In this case, you could select the marketing catalog.
You'll only see catalogs you have permission to create access packages in. To create an access package in an existing catalog, you must be either a Global administrator, Identity Governance administrator or User administrator, or you must be a catalog owner or access package manager in that catalog.
If you're a Global administrator, an Identity Governance administrator, a User administrator, or catalog creator and you would like to create your access package in a new catalog that's not listed, select Create new catalog. Enter the Catalog name and description and then select Create.
The access package you're creating, and any resources included in it, will be added to the new catalog. You can also add additional catalog owners later, and add attributes to the resources you put in the catalog. Read Add resource attributes in the catalog to learn more about how to edit the attributes list for a specific catalog resource and the prerequisite roles.
Select Next.
Resource roles
On the Resource roles tab, you select the resources to include in the access package. Users who request and receive the access package will receive all the resource roles, such as group membership, in the access package.
If you're not sure which resource roles to include, you can skip adding resource roles while creating the access package, and then add resource roles after you've created the access package.
Select the resource type you want to add (Groups and Teams, Applications, or SharePoint sites).
In the Select pane that appears, select one or more resources from the list.
If you're creating the access package in the General catalog or a new catalog, you'll be able to pick any resource from the directory that you own. You must be at least a Global administrator, a User administrator, or Catalog creator.
If you're creating the access package in an existing catalog, you can select any resource that is already in the catalog without owning it.
If you're a Global administrator, a User administrator, or catalog owner, you have the additional option of selecting resources you own that aren't yet in the catalog. If you select resources not currently in the selected catalog, these resources will also be added to the catalog for other catalog administrators to build access packages with. To see all the resources that can be added to the catalog, check the See all check box at the top of the Select pane. If you only want to select resources that are currently in the selected catalog, leave the check box See all unchecked (default state).
Once you've selected the resources, in the Role list, select the role you want users to be assigned for the resource. For more information on selecting the appropriate roles for a resource, read add resource roles.
Select Next.
Note
You can add dynamic groups to a catalog and to an access package. However, you will be able to select only the Owner role when managing a dynamic group resource in an access package.
Requests
On the Requests tab, you create the first policy to specify who can request the access package and also approval settings. Later, you can create more request policies to allow additional groups of users to request the access package with their own approval settings.
Depending on who you want to be able to request this access package, perform the steps in one of the following sections.
For users in your directory
Follow these steps if you want to allow users in your directory to be able to request this access package. When defining the request policy, you can specify individual users, or more commonly groups of users. For example, your organization may already have a group such as All employees. If that group is added in the policy for users who can request access, then any member of that group can then request access.
In the Users who can request access section, select For users in your directory.
When you select this option, new options appear to further refine who in your directory can request this access package.
Select one of the following options:
Description Specific users and groups Choose this option if you want only the users and groups in your directory that you specify to be able to request this access package. All members (excluding guests) Choose this option if you want all member users in your directory to be able to request this access package. This option doesn't include any guest users you might have invited into your directory. All users (including guests) Choose this option if you want all member users and guest users in your directory to be able to request this access package. Guest users refer to external users that have been invited into your directory with Azure AD B2B. For more information about the differences between member users and guest users, see What are the default user permissions in Azure Active Directory?.
If you selected Specific users and groups, select Add users and groups.
In the Select users and groups pane, select the users and groups you want to add.
Select Select to add the users and groups.
Skip down to the Approval section.
For users not in your directory
Users not in your directory refers to users who are in another Azure AD directory or domain. These users may not have yet been invited into your directory. Azure AD directories must be configured to allow invitations in Collaboration restrictions. For more information, see Configure external collaboration settings.
Note
A guest user account will be created for a user not yet in your directory whose request is approved or auto-approved. The guest will be invited, but will not receive an invite email. Instead, they will receive an email when their access package assignment is delivered. By default, later when that guest user no longer has any access package assignments, because their last assignment has expired or been cancelled, that guest user account will be blocked from sign in and subsequently deleted. If you want to have guest users remain in your directory indefinitely, even if they have no access package assignments, you can change the settings for your entitlement management configuration. For more information about the guest user object, see Properties of an Azure Active Directory B2B collaboration user.
Follow these steps if you want to allow users not in your directory to request this access package:
In the Users who can request access section, select For users not in your directory.
When you select this option, new options appear.
Select one of the following options:
Description Specific connected organizations Choose this option if you want to select from a list of organizations that your administrator previously added. All users from the selected organizations can request this access package. All connected organizations Choose this option if all users from all your connected organizations can request this access package. All users (All connected organizations + any new external users) Choose this option if all users from all your connected organizations can request this access package and that the B2B allow or blocklist settings should take precedence for any new external user. A connected organization is an external Azure AD directory or domain that you have a relationship with.
If you selected Specific connected organizations, select Add directories to select from a list of connected organizations that your administrator previously added.
Type the name or domain name to search for a previously connected organization.
If the organization you want to collaborate with isn't in the list, you can ask your administrator to add it as a connected organization. For more information, see Add a connected organization.
Once you've selected all your connected organizations, select Select.
Note
All users from the selected connected organizations will be able to request this access package. This includes users in Azure AD from all subdomains associated with the organization, unless those domains are blocked by the Azure B2B allow or block list. For more information, see Allow or block invitations to B2B users from specific organizations.
Skip down to the Approval section.
None (administrator direct assignments only)
Follow these steps if you want to bypass access requests and allow administrators to directly assign specific users to this access package. Users won't have to request the access package. You can still set lifecycle settings, but there are no request settings.
In the Users who can request access section, select None (administrator direct assignments only).
After you create the access package, you can directly assign specific internal and external users to the access package. If you specify an external user, a guest user account will be created in your directory. For information about directly assigning a user, see View, add, and remove assignments for an access package.
Skip down to the Enable requests section.
Approval
In the Approval section, you specify whether an approval is required when users request this access package. The approval settings work in the following way:
- Only one of the selected approvers or fallback approvers needs to approve a request for single-stage approval.
- Only one of the selected approvers from each stage needs to approve a request for 2-stage approval.
- The approver can be a Manager, Internal sponsor, or External sponsor depending on who the policy is governing access.
- Approval from every selected approver isn't required for single or 2-stage approval.
- The approval decision is based on whichever approver reviews the request first.
For a demonstration of how to add approvers to a request policy, watch the following video:
For a demonstration of how to add a multi-stage approval to a request policy, watch the following video:
Follow these steps to specify the approval settings for requests for the access package:
To require approval for requests from the selected users, set the Require approval toggle to Yes. Or, to have requests automatically approved, set the toggle to No.
To require users to provide a justification to request the access package, set the Require requestor justification toggle to Yes.
Now determine if requests will require single or 2-stage approval. Set the How many stages toggle to 1 for single stage approval or set the toggle to 2 for 2-stage approval.
Use the following steps to add approvers after selecting how many stages you require:
Single-stage approval
Add the First Approver:
If the policy is set to For users in your directory, you can select Manager as approver. Or, add a specific user by clicking Add approvers after selecting Choose specific approvers from the dropdown menu.
If this policy is set to For users not in your directory, you can select External sponsor or Internal sponsor. Or, add a specific user by clicking Add approvers or groups under Choose specific approvers.
If you selected Manager as the first approver, select Add fallback to select one or more users or groups in your directory to be a fallback approver. Fallback approvers receive the request if entitlement management can't find the manager for the user requesting access.
The manager is found by entitlement management using the Manager attribute. The attribute is in the user's profile in Azure AD. For more information, see Add or update a user's profile information using Azure Active Directory.
If you selected Choose specific approvers, select Add approvers to select one or more users or groups in your directory to be approvers.
In the box under Decision must be made in how many days?, specify the number of days that an approver has to review a request for this access package.
If a request isn't approved within this time period, it will be automatically denied. The user will have to submit another request for the access package.
To require approvers to provide a justification for their decision, set Require approver justification to Yes.
The justification is visible to other approvers and the requestor.
2-stage approval
If you selected a 2-stage approval, you'll need to add a second approver.
Add the Second Approver:
If the users are in your directory, add a specific user as the second approver by clicking Add approvers under Choose specific approvers.
If the users aren't in your directory, select Internal sponsor or External sponsor as the second approver. After selecting the approver, add the fallback approvers.
Specify the number of days the second approver has to approve the request in the box under Decision must be made in how many days?.
Set the Require approver justification toggle to Yes or No.
Alternate approvers
You can specify alternate approvers, similar to specifying the first and second approvers who can approve requests. Having alternate approvers will help ensure that the requests are approved or denied before they expire (timeout). You can list alternate approvers the first approver and second approver for 2-stage approval.
When you specify alternate approvers, if the first or second approvers were unable to approve or deny the request, the pending request gets forwarded to the alternate approvers. The request is sent per the forwarding schedule you specified during policy setup. They receive an email to approve or deny the pending request.
After the request is forwarded to the alternate approvers, the first or second approvers can still approve or deny the request. Alternate approvers use the same My Access site to approve or deny the pending request.
We can list people or groups of people to be approvers and alternate approvers. Ensure that you list different sets of people to be the first, second, and alternate approvers. For example, if you listed Alice and Bob as the First Approver(s), list Carol and Dave as the alternate approvers. Use the following steps to add alternate approvers to an access package:
Under the First Approver, Second Approver, or both, select Show advanced request settings.
Set If no action taken, forward to alternate approvers? toggle to Yes.
Select Add alternate approvers and select the alternate approver(s) from the list.
If you select Manager as approver for the First Approver, you'll have an extra option, Second level manager as alternate approver, available to choose in the alternate approver field. If you select this option, you need to add a fallback approver to forward the request to in case the system can't find the second level manager.
In the Forward to alternate approver(s) after how many days box, put in the number of days the approvers have to approve or deny a request. If no approvers have approved or denied the request before the request duration, the request expires (timeout). The user will then have to submit another request for the access package.
Requests can only be forwarded to alternate approvers a day after the request duration reaches half-life, and the decision of the main approver(s) has to time out after at least four days. If the request time-out is less or equal than 3, there isn't enough time to forward the request to alternate approver(s). In this example, the duration of the request is 14 days. So, the request duration reaches half-life at day 7. So the request can't be forwarded earlier than day 8. Also, requests can't be forwarded on the last day of the request duration. So in the example, the latest the request can be forwarded is day 13.
Enable requests
If you want the access package to be made immediately available for users in the request policy to request, move the Enable toggle to Yes.
You can always enable it in the future after you have finished creating the access package.
If you selected None (administrator direct assignments only) and you set enable to No, then administrators can't directly assign this access package.
Go to the verified ID requirement section section to learn how to add a verified ID requirement to your access package. Otherwise, select Next.
Add a Verified ID requirement (Preview)
Note
You will need to have a Global administrator role to add verified ID requirements to an access package. Identity Governance administrator, User administrator, Catalog owner, or Access package manager will be able to add verified ID requirements to access packages soon.
Follow these steps if you want to add a verified ID requirement to your access package policy. Users requesting access to the access package will need to present the required verified IDs before successfully submitting their request. You can learn more about how to configure your tenant with the Microsoft Entra Verified ID service here.
- Click + Add issuer and select an issuer from the Entra Verified ID network. If you want to issue your own credentials to users, you can find instructions on how to do that here.
- Select the credential type(s) you want users to present during the request process.
Note
If you select multiple credential types from one issuer, users will be required to present credentials of all selected types. Similarly, if you include multiple issuers, users will be required to present credentials from each of the issuers you include in the policy. To give users the option of presenting different credentials from various issuers, configure separate policies for each issuer/credential type you’ll accept.
- Click Add to add the verified ID requirement to the access package policy.
Add Requestor information to an access package
Go to the Requestor information tab and select the Questions sub tab.
Type in what you want to ask the requestor, also known as the display string, for the question in the Question box.
If you would like to add your own localization options, select add localization.
- Once in the Add localizations for question pane, select the language code for the language in which you're localizing the question.
- In the language you configured, type the question in the Localized Text box.
- Once you've added all the localizations needed, select Save.
Select the Answer format in which you would like requestors to answer. Answer formats include: Short text, Multiple choice, and long text.
If selecting multiple choice, select on the edit and localize button to configure the answer options.
- After selecting edit and localize, the View/edit question pane will open.
- Type in the response options you wish to give the requestor when answering the question in the Answer values boxes.
- Select the language for the response option. You can localize response options if you choose extra languages.
- Type in as many responses as you need then select Save.
To require requestors to answer this question when requesting access to an access package, select the check box under Required.
Select on the Attributes sub tab to view attributes associated with resources added to the access package.
Note
To add or update attributes for an access package's resources, go to Catalogs and find the catalog associated with the access package. Read Add resource attributes in the catalog to learn more about how to edit the attributes list for a specific catalog resource and the prerequisite roles.
Select Next
Lifecycle
On the Lifecycle tab, you specify when a user's assignment to the access package expires. You can also specify whether users can extend their assignments.
In the Expiration section, set Access package assignments expires to On date, Number of days, Number of hours, or Never.
- For On date, select an expiration date in the future.
- For Number of days, specify a number between 0 and 3660 days.
- For Number of hours, specify how many hours.
Based on your selection, a user's assignment to the access package expires on a certain date, some days after they're approved, or never.
If you want the user to request a specific start and end date for their access, select yes next to the Users can request specific timeline toggle.
Select Show advanced expiration settings to show more settings.
To allow user to extend their assignments, set Allow users to extend access to Yes.
If extensions are allowed in the policy, the user receives an email 14 days and also one day before their access package assignment is set to expire, prompting them to extend the assignment. The user must still be in the scope of the policy at the time they request an extension. Also, if the policy has an explicit end date for assignments, and a user submits a request to extend access, the extension date in the request must be at or before when assignments expire, as defined in the policy that was used to grant the user access to the access package. For example, if the policy indicates that assignments are set to expire on June 30, the maximum extension a user can request is June 30.
If a user's access is extended, they won't be able to request the access package after the specified extension date (date set in the time zone of the user who created the policy).
To require approval to grant an extension, set Require approval to grant extension to Yes.
The same approval settings that were specified on the Requests tab will be used.
Select Next or Update.
Review + create
On the Review + create tab, you can review your settings and check for any validation errors.
Review the access package's settings
Select Create to create the access package.
The new access package appears in the list of access packages.
Create an access package programmatically
There are two ways to create an access package programmatically, through Microsoft Graph and through the PowerShell cmdlets for Microsoft Graph.
Create an access package with Microsoft Graph
You can create an access package using Microsoft Graph. A user in an appropriate role with an application that has the delegated EntitlementManagement.ReadWrite.All permission can call the API to
- List the accessPackageResources in the catalog and create an accessPackageResourceRequest for any resources that aren't yet in the catalog.
- List the accessPackageResourceRoles of each accessPackageResource in an accessPackageCatalog. This list of roles will then be used to select a role, when later creating an accessPackageResourceRoleScope.
- Create an accessPackage.
- Create an accessPackageResourceRoleScope for each resource role needed in the access package.
- Create an accessPackageAssignmentPolicy for each policy needed in the access package.
Create an access package with Microsoft PowerShell
You can also create an access package in PowerShell with the cmdlets from the Microsoft Graph PowerShell cmdlets for Identity Governance module version 1.16.0 or later. This script illustrates using the Graph beta profile.
First, you would retrieve the ID of the catalog, and of the resources and their roles in that catalog that you wish to include in the access package, using a script similar to the following.
Connect-MgGraph -Scopes "EntitlementManagement.ReadWrite.All"
Select-MgProfile -Name "beta"
$catalog = Get-MgEntitlementManagementAccessPackageCatalog -Filter "displayName eq 'Marketing'"
$rsc = Get-MgEntitlementManagementAccessPackageCatalogAccessPackageResource -AccessPackageCatalogId $catalog.Id -Filter "resourceType eq 'Application'" -ExpandProperty "accessPackageResourceScopes"
$filt = "(originSystem eq 'AadApplication' and accessPackageResource/id eq '" + $rsc[0].Id + "')"
$rr = Get-MgEntitlementManagementAccessPackageCatalogAccessPackageResourceRole -AccessPackageCatalogId $catalog.Id -Filter $filt -ExpandProperty "accessPackageResource"
Then, create the access package.
$params = @{
CatalogId = $catalog.id
DisplayName = "sales reps"
Description = "outside sales representatives"
}
$ap = New-MgEntitlementManagementAccessPackage -BodyParameter $params
Once the access package has been created, assign the resource roles to the access package. For example, if you wished to include the second resource role of the first resource returned earlier as a resource role of the new access package, you would use a script similar to the following.
$rparams = @{
AccessPackageResourceRole = @{
OriginId = $rr[2].OriginId
DisplayName = $rr[2].DisplayName
OriginSystem = $rr[2].OriginSystem
AccessPackageResource = @{
Id = $rsc[0].Id
ResourceType = $rsc[0].ResourceType
OriginId = $rsc[0].OriginId
OriginSystem = $rsc[0].OriginSystem
}
}
AccessPackageResourceScope = @{
OriginId = $rsc[0].OriginId
OriginSystem = $rsc[0].OriginSystem
}
}
New-MgEntitlementManagementAccessPackageResourceRoleScope -AccessPackageId $ap.Id -BodyParameter $rparams
Finally, create the policies. In this policy, only the administrator can assign access, and there are no access reviews. See create an assignment policy through PowerShell and create an accessPackageAssignmentPolicy for more examples.
$pparams = @{
AccessPackageId = $ap.Id
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 = @(
)
}
}
New-MgEntitlementManagementAccessPackageAssignmentPolicy -BodyParameter $pparams
Next steps
Feedback
Submit and view feedback for