Merge pull request #210149 from weznagwama/doco-changes

Doco changes

Author: jborsecnik

articles/active-directory/cloud-infrastructure-entitlement-management/media/onboard-enable-tenant/dashboard.png

@@ -18,6 +18,20 @@ This article describes how to onboard an Amazon Web Services (AWS) account on Pe
 > [!NOTE]
 > A *global administrator* or *super admin* (an admin for all authorization system types) can perform the tasks in this article after the global administrator has initially completed the steps provided in [Enable Permissions Management on your Azure Active Directory tenant](onboard-enable-tenant.md).
 
+## Explanation
+
+There are several moving parts across AWS and Azure, which are required to be configured before onboarding.
+
+* An Azure AD OIDC App
+* An AWS OIDC account
+* An (optional) AWS Master account
+* An (optional) AWS Central logging account
+* An AWS OIDC role
+* An AWS Cross Account role assumed by OIDC role
+ 
+
+<!-- diagram from gargi -->
+
 ## Onboard an AWS account
 
 1. If the **Data Collectors** dashboard isn't displayed when Permissions Management launches:
@@ -99,15 +113,15 @@ This article describes how to onboard an Amazon Web Services (AWS) account on Pe
 
 Select **Enable AWS SSO checkbox**, if the AWS account access is configured through AWS SSO. 
 
-Choose from 3 options to manage AWS accounts. 
+Choose from three options to manage AWS accounts. 
 
 #### Option 1: Automatically manage 
 
-Choose this option to automatically detect and add to monitored account list, without additional configuration. Steps to detect list of accounts and onboard for collection: 
+Choose this option to automatically detect and add to the monitored account list, without extra configuration. Steps to detect list of accounts and onboard for collection: 
 
 - Deploy Master account CFT (Cloudformation template) which creates organization account role that grants permission to OIDC role created earlier to list accounts, OUs and SCPs. 
 - If AWS SSO is enabled, organization account CFT also adds policy needed to collect AWS SSO configuration details. 
-- Deploy Member account CFT in all the accounts that need to be monitored by Entra Permissions Management. This creates a cross account role that trusts the OIDC role created earlier. The SecurityAudit policy is attached to the role created for data collection. 
+- Deploy Member account CFT in all the accounts that need to be monitored by Entra Permissions Management. These actions create a cross account role that trusts the OIDC role created earlier. The SecurityAudit policy is attached to the role created for data collection. 
 
 Any current or future accounts found get onboarded automatically. 
 
@@ -159,7 +173,7 @@ This option detects all AWS accounts that are accessible through OIDC role acces
 
 - Deploy Master account CFT (Cloudformation template) which creates organization account role that grants permission to OIDC role created earlier to list accounts, OUs and SCPs. 
 - If AWS SSO is enabled, organization account CFT also adds policy needed to collect AWS SSO configuration details. 
-- Deploy Member account CFT in all the accounts that need to be monitored by Entra Permissions Management. This creates a cross account role that trusts the OIDC role created earlier. The SecurityAudit policy is attached to the role created for data collection. 
+- Deploy Member account CFT in all the accounts that need to be monitored by Entra Permissions Management. These actions create a cross account role that trusts the OIDC role created earlier. The SecurityAudit policy is attached to the role created for data collection. 
 - Click Verify and Save. 
 - Navigate to newly create Data Collector row under AWSdata collectors. 
 - Click on Status column when the row has “Pending” status 

articles/active-directory/cloud-infrastructure-entitlement-management/media/overview/discover-remediate-monitor.png

@@ -18,6 +18,14 @@ This article describes how to onboard a Microsoft Azure subscription or subscrip
 > [!NOTE]
 > A *global administrator* or *super admin* (an admin for all authorization system types) can perform the tasks in this article after the global administrator has initially completed the steps provided in [Enable Permissions Management on your Azure Active Directory tenant](onboard-enable-tenant.md).
 
+## Explanation
+
+The Permissions Management service is built on Azure, and given you're onboarding your Azure subscriptions to be monitored and managed, setup is simple with few moving parts to configure. Below is what is required to configure onboarding:
+
+* When your tenant is onboarded, an application is created in the tenant.
+* This app requires 'reader' permissions on the subscriptions
+* For controller functionality, the app requires 'User Access Administrator' to create and implement right-size roles
+
 ## Prerequisites
 
 To add Permissions Management to your Azure AD tenant:
@@ -34,23 +42,24 @@ To add Permissions Management to your Azure AD tenant:
 
 ### 1. Add Azure subscription details
 
-Choose from 3 options to manage Azure subscriptions. 
+Choose from three options to manage Azure subscriptions. 
 
 #### Option 1: Automatically manage 
 
-This option allows subscriptions to be automatically detected and monitored without extra configuration.A key benefit of automatic management is that any current or future subscriptions found get onboarded automatically. Steps to detect list of subscriptions and onboard for collection:  
+This option allows subscriptions to be automatically detected and monitored without further work required. A key benefit of automatic management is that any current or future subscriptions found will be onboarded automatically. The steps to detect a list of subscriptions and onboard for collection are as follows:  
 
-- Firstly, grant Reader role to Cloud Infrastructure Entitlement Management application at management group or subscription scope.  
+- Firstly, grant Reader role to Cloud Infrastructure Entitlement Management application at management group or subscription scope. To do this:  
 
 1. In the EPM portal, left-click the cog on the top right-hand side.  
 1. Navigate to data collectors tab  
 1. Ensure 'Azure' is selected
 1. Click ‘Create Configuration’ 
 1. For onboarding mode, select ‘Automatically Manage’ 
 
-The steps listed on the screen outline how to create the role assignment for the Cloud Infrastructure Entitlements Management application. This can be performed manually in the Entra console, or programatically with PowerShell or the Azure CLI.
+    > [!NOTE]
+    > The steps listed on the screen outline how to create the role assignment for the Cloud Infrastructure Entitlements Management application. This can be performed manually in the Entra console, or programatically with PowerShell or the Azure CLI.
 
-Lastly, Click ‘Verify Now & Save’ 
+- Once complete, Click ‘Verify Now & Save’
 
 To view status of onboarding after saving the configuration: 
 
@@ -61,13 +70,13 @@ To view status of onboarding after saving the configuration:
 
 You have the ability to specify only certain subscriptions to manage and monitor with MEPM (up to 10 per collector). Follow the steps below to configure these subscriptions to be monitored: 
 
-1. For each subscription you wish to manage, ensure that the ‘Reader’ role has been granted to Cloud Infrastructure Entitlement Management application for this subscription. 
+1. For each subscription you wish to manage, ensure that the ‘Reader’ role has been granted to Cloud Infrastructure Entitlement Management application for the subscription. 
 1. In the EPM portal, click the cog on the top right-hand side. 
 1. Navigate to data collectors tab 
 1. Ensure 'Azure' is selected
 1. Click ‘Create Configuration’ 
 1. Select ‘Enter Authorization Systems’ 
-1. Under the Subscription IDs section, enter a desired subscription ID into the input box. Click the “+” up to 9 additional times, putting a single subscription ID into each respective input box. 
+1. Under the Subscription IDs section, enter a desired subscription ID into the input box. Click the “+” up to nine extra times, putting a single subscription ID into each respective input box. 
 1. Once you have input all of the desired subscriptions, click next 
 1. Click ‘Verify Now & Save’ 
 1. Once the access to read and collect data is verified, collection will begin. 
@@ -90,9 +99,10 @@ This option detects all subscriptions that are accessible by the Cloud Infrastru
 1. Click ‘Create Configuration’ 
 1. For onboarding mode, select ‘Automatically Manage’ 
 
-The steps listed on the screen outline how to create the role assignment for the Cloud Infrastructure Entitlements Management application. You can do this manually in the Entra console, or programatically with PowerShell or the Azure CLI.
+    > [!NOTE]
+    > The steps listed on the screen outline how to create the role assignment for the Cloud Infrastructure Entitlements Management application. You can do this manually in the Entra console, or programatically with PowerShell or the Azure CLI.
 
-Lastly, Click ‘Verify Now & Save’ 
+- Once complete, Click ‘Verify Now & Save’ 
 
 To view status of onboarding after saving the configuration: 
 

articles/active-directory/cloud-infrastructure-entitlement-management/media/ui-dashboard/pci-heat-map.png

@@ -18,6 +18,8 @@ This article describes how to enable Permissions Management in your organization
 > [!NOTE]
 > To complete this task, you must have *global administrator* permissions as a user in that tenant. You can't enable Permissions Management as a user from other tenant who has signed in via B2B or via Azure Lighthouse.
 
+:::image type="content" source="media/onboard-enable-tenant/dashboard.png" alt-text="A preview of what the permissions management dashboard looks like." lightbox="media/onboard-enable-tenant/dashboard.png":::
+
 ## Prerequisites
 
 To enable Permissions Management in your organization:

articles/active-directory/cloud-infrastructure-entitlement-management/media/ui-dashboard/ui-dashboard.png

@@ -18,6 +18,20 @@ This article describes how to onboard a Google Cloud Platform (GCP) project on P
 > [!NOTE]
 > A *global administrator* or *super admin* (an admin for all authorization system types) can perform the tasks in this article after the global administrator has initially completed the steps provided in [Enable Permissions Management on your Azure Active Directory tenant](onboard-enable-tenant.md).
 
+## Explanation
+
+For GCP, permissions management is scoped to a *GCP project*. A GCP project is a logical collection of your resources in GCP, like a subscription in Azure, albeit with further configurations you can perform such as application registrations and OIDC configurations.
+
+<!-- Diagram from Gargi-->
+
+There are several moving parts across GCP and Azure, which are required to be configured before onboarding.
+
+* An Azure AD OIDC App
+* A Workload Identity in GCP
+* OAuth2 confidential client grants utilized
+* A GCP service account with permissions to collect
+
+
 ## Onboard a GCP project
 
 1. If the **Data Collectors** dashboard isn't displayed when Permissions Management launches:
@@ -37,22 +51,21 @@ This article describes how to onboard a Google Cloud Platform (GCP) project on P
     > [!NOTE]
     > 1. To confirm that the app was created, open **App registrations** in Azure and, on the **All applications** tab, locate your app.
     > 1. Select the app name to open the **Expose an API** page. The **Application ID URI** displayed in the **Overview** page is the *audience value* used while making an OIDC connection with your GCP account.
-
-    1. Return to Permissions Management, and in the **Permissions Management Onboarding - Azure AD OIDC App Creation**, select **Next**.
+    > 1. Return to the Permissions Management window, and in the **Permissions Management Onboarding - Azure AD OIDC App Creation**, select **Next**.
 
 ### 2. Set up a GCP OIDC project.
 
 Choose from 3 options to manage GCP projects. 
 
 #### Option 1: Automatically manage 
 
-This option allows projects to be automatically detected and monitored without additional configuration. Steps to detect list of projects and onboard for collection:  
+The automatically manage option allows projects to be automatically detected and monitored without extra configuration. Steps to detect list of projects and onboard for collection:  
 
 Firstly, grant Viewer and Security Reviewer role to service account created in previous step at organization, folder or project scope. 
 
-Once done, the steps are listed in the screen to do this manually in the GPC console, or programatically with the gcloud CLI.
+Once done, the steps are listed in the screen, which shows how to further configure in the GPC console, or programatically with the gcloud CLI.
 
-Once this has been configured, click next, then 'Verify Now & Save'.
+Once everything has been configured, click next, then 'Verify Now & Save'.
 
 Any current or future projects found get onboarded automatically. 
 
@@ -81,7 +94,7 @@ To view status of onboarding after saving the configuration:
 This option detects all projects that are accessible by the Cloud Infrastructure Entitlement Management application.  
 
 - Firstly, grant Viewer and Security Reviewer role to service account created in previous step at organization, folder or project scope
-- Once done, the steps are listed in the screen to do this manually in the GPC console, or programatically with the gcloud CLI
+- Once done, the steps are listed in the screen to do configure manually in the GPC console, or programatically with the gcloud CLI
 - Click Next
 - Click 'Verify Now & Save' 
 - Navigate to newly create Data Collector row under GCP data collectors
@@ -108,7 +121,7 @@ This option detects all projects that are accessible by the Cloud Infrastructure
 
     The **Welcome to Permissions Management GCP onboarding** screen appears, displaying steps you must complete to onboard your GCP project.
 
-### 5. Paste the environment vars from the Permissions Management portal.
+### 5. Paste the environmental variables from the Permissions Management portal.
 
 1. Return to Permissions Management and select **Copy export variables**.
 1. In the GCP Onboarding shell editor, paste the variables you copied, and then press **Enter**.

articles/active-directory/cloud-infrastructure-entitlement-management/onboard-aws.md

@@ -15,13 +15,13 @@ ms.author: kenwith
 
 ## Overview
 
-Permissions Management is a cloud infrastructure entitlement management (CIEM) solution that provides comprehensive visibility into permissions assigned to all identities. For example, over-privileged workload and user identities, actions, and resources across multi-cloud infrastructures in Microsoft Azure, Amazon Web Services (AWS), and Google Cloud Platform (GCP).
+Permissions Management is a cloud infrastructure entitlement management (CIEM) solution that provides comprehensive visibility into permissions assigned to all identities. For example, over-privileged workload and user identities, actions, and resources across multicloud infrastructures in Microsoft Azure, Amazon Web Services (AWS), and Google Cloud Platform (GCP).
 
 Permissions Management  detects, automatically right-sizes, and continuously monitors unused and excessive permissions.
 
 Organizations have to consider permissions management as a central piece of their Zero Trust security to implement least privilege access across their entire infrastructure:
 
-- Organizations are increasingly adopting multi-cloud strategy and are struggling with the lack of visibility and the increasing complexity of managing access permissions.
+- Organizations are increasingly adopting multicloud strategy and are struggling with the lack of visibility and the increasing complexity of managing access permissions.
 - With the proliferation of identities and cloud services, the number of high-risk cloud permissions is exploding, expanding the attack surface for organizations.
 - IT security teams are under increased pressure to ensure access to their expanding cloud estate is secure and compliant.
 - The inconsistency of cloud providers' native access management models makes it even more complex for Security and Identity to manage permissions and enforce least privilege access policies across their entire environment.
@@ -32,8 +32,9 @@ Organizations have to consider permissions management as a central piece of thei
 
 Permissions Management  allows customers to address three key use cases: *discover*, *remediate*, and *monitor*.
 
-Permissions Management has been designed in such a way that we recommended your organization sequentially 'step-through' each of the below phases in order to gain insights into permissions across the organization. This is because you generally cannot action what is yet to be discovered, likewise you cannot continually evaluate what is yet to be remediated.
+Permissions Management has been designed in such a way that we recommended you 'step-through' each of the below phases in order to gain insights into permissions across the organization. This is because you generally can't action what is yet to be discovered, likewise you can't continually evaluate what is yet to be remediated.
 
+:::image type="content" source="media/overview/discover-remediate-monitor.png" alt-text="Use case for Permissions Management." lightbox="media/overview/discover-remediate-monitor.png":::
 
 ### Discover
 
@@ -64,7 +65,7 @@ Permissions Management  deepens Zero Trust security strategies by augmenting the
 - Automate least privilege access: Use access analytics to ensure identities have the right permissions, at the right time.
 - Unify access policies across infrastructure as a service (IaaS) platforms: Implement consistent security policies across your cloud infrastructure.
 
-Once your organization has explored and implemented the discover, remediation and monitor phases, you have established one of the core pillars of a modern zero-trust security strategy.
+Once your organization has explored and implemented the discover, remediation and monitor phases, you've established one of the core pillars of a modern zero-trust security strategy.
 
 ## Next steps
 

articles/active-directory/cloud-infrastructure-entitlement-management/onboard-azure.md

@@ -16,6 +16,8 @@ ms.author: kenwith
 
 Permissions Management provides a summary of key statistics and data about your authorization system regularly. This information is available for Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform (GCP).
 
+:::image type="content" source="media/ui-dashboard/ui-dashboard.png" alt-text="An example of the Permissions Management dashboard, highlighting key statistics to investigate." lightbox="media/ui-dashboard/ui-dashboard.png":::
+
 ## View metrics related to avoidable risk
 
 The data provided by Permissions Management includes metrics related to avoidable risk. These metrics allow the Permissions Management administrator to identify areas where they can reduce risks related to the principle of least permissions.
@@ -74,6 +76,8 @@ The Permissions Management **Dashboard** displays the following information:
 
 ## The PCI heat map
 
+:::image type="content" source="media/ui-dashboard/pci-heat-map.png" alt-text="An example of the PCI heatmap showing hundreds of identities which require investigation." lightbox="media/ui-dashboard/pci-heat-map.png":::
+
 The **Permission Creep Index**  heat map shows the incurred risk of users with access to high-risk permissions, and provides information about:
 
 - Users who were given access to high-risk permissions but aren't actively using them. *High-risk permissions* include the ability to modify or delete information in the authorization system.