Merge pull request #219724 from markwahl-msft/mwahl-gov-rolemig

identity governance: clarify roles in entitlement management

Author: prmerger-automator[bot]

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

@@ -32,7 +32,7 @@ With the separation of duties settings on an access package, you can configure t
 
 For example, you have an access package, *Marketing Campaign*, that people across your organization and other organizations can request access to, to work with your organization's marketing department while that campaign is going on. Since employees in the marketing department should already have access to that marketing campaign material, you don't want employees in the marketing department to request access to that access package.  Or, you may already have a dynamic group, *Marketing department employees*, with all of the marketing employees in it. You could indicate that the access package is incompatible with the membership of that dynamic group. Then, if a marketing department employee is looking for an access package to request, they couldn't request access to the *Marketing campaign* access package.
 
-Similarly, you may have an application with two roles - **Western Sales** and **Eastern Sales** - and want to ensure that a user can only have one sales territory at a time.  If you have two access packages, one access package **Western Territory** giving the **Western Sales** role and the other access package **Eastern Territory** giving the **Eastern Sales** role, then you can configure
+Similarly, you may have an application with two app roles - **Western Sales** and **Eastern Sales** - representing sales territories, and you want to ensure that a user can only have one sales territory at a time.  If you have two access packages, one access package **Western Territory** giving the **Western Sales** role and the other access package **Eastern Territory** giving the **Eastern Sales** role, then you can configure
  - the **Western Territory** access package has the **Eastern Territory** package as incompatible, and
  - the **Eastern Territory** access package has the **Western Territory** package as incompatible.
 
@@ -179,7 +179,7 @@ If there's an exceptional situation where separation of duties rules might need
 
 For example, if there was a scenario that some users would need to have access to both production and deployment environments at the same time, you could create a new access package **Production and development environments**.  That access package could have as its resource roles some of the resource roles of the **Production environment** access package and some of the resource roles of the **Development environment** access package.  
 
-If the motivation of the incompatible access is one resource's roles are particularly problematic, then that resource could be omitted from the combined access package, and require explicit administrator assignment of a user to the role.  If that is a third party application or your own application, then you can ensure oversight by monitoring those role assignments using the  *Application role assignment activity* workbook described in the next section.
+If the motivation of the incompatible access is one resource's roles are particularly problematic, then that resource could be omitted from the combined access package, and require explicit administrator assignment of a user to the resource's role.  If that is a third party application or your own application, then you can ensure oversight by monitoring those role assignments using the  *Application role assignment activity* workbook described in the next section.
 
 Depending on your governance processes, that combined access package could have as its policy either:
 

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

@@ -117,10 +117,10 @@ For more information, see [Compare groups](/office365/admin/create-groups/compar
 
 You can have Azure AD automatically assign users access to an Azure AD enterprise application, including both SaaS applications and your organization's applications integrated with Azure AD, when a user is assigned an access package. For applications that integrate with Azure AD through federated single sign-on, Azure AD will issue federation tokens for users assigned to the application.
 
-Applications can have multiple roles. When you add an application to an access package, if that application has more than one role, you'll need to specify the appropriate role for those users in each access package. If you're developing applications, you can read more about how those roles are added to your applications in [How to: Configure the role claim issued in the SAML token for enterprise applications](../develop/active-directory-enterprise-app-role-management.md).
+Applications can have multiple app roles defined in their manifest. When you add an application to an access package, if that application has more than one app role, you'll need to specify the appropriate role for those users in each access package. If you're developing applications, you can read more about how those roles are added to your applications in [How to: Configure the role claim issued in the SAML token for enterprise applications](../develop/active-directory-enterprise-app-role-management.md).
 
 > [!NOTE]
-> If an application has multiple roles, and more than one role of that application are in an access package, then the user will receive all the roles.  If instead you want users to only have some of the roles, then you will need to create multiple access packages in the catalog, with separate access packages for each of the roles.
+> If an application has multiple roles, and more than one role of that application are in an access package, then the user will receive all those application's roles.  If instead you want users to only have some of the application's roles, then you will need to create multiple access packages in the catalog, with separate access packages for each of the application roles.
 
 Once an application role is part of an access package:
 
@@ -129,7 +129,7 @@ Once an application role is part of an access package:
 
 Here are some considerations when selecting an application:
 
-- Applications may also have groups assigned to their roles as well.  You can choose to add a group in place of an application role in an access package, however then the application will not be visible to the user as part of the access package in the My Access portal.
+- Applications may also have groups assigned to their app roles as well.  You can choose to add a group in place of an application role in an access package, however then the application will not be visible to the user as part of the access package in the My Access portal.
 - Azure portal may also show service principals for services that cannot be selected as applications.  In particular, **Exchange Online** and **SharePoint Online** are services, not applications that have resource roles in the directory, so they cannot be included in an access package.  Instead, use group-based licensing to establish an appropriate license for a user who needs access to those services.
 - Applications which only support Personal Microsoft Account users for authentication, and do not support organizational accounts in your directory, do not have application roles and cannot be added to access package catalogs.
 

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

@@ -23,6 +23,14 @@ ms.collection: M365-identity-device-management
 
 # Delegation and roles in Azure AD entitlement management
 
+In Azure AD, you can use role models to manage access at scale through identity governance.
+
+ * You can use access packages to represent organizational roles in your organization, such as "sales representative". An access package representing that enterprise role would include all the access rights that a sales representative might typically need, across multiple resources.
+ * Applications [can define their own roles](../develop/howto-add-app-roles-in-azure-ad-apps.md). For example, if you had a sales application, and that application included the app role "salesperson", you could then [include that role in an access package](entitlement-management-access-package-resources.md).
+ * You can use roles for delegating administrative access.  If you have a catalog for all the access packages needed by sales, you could assign someone to be responsible for that catalog, by assigning them a catalog-specific role.
+
+This article discusses how to use roles to manage aspects within Azure AD entitlement management.
+
 By default, Global administrators and Identity governance administrators can create and manage all aspects of Azure AD entitlement management. However, the users in these roles may not know all the situations where access packages are required. Typically it's users within the respective departments, teams, or projects who know who they're collaborating with, using what resources, and for how long. Instead of granting unrestricted permissions to non-administrators, you can grant users the least permissions they need to do their job and avoid creating conflicting or inappropriate access rights.
 
 This video provides an overview of how to delegate access governance from IT administrator to users who aren't administrators.
@@ -49,9 +57,9 @@ Here is one way that Hana could delegate access governance to the marketing, fin
 
 1. Mamta creates a **Marketing** catalog, which is a container of resources.
 
-1. Mamta adds the resources that her marketing department owns to this catalog.
+1. Mamta adds the resources that the marketing department owns to this catalog.
 
-1. Mamta can add other people from her department as catalog owners for this catalog, which helps share the catalog management responsibilities.
+1. Mamta can add other people from that department as catalog owners for this catalog, which helps share the catalog management responsibilities.
 
 1. Mamta can further delegate the creation and management of access packages in the Marketing catalog to project managers in the Marketing department. She can do this by assigning them to the access package manager role. An access package manager can create and manage access packages. 
 
@@ -61,7 +69,7 @@ The following diagram shows catalogs with resources for the marketing, finance,
 
 After delegation, the marketing department might have roles similar to the following table.
 
-| User | Job role | Azure AD role | Entitlement management role |
+| User | Organizational role | Azure AD role | Entitlement management role |
 | --- | --- | --- | --- |
 | Hana | IT administrator | Global administrator or Identity Governance administrator  |  |
 | Mamta | Marketing manager | User | Catalog creator and Catalog owner |
@@ -70,13 +78,13 @@ After delegation, the marketing department might have roles similar to the follo
 
 ## Entitlement management roles
 
-Entitlement management has the following roles that apply across all catalogs.
+Entitlement management has the following roles, with permissions for administering entitlement management itself, that apply across all catalogs.
 
 | Entitlement management role | Role definition ID | Description |
 | --- | --- | -- |
 | Catalog creator | `ba92d953-d8e0-4e39-a797-0cbedb0a89e8` | Create and manage catalogs. Typically an IT administrator who isn't a Global administrator, or a resource owner for a collection of resources. The person that creates a catalog automatically becomes the catalog's first catalog owner, and can add more catalog owners. A catalog creator can’t manage or see catalogs that they don’t own and can’t add resources they don’t own to a catalog. If the catalog creator needs to manage another catalog or add resources they don’t own, they can request to be a co-owner of that catalog or resource. |
 
-Entitlement management has the following roles that are defined for each particular catalog.  An administrator or a catalog owner can add users, groups of users, or service principals to these roles.
+Entitlement management has the following roles that are defined for each particular catalog, for administering access packages and other configuration within a catalog.  An administrator or a catalog owner can add users, groups of users, or service principals to these roles.
 
 | Entitlement management role | Role definition ID | Description |
 | --- | --- | -- |
@@ -92,7 +100,7 @@ Also, the chosen approver and a requestor of an access package have rights, alth
 | Approver | Authorized by a policy to approve or deny requests to access packages, though they can't change the access package definitions. |
 | Requestor | Authorized by a policy of an access package to request that access package. |
 
-The following table lists the tasks that the entitlement management roles can do.
+The following table lists the tasks that the entitlement management roles can do within entitlement management.
 
 | Task | Admin | Catalog creator | Catalog owner | Access package manager | Access package assignment manager |
 | --- | :---: | :---: | :---: | :---: | :---: |
@@ -125,7 +133,7 @@ A Global administrator can add or remove any group (cloud-created security group
 > [!NOTE]
 > Users that have been assigned the User administrator role will no longer be able to create catalogs or manage access packages in a catalog they do not own. If users in your organization have been assigned the User administrator role to configure catalogs, access packages, or policies in entitlement management, you should instead assign these users the **Identity Governance administrator** role.
 
-For a user who isn't a global administrator, to add groups, applications, or SharePoint Online sites to a catalog, that user must have *both* an Azure AD directory role or ownership of the resource, and a and catalog owner entitlement management role for the catalog. The following table lists the role combinations that are required to add resources to a catalog. To remove resources from a catalog, you must have the same roles.
+For a user who isn't a global administrator, to add groups, applications, or SharePoint Online sites to a catalog, that user must have *both* an Azure AD directory role or ownership of the resource, and a catalog owner entitlement management role for the catalog. The following table lists the role combinations that are required to add resources to a catalog. To remove resources from a catalog, you must have the same roles.
 
 | Azure AD directory role | Entitlement management role | Can add security group | Can add Microsoft 365 Group | Can add app | Can add SharePoint Online site |
 | --- | :---: | :---: | :---: | :---: | :---: |
@@ -141,11 +149,11 @@ For a user who isn't a global administrator, to add groups, applications, or Sha
 
 To determine the least privileged role for a task, you can also reference [Administrator roles by admin task in Azure Active Directory](../roles/delegate-by-task.md#entitlement-management).
 
-## Manage role assignments programmatically (preview)
+## Manage role assignments to entitlement management roles programmatically (preview)
 
 You can also view and update catalog creators and entitlement management catalog-specific role assignments using Microsoft Graph.  A user in an appropriate role with an application that has the delegated `EntitlementManagement.ReadWrite.All` permission can call the Graph API to [list the role definitions](/graph/api/rbacapplication-list-roledefinitions) of entitlement management, and [list role assignments](/graph/api/rbacapplication-list-roleassignments) to those role definitions.
 
-For example, to view the entitlement management-specific roles which a particular user or group has been assigned, use the Graph query to list role assignments, and provide the user or group's ID as the value of the `principalId` query filter, as in
+For example, to view the entitlement management-specific roles that a particular user or group has been assigned, use the Graph query to list role assignments, and provide the user or group's ID as the value of the `principalId` query filter, as in
 
 ```http
 GET https://graph.microsoft.com/beta/roleManagement/entitlementManagement/roleAssignments?$filter=principalId eq '10850a21-5283-41a6-9df3-3d90051dd111'&$expand=roleDefinition&$select=id,appScopeId,roleDefinition