Merge pull request #220093 from markwahl-msft/mwahl-gov-rolmig2

identity governance: migrating an organizational role model to Azure AD

Author: liljack17

articles/active-directory/governance/TOC.yml

@@ -36,6 +36,8 @@
         href: entitlement-management-group-licenses.md
       - name: Onboard external users to Azure AD through an approval process
         href: entitlement-management-onboard-external-user.md
+      - name: Migrate an organizational role model
+        href: identity-governance-organizational-roles.md
     - name: Access Reviews
       items:
       - name: Review access to Microsoft 365 groups - Microsoft Graph

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

@@ -72,11 +72,11 @@ To create a policy for an access package, you need to start from the access pack
 
 There are two ways to create an access package assignment policy for automatic assignment programmatically, through Microsoft Graph and through the PowerShell cmdlets for Microsoft Graph.
 
-### Creating an access package assignment policy through Graph
+### Create an access package assignment policy through Graph
 
 You can 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.
 
-### Creating an access package assignment policy through PowerShell
+### Create an access package assignment policy through PowerShell
 
 You can also create a policy in PowerShell with the cmdlets from the [Microsoft Graph PowerShell cmdlets for Identity Governance](https://www.powershellgallery.com/packages/Microsoft.Graph.Identity.Governance/) module version 1.16.0 or later.
 

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

@@ -132,11 +132,11 @@ On the **Review + create** tab, you can review your settings and check for any v
 
     The new access package appears in the list of access packages.
 
-## Creating an access package programmatically
+## 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.
 
-### Creating an access package with 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
 
@@ -147,7 +147,7 @@ You can create an access package using Microsoft Graph. A user in an appropriate
 1. [Create an accessPackageAssignmentPolicy](/graph/api/entitlementmanagement-post-accesspackageassignmentpolicies?tabs=http&view=graph-rest-beta&preserve-view=true) for each policy needed in the access package.
 
 
-### Creating an access package with Microsoft PowerShell
+### 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](https://www.powershellgallery.com/packages/Microsoft.Graph.Identity.Governance/) module version 1.16.0 or later.  This script illustrates using the Graph `beta` profile.
 
@@ -197,7 +197,7 @@ $rparams = @{
 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](entitlement-management-access-package-request-policy.md#creating-an-access-package-assignment-policy-through-powershell) and [create an accessPackageAssignmentPolicy](/graph/api/entitlementmanagement-post-assignmentpolicies?tabs=http&view=graph-rest-beta&preserve-view=true) for more examples.
+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](entitlement-management-access-package-request-policy.md#create-an-access-package-assignment-policy-through-powershell) and [create an accessPackageAssignmentPolicy](/graph/api/entitlementmanagement-post-assignmentpolicies?tabs=http&view=graph-rest-beta&preserve-view=true) for more examples.
 
 ```powershell
 

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

@@ -209,19 +209,19 @@ 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
+## Create an access package assignment policy programmatically
 
 There are two ways to create an access package assignment policy programmatically, through Microsoft Graph and through the PowerShell cmdlets for Microsoft Graph.
 
-### Creating an access package assignment policy through Graph
+### Create an access package assignment policy through Graph
 
 You can 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.
 
-### Creating an access package assignment policy through PowerShell
+### Create an access package assignment policy through PowerShell
 
 You can also create an access package in PowerShell with the cmdlets from the [Microsoft Graph PowerShell cmdlets for Identity Governance](https://www.powershellgallery.com/packages/Microsoft.Graph.Identity.Governance/) module version 1.16.0 or later.  
 
-This script below illustrates using the `beta` profile, to create a policy for direct assignment to an access package. In this policy, only the administrator can assign access, and there are no access reviews. See [Create an automatic assignment policy](entitlement-management-access-package-auto-assignment-policy.md#creating-an-access-package-assignment-policy-through-powershell) for an example of how to create an automatic assignment policy, and [create an accessPackageAssignmentPolicy](/graph/api/entitlementmanagement-post-assignmentpolicies?tabs=http&view=graph-rest-beta&preserve-view=true) for more examples.
+This script below illustrates using the `beta` profile, to create a policy for direct assignment to an access package. In this policy, only the administrator can assign access, and there are no access reviews. See [Create an automatic assignment policy](entitlement-management-access-package-auto-assignment-policy.md#create-an-access-package-assignment-policy-through-powershell) for an example of how to create an automatic assignment policy, and [create an accessPackageAssignmentPolicy](/graph/api/entitlementmanagement-post-assignmentpolicies?tabs=http&view=graph-rest-beta&preserve-view=true) for more examples.
 
 ```powershell
 Connect-MgGraph -Scopes "EntitlementManagement.ReadWrite.All"

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

@@ -25,11 +25,11 @@ ms.collection: M365-identity-device-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.
+ * You can use access packages to represent [organizational roles](identity-governance-organizational-roles.md) in your organization, such as "sales representative". An access package representing that organizational 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 entitlement management.
+This article discusses how to use roles to manage aspects within Microsoft Entra entitlement management, for controlling access to the entitlement management resources.
 
 By default, Global administrators and Identity governance administrators can create and manage all aspects of 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.
 

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

@@ -107,9 +107,11 @@ The following diagram shows an example of the different elements in entitlement
 
 Access packages don't replace other mechanisms for access assignment.  They're most appropriate in situations such as:
 
+- Migrating access policy definitions from a third party [enterprise role management](identity-governance-organizational-roles.md) to Azure AD.
 - Employees need time-limited access for a particular task.  For example, you might use group-based licensing and a dynamic group to ensure all employees have an Exchange Online mailbox, and then use access packages for situations in which employees need more access rights. For example, rights to read departmental resources from another department.
 - Access that requires the approval of an employee's manager or other designated individuals.
-- Departments wish to manage their own access policies for their resources without IT involvement.  
+- Access that should be assigned automatically to people in a particular part of an organization during their time in that job role, but also available for people elsewhere in the organization, or in a business partner organization, to request.
+- Departments wish to manage their own access policies for their resources without IT involvement.
 - Two or more organizations are collaborating on a project, and as a result, multiple users from one organization will need to be brought in via Azure AD B2B to access another organization's resources.
 
 ## How do I delegate access?

articles/active-directory/governance/identity-governance-applications-define.md

@@ -29,13 +29,13 @@ Organizations with compliance requirements or risk management plans will have se
    > [!Note]
    > If you're using an application from the Azure AD application gallery that supports provisioning, then Azure AD may import defined roles in the application and automatically update the application manifest with the application's roles automatically, once provisioning is configured.
 
-1. **Select which roles and groups have membership that are to be governed in Azure AD.** Based on compliance and risk management requirements, organizations often prioritize those roles or groups that give privileged access or access to sensitive information.
+1. **Select which roles and groups have membership that are to be governed in Azure AD.** Based on compliance and risk management requirements, organizations often prioritize those application roles or groups that give privileged access or access to sensitive information.
 
 ## Define the organization's policy with prerequisites and other constraints for access to the application
 
 In this section, you'll write down the organizational policies you plan to use to determine access to the application. You can record this as a table in a spreadsheet, for example
 
-|Role|Prerequisite for access|Approvers|Default duration of access|Separation of duties constraints|Conditional access policies|
+|App Role|Prerequisite for access|Approvers|Default duration of access|Separation of duties constraints|Conditional access policies|
 |:--|-|-|-|-|-|
 |*Western Sales*|Member of sales team|user's manager|Yearly review|Cannot have *Eastern Sales* access|Multifactor authentication (MFA) and registered device required for access|
 |*Western Sales*|Any employee outside of sales|head of Sales department|90 days|N/A|MFA and registered device required for access|
@@ -44,9 +44,13 @@ In this section, you'll write down the organizational policies you plan to use t
 |*Eastern Sales*|Any employee outside of sales|head of Sales department|90 days|N/A|MFA and registered device required for access|
 |*Eastern Sales*|Non-employee sales rep|head of Sales department|30 days|N/A|MFA required for access|
 
+If you already have an organization role definition, then see [how to migrate an organizational role](identity-governance-organizational-roles.md) for more information.
+
 1. **Identify if there are prerequisite requirements, standards that a user must meet before to they're given access to an application.** For example, under normal circumstances, only full time employees, or those in a particular department or cost center, should be allowed to have access to a particular department's application.  Also, you may require the entitlement management policy for a user from some other department requesting access to have one or more additional approvers. While having multiple stages of approval may slow the overall process of a user gaining access, these extra stages ensure access requests are appropriate and decisions are accountable.  For example, requests for access by an employee could have two stages of approval, first by the requesting user's manager, and second by one of the resource owners responsible for data held in the application.
 
-1. **Determine how long a user who has been approved for access, should have access, and when that access should go away.**  For many applications, a user might retain access indefinitely, until they're no longer affiliated with the organization. In some situations, access may be tied to particular projects or milestones, so that when the project ends, access is removed automatically.  Or, if only a few users are using an application through a policy, you may configure quarterly or yearly reviews of everyone's access through that policy, so that there's regular oversight. These processes can ensure users lose access eventually when access is no longer needed, even if there isn't a pre-determined project end date.
+1. **Determine how long a user who has been approved for access, should have access, and when that access should go away.**  For many applications, a user might retain access indefinitely, until they're no longer affiliated with the organization. In some situations, access may be tied to particular projects or milestones, so that when the project ends, access is removed automatically.  Or, if only a few users are using an application through a policy, you may configure quarterly or yearly reviews of everyone's access through that policy, so that there's regular oversight.
+
+1. **If your organization is governing access already with an organizational role model, plan to bring that organizational role model into Azure AD.** You may have an [organizational role](identity-governance-organizational-roles.md) defined which assigns access based on a user's property, such as their position or department. These processes can ensure users lose access eventually when access is no longer needed, even if there isn't a pre-determined project end date.  
 
 1. **Inquire if there are separation of duties constraints.** For example, you may have an application with two app roles, *Western Sales* and *Eastern Sales*, and you want to ensure that a user can only have one sales territory at a time.  Include a list of any pairs of app roles that are incompatible for your application, so that if a user has one role, they aren't allowed to request the second role.
 

articles/active-directory/governance/identity-governance-applications-integrate.md

@@ -61,7 +61,7 @@ Next, if the application implements a provisioning protocol, then you should con
      | Integrated Windows Auth (IWA) | Deploy the [application proxy](../app-proxy/application-proxy.md), configure an application for [Integrated Windows authentication SSO](../app-proxy/application-proxy-configure-single-sign-on-with-kcd.md), and set firewall rules to prevent access to the application's endpoints except via the proxy.|
      | header-based authentication | Deploy the [application proxy](../app-proxy/application-proxy.md) and configure an application for [header-based SSO](../app-proxy/application-proxy-configure-single-sign-on-with-headers.md) |
 
-1. If your application has multiple roles, and relies upon Azure AD to send a user's application-specific role as a claim of a user signing into the application, then configure those application roles in Azure AD on your application.  You can use  the [app roles UI](../develop/howto-add-app-roles-in-azure-ad-apps.md#app-roles-ui) to add those roles.
+1. If your application has multiple roles, and relies upon Azure AD to send a user's application-specific role as a claim of a user signing into the application, then configure those application roles in Azure AD on your application.  You can use  the [app roles UI](../develop/howto-add-app-roles-in-azure-ad-apps.md#app-roles-ui) to add those roles to the application manifest.
 
 1. If the application supports provisioning, then [configure provisioning](../app-provisioning/configure-automatic-user-provisioning-portal.md) of assigned users and groups from Azure AD to that application.  If this is a private or custom application, you can also select the integration that's most appropriate, based on the location and capabilities of the application.