Merge pull request #199085 from markwahl-msft/mwahl-em-auto-2

public preview of azure ad entitlement management: auto assignment

Author: v-regandowner

articles/active-directory/governance/TOC.yml

@@ -112,6 +112,8 @@
         href: entitlement-management-access-package-approval-policy.md
       - name: Change lifecycle settings
         href: entitlement-management-access-package-lifecycle-policy.md
+      - name: Configure automatic assignment
+        href: entitlement-management-access-package-auto-assignment-policy.md
       - name: Configure separation of duties
         href: entitlement-management-access-package-incompatible.md
       - name: View and remove requests

articles/active-directory/governance/entitlement-management-access-package-auto-assignment-policy.md

@@ -0,0 +1,73 @@
+---
+title: Configure an automatic assignment policy for an access package in Azure AD entitlement management - Azure Active Directory
+description: Learn how to configure automatic assignments based on rules for an access package in Azure Active Directory entitlement management.
+services: active-directory
+documentationCenter: ''
+author: markwahl-msft
+manager: karenhoran
+editor: 
+ms.service: active-directory
+ms.workload: identity
+ms.tgt_pltfrm: na
+ms.topic: how-to
+ms.subservice: compliance
+ms.date: 08/15/2022
+ms.author: owinfrey
+ms.reviewer: mwahl
+ms.collection: M365-identity-device-management
+
+
+#Customer intent: As an administrator, I want detailed information about how I can edit an access package to include a policy for users to get and lose access package assignments automatically, without them or an administrator needing to request access.
+
+---
+# Configure an automatic assignment policy for an access package in Azure AD entitlement management (Preview)
+
+You can use rules to determine access package assignment based on user properties in Azure Active Directory (Azure AD), part of Microsoft Entra.  In Entitlement Management, an access package can have multiple policies, and each policy establishes how users get an assignment to the access package, and for how long.  As an administrator, you can establish a policy for automatic assignments by supplying a membership rule, that Entitlement Management will follow to create and remove assignments automatically.  Similar to a [dynamic group](../enterprise-users/groups-create-rule.md), when an automatic assignment policy is created, user attributes are evaluated for matches with the policy's membership rule. When an attribute changes for a user, these automatic assignment policy rules in the access packages are processed for membership changes. Assignments to users are then added or removed depending on whether they meet the rule criteria.
+
+During this preview, you can have at most one automatic assignment policy in an access package.
+
+This article describes how to create an access package automatic assignment policy for an existing access package.
+
+## Create an automatic assignment policy (Preview)
+
+To create a policy for an access package, you need to start from the access package's policy tab. Follow these steps to create a new policy for an access package.
+
+**Prerequisite role:** Global administrator, Identity Governance administrator, Catalog owner, or Access package manager
+
+1. In the Azure portal, click **Azure Active Directory** and then click **Identity Governance**.
+
+1. In the left menu, click **Access packages** and then open the access package.
+
+1. Click **Policies** and then **Add auto-assignment policy** to create a new policy.
+
+1. In the first tab, you'll specify the rule.  Click **Edit**.
+
+1. Provide a dynamic membership rule, using the [membership rule builder](../enterprise-users/groups-dynamic-membership.md) or by clicking **Edit** on the rule syntax text box.
+
+   > [!NOTE]
+   > The rule builder might not be able to display some rules constructed in the text box. For more information, see [rule builder in the Azure portal](/enterprise-users/groups-create-rule.md#rule-builder-in-the-azure-portal).
+
+    ![Screenshot of an access package automatic assignment policy rule configuration.](./media/entitlement-management-access-package-auto-assignment-policy/auto-assignment-rule-configuration.png)
+
+1. Click **Save** to close the dynamic membership rule editor, then click **Next** to open the **Custom Extensions** tab.
+
+1. If you have [custom extensions](entitlement-management-logic-apps-integration.md) in your catalog you wish to have run when the policy assigns or removes access, you can add them to this policy.  Then click next to open the **Review** tab.
+
+1. Type a name and a description for the policy.
+
+    ![Screenshot of an access package automatic assignment policy review tab.](./media/entitlement-management-access-package-auto-assignment-policy/auto-assignment-review.png)
+
+1. Click **Create** to save the policy.
+
+   > [!NOTE]
+   > In this preview, Entitlement management will automatically create a dynamic security group corresponding to each policy, in order to evaluate the users in scope. This group should not be modified except by Entitlement Management itself.  This group may also be modified or deleted automatically by Entitlement Management, so don't use this group for other applications or scenarios.
+
+1. Azure AD will evaluate the users in the organization that are in scope of this rule, and create assignments for those users who don't already have assignments to the access package.  It may take several minutes for the evaluation to occur, or for subsequent updates to user's attributes to be reflected in the access package assignments.
+
+## Create an automatic assignment policy programmatically (Preview)
+
+You can also create a policy using Microsoft Graph. A user in an appropriate role with an application that has the delegated `EntitlementManagement.ReadWrite.All` permission, or an application in a catalog role or with the `EntitlementManagement.ReadWrite.All` permission, can call the [create an accessPackageAssignmentPolicy](/graph/api/entitlementmanagement-post-assignmentpolicies?tabs=http&view=graph-rest-1.0&preserve-view=true) API.  In your [request payload](/graph/api/resources/accesspackageassignmentpolicy?view=graph-rest-1.0&preserve-view=true), include the `displayName`, `description`, `specificAllowedTargets`, [`automaticRequestSettings`](/graph/api/resources/accesspackageautomaticrequestsettings?view=graph-rest-1.0&preserve-view=true) and `accessPackage` properties of the policy.
+
+## Next steps
+
+- [View assignments for an access package](entitlement-management-access-package-assignments.md)

articles/active-directory/governance/entitlement-management-access-package-request-policy.md

@@ -30,9 +30,11 @@ The way you specify who can request an access package is with a policy. Before c
 
 When you create an access package, you can specify the request, approval and lifecycle settings, which are stored on the first policy of the access package. Most access packages will have a single policy for users to request access, but a single access package can have multiple policies. You would create multiple policies for an access package if you want to allow different sets of users to be granted assignments with different request and approval settings.
 
-For example, a single policy cannot be used to assign internal and external users to the same access package. However, you can create two policies in the same access package, one for internal users and one for external users. If there are multiple policies that apply to a user, they will be prompted at the time of their request to select the policy they would like to be assigned to. The following diagram shows an access package with two policies.
+For example, a single policy cannot be used to assign internal and external users to the same access package. However, you can create two policies in the same access package, one for internal users and one for external users. If there are multiple policies that apply to a user to request, they will be prompted at the time of their request to select the policy they would like to be assigned to. The following diagram shows an access package with two policies.
 
-![Multiple policies in an access package](./media/entitlement-management-access-package-request-policy/access-package-policy.png)
+![Diagram that illustrates multiple policies, along with multiple resource roles, can be contained within an access package.](./media/entitlement-management-access-package-request-policy/access-package-policy.png)
+
+In addition to policies for users to request access, you can also have policies for [automatic assignment](entitlement-management-access-package-auto-assignment-policy.md), and policies for direct assignment by administrators or catalog owners.
 
 ### How many policies will I need?
 
@@ -43,7 +45,8 @@ For example, a single policy cannot be used to assign internal and external user
 | I want to allow users in my directory and also users outside my directory to request an access package | Two |
 | I want to specify different approval settings for some users | One for each group of users |
 | I want some users access package assignments to expire while other users can extend their access | One for each group of users |
-| I want users to request access and other users to be assigned access by an administrator | Two |
+| I want some users to request access and other users to be assigned access by an administrator | Two |
+| I want some users in my organization to receive access automatically, other users in my organization to be able to request, and other users to be assigned access by an administrator | Three |
 
 For information about the priority logic that is used when multiple policies apply, see [Multiple policies](entitlement-management-troubleshoot.md#multiple-policies
 ).
@@ -105,7 +108,7 @@ Follow these steps if you want to allow users in your directory to be able to re
 
 ## 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 be allow invitations in **Collaboration restrictions**. For more information, see [Configure external collaboration settings](../external-identities/external-collaboration-settings-configure.md).
+ **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](../external-identities/external-collaboration-settings-configure.md).
 
 > [!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](../external-identities/user-properties.md).
@@ -206,6 +209,10 @@ To change the request and approval settings for an access package, you need to o
 
 1. If you are editing a policy click **Update**. If you are adding a new policy, click **Create**.
 
+## Creating an access package assignment policy programmatically
+
+You can also create a policy using Microsoft Graph. A user in an appropriate role with an application that has the delegated `EntitlementManagement.ReadWrite.All` permission, or an application in a catalog role or with the `EntitlementManagement.ReadWrite.All` permission, can call the [create an accessPackageAssignmentPolicy](/graph/api/entitlementmanagement-post-assignmentpolicies?tabs=http&view=graph-rest-1.0&preserve-view=true) API.
+
 ## Prevent requests from users with incompatible access
 
 In addition to the policy checks on who can request, you may wish to further restrict access, in order to avoid a user who already has some access - via a group or another access package - from obtaining excessive access.

articles/active-directory/governance/entitlement-management-overview.md

@@ -50,6 +50,7 @@ Azure AD entitlement management can help address these challenges.  To learn mor
 Here are some of capabilities of entitlement management:
 
 - Control who can get access to applications, groups, Teams and SharePoint sites, with multi-stage approval, and ensure users don't retain access indefinitely through time-limited assignments and recurring access reviews.
+- Give users access automatically to those resources, based on the user's properties like department or cost center, and remove a user's access when those properties change (preview).
 - Delegate to non-administrators the ability to create access packages. These access packages contain resources that users can request, and the delegated access package managers can define policies with rules for which users can request, who must approve their access, and when access expires.
 - Select connected organizations whose users can request access.  When a user who isn't yet in your directory requests access, and is approved, they're automatically invited into your directory and assigned access.  When their access expires, if they have no other access package assignments, their B2B account in your directory can be automatically removed.
 
@@ -93,7 +94,7 @@ You can have policies for users to request access. In these kinds of policies, a
 - The approval process and the users that can approve or deny access
 - The duration of a user's access assignment, once approved, before the assignment expires
 
-You can also have policies for users to be assigned access, either by an administrator or automatically.
+You can also have policies for users to be assigned access, either by an administrator or [automatically](entitlement-management-access-package-auto-assignment-policy.md).
 
 The following diagram shows an example of the different elements in entitlement management. It shows one catalog with two example access packages.
 
@@ -143,17 +144,17 @@ Specialized clouds, such as Azure Germany, and Azure China 21Vianet, aren't curr
 
 Ensure that your directory has at least as many Azure AD Premium P2 licenses as you have:
 
-- Member users who **can** request an access package.
-- Member users who <u>request</u> an access package.
-- Member users who <u>approve requests</u> for an access package.
-- Member users who <u>review assignments</u> for an access package. 
-- Member users who have a <u>direct assignment</u> to an access package.
+- Member users who *can* request an access package.
+- Member users who *request* an access package.
+- Member users who *approve requests* for an access package.
+- Member users who *review assignments* for an access package.
+- Member users who have a *direct assignment* or an *automatic assignment* to an access package.
 
 For guest users, licensing needs will depend on the [licensing model](../external-identities/external-identities-pricing.md) you’re using. However, the below guest users’ activities are considered Azure AD Premium P2 usage:
-- Guest users who <u>request</u> an access package. 
-- Guest users who <u>approve requests</u> for an access package.
-- Guest users who <u>review assignments</u> for an access package.
-- Guest users who have a <u>direct assignment</u> to an access package. 
+- Guest users who *request* an access package.
+- Guest users who *approve requests* for an access package.
+- Guest users who *review assignments* for an access package.
+- Guest users who have a *direct assignment* to an access package.
 
 Azure AD Premium P2 licenses are **not** required for the following tasks:
 

articles/active-directory/governance/entitlement-management-scenarios.md

@@ -47,6 +47,12 @@ There are several ways that you can configure entitlement management for your or
 
 ## Govern access for users in your organization
 
+### Administrator: Assign employees access automatically (preview)
+
+1. [Create a new access package](entitlement-management-access-package-create.md#start-new-access-package)
+1. [Add groups, Teams, applications, or SharePoint sites to access package](entitlement-management-access-package-create.md#resource-roles)
+1. [Add an automatic assignment policy](entitlement-management-access-package-auto-assignment-policy.md)
+
 ### Access package manager: Allow employees in your organization to request access to resources
 
 1. [Create a new access package](entitlement-management-access-package-create.md#start-new-access-package)
@@ -151,7 +157,7 @@ There are several ways that you can configure entitlement management for your or
 
 ## Programmatic administration
 
-You can also manage access packages, catalogs, policies, requests and assignments 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 [entitlement management API](/graph/tutorial-access-package-api).  An application with those application permissions can also use many of those API functions, with the exception of managing resources in catalogs and access packages. An an applications which only needs to operate within specific catalogs, can be added to the **Catalog owner** or **Catalog reader** roles of a catalog to be authorized to update or read within that catalog.
+You can also manage access packages, catalogs, policies, requests and assignments 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 [entitlement management API](/graph/tutorial-access-package-api).  An application with those application permissions can also use many of those API functions, with the exception of managing resources in catalogs and access packages. And an application which only needs to operate within specific catalogs can be added to the **Catalog owner** or **Catalog reader** roles of a catalog to be authorized to update or read within that catalog.
 
 ## Next steps
 

articles/active-directory/governance/identity-governance-overview.md

@@ -109,6 +109,7 @@ Once you've started using these identity governance features, you can easily aut
 | Creating, updating and deleting AD and Azure AD user accounts automatically for employees |[Plan cloud HR to Azure AD user provisioning](../app-provisioning/plan-cloud-hr-provision.md)|
 | Updating the membership of a group, based on changes to the member user's attributes | [Create a dynamic group](../enterprise-users/groups-create-rule.md)|
 | Assigning licenses | [group-based licensing](../enterprise-users/licensing-groups-assign.md) |
+| Adding and removing a user's group memberships, application roles, and SharePoint site roles, based on changes to the user's attributes | [Configure an automatic assignment policy for an access package in entitlement management](entitlement-management-access-package-auto-assignment-policy.md) (preview)|
 | Adding and removing a user's group memberships, application roles, and SharePoint site roles, on a specific date | [Configure lifecycle settings for an access package in entitlement management](entitlement-management-access-package-lifecycle-policy.md)|
 | Running custom workflows when a user requests or receives access, or access is removed | [Trigger Logic Apps in entitlement management](entitlement-management-logic-apps-integration.md) (preview) |
 | Regularly having memberships of guests in Microsoft groups and Teams reviewed, and removing guest memberships that are denied |[Create an access review](create-access-review.md) |