[Wiki] Several 'How-Enterprise-Scale-Works' & 'ALZ-Setup-aad-permissions' documentation-specific suggestions (#1224)

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

docs/wiki/ALZ-Deploy-reference-implementations.md

@@ -19,12 +19,12 @@ The Enterprise-Scale design principles and reference implementations can be adop
 
 An Enterprise-Scale reference implementation is rooted in the principle that **Everything in Azure is a Resource**. All of the reference scenarios leverage native **Azure Resource Manager (ARM)** to describe and manage their resources as part of their target state architecture at-scale.
 
-Reference implementations enable security, monitoring, networking, and any other plumbing needed for landing zones (i.e. Subscriptions) autonomously through policy enforcement. Companies will deploy the Azure environment with ARM templates to create the necessary structure for management and networking to declare a desired goal state. All scenarios will apply the principle of "Policy Driven Governance" for landing zones by using Azure Policy. The benefits of a policy-driven approach are many but the most significant are:
+Reference implementations enable security, monitoring, networking, and any other plumbing needed for landing zones (i.e. subscriptions) autonomously through policy enforcement. Companies will deploy the Azure environment with ARM templates to create the necessary structure for management and networking to declare a desired goal state. All scenarios will apply the principle of "Policy-Driven Governance" for landing zones by using Azure Policy. The benefits of a policy-driven approach are many but the most significant are:
 
-1. Platform can provide an orchestration capability to bring target resources (in this case a subscription) to a desired goal state.
+1. The platform can provide an orchestration capability to bring target resources (in this case a subscription) to a desired goal state.
 
 2. Continuous conformance to ensure all platform-level resources are compliant. Because the platform is aware of the goal state, the platform can assist with the monitoring and remediation of resources throughout their life-cycle.
 
-3. Platform enables autonomy regardless of the customer's scale point.
+3. The platform enables autonomy regardless of the customer's scale point.
 
 To know and learn more about ARM templates used for above reference implementation, please follow [this](https://github.com/Azure/Enterprise-Scale/blob/main/docs/Deploy/es-schema.md) article.

docs/wiki/ALZ-Setup-aad-permissions.md

@@ -2,7 +2,7 @@
 
 This article will guide you through the process to add your AzOps service principal to the  Azure Active Directory [Directory Readers](https://learn.microsoft.com/azure/active-directory/users-groups-roles/directory-assign-admin-roles) role.
 
-> Note: The steps below requires you to use an identity that is local to the Azure AD, and **_not_** Guest user account due to known restrictions.
+> Note: The steps below requires you to use an identity that is local to the Azure AD, and **_not_** a Guest user account due to known restrictions.
 
 The service principal used by the Enterprise-Scale reference implementation requires Azure AD directory reader permissions to be able to discover Azure role assignments. These permissions are used to enrich data around the role assignments with additional Azure AD context such as ObjectType and Azure AD Object DisplayName.
 
@@ -15,7 +15,7 @@ The service principal used by the Enterprise-Scale reference implementation requ
 1.3 Under _Manage_ > _Roles and administrators_, select _Directory readers_.
 ![alt](./media/aad-rolesandadministrators.png)
 
-1.4 Under _Manage_ > _Assignments_ > _Add assignments_, find for and select your AzOps service principal and finally add it to the directory role.
+1.4 Under _Manage_ > _Assignments_ > _Add assignments_, find and select your AzOps service principal and finally add it to the directory role.
 
 ![alt](./media/directory-reader.png)
 
@@ -31,27 +31,23 @@ Ensure that you have the [AzureAD PowerShell module installed on your machine](h
 $ADServicePrincipal = "AZOps"
 
 #verify if AzureAD module is installed and running a minimum version, if not install with the latest version.
-if ((Get-InstalledModule -Name "AzureAD" -MinimumVersion 2.0.2.130 ` -ErrorAction SilentlyContinue) -eq $null) {
+if (-not (Get-InstalledModule -Name "AzureAD" -MinimumVersion 2.0.2.130 ` -ErrorAction 'SilentlyContinue')) {
-
-    Write-Host "AzureAD Module does not exist" -ForegroundColor Yellow
-    Install-Module -Name AzureAD -Force
-    Import-Module -Name AzureAD
-    Connect-AzureAD #sign in to Azure from Powershell, this will redirect you to a webbrowser for authentication, if required
 
+    Write-Host "AzureAD Module does not exist" -ForegroundColor 'Yellow'
+    Install-Module -Name 'AzureAD' -Force
 }
 else {
-    Write-Host "AzureAD Module exists with minimum version" -ForegroundColor Yellow
+    Write-Host "AzureAD Module exists with minimum version" -ForegroundColor 'Yellow'
-    Import-Module -Name AzureAD
-    Connect-AzureAD #sign in to Azure from Powershell, this will redirect you to a webbrowser for authentication, if required
 }
+Connect-AzureAD #sign in to Azure from Powershell, this will redirect you to a webbrowser for authentication, if required
 
 #Verify Service Principal and if not pick a new one.
-if (!(Get-AzureADServicePrincipal -Filter "DisplayName eq '$ADServicePrincipal'")) { 
+if (-not (Get-AzureADServicePrincipal -Filter "DisplayName eq '$ADServicePrincipal'")) { 
-    Write-Host "ServicePrincipal doesn't exist or is not AZOps" -ForegroundColor Red
+    Write-Host "ServicePrincipal doesn't exist or is not AZOps" -ForegroundColor 'Red'
     break
 }
 else { 
-    Write-Host "$ADServicePrincipal exist" -ForegroundColor Green
+    Write-Host "$ADServicePrincipal exist" -ForegroundColor 'Green'
     $ServicePrincipal = Get-AzureADServicePrincipal -Filter "DisplayName eq '$ADServicePrincipal'"
     #Get Azure AD Directory Role
     $DirectoryRole = Get-AzureADDirectoryRole -Filter "DisplayName eq 'Directory Readers'"

docs/wiki/How-Enterprise-Scale-Works.md

@@ -48,17 +48,15 @@ One of the key tenets of Enterprise-Scale is to have a clear separation of the A
 
 Platform resource are managed by a cross-functional platform team. The team consist mainly out of the following functions. These functions working in close collaboration with the SME functions across the organization:
 
-- PlatformOps: Responsible for management and deployment of control plane resource types such as subscriptions, management groups via IaC and the respective CI/CD pipelines. Management of the platform related identify identity resources on Azure AD and cost management for the platform.
+- **PlatformOps:** Responsible for management and deployment of control plane resource types such as subscriptions, management groups via IaC and the respective CI/CD pipelines. Management of the platform-related identity resources on Azure AD and cost management for the platform. Operationalization of the platform for an organization is under the responsibility of the platform function.
-     Operationalization of the Platform for an organization is under the responsibility of the platform function.
+- **SecOps:** Responsible for definition and management of Azure Policy and RBAC permissions on the platform for landing zones and platform management groups and subscriptions. Security operations including monitoring and the definition & operation of reporting and auditing dashboard.
-
+- **NetOps:** Definition and management of the common networking components in Azure including the hybrid connectivity and firewall resource to control internet facing networking traffic. NetOps team is responsible to handout virtual networks to landing zone owners or team.
-- SecOps: Responsible for definition and management of Azure Policy and RBAC permissions on the platform for landing zones and platform management groups and subscriptions. Security operations including monitoring and the definition and the operation of reporting and auditing dashboard.
-- NetOps: Definition and management of the common networking components in Azure including the hybrid connectivity and firewall resource to control internet facing networking traffic. NetOps team is responsible to handout virtual networks to landing zone owners or team.
 
 ## Landing zone owners responsibilities
 
-Enterprise-scale landing zones supporting a both centralized and federated application DevOps models. Most common model are dedicated **DevOps** team aligned with a single workload. In case of smaller workloads or COTS or 3rd party application a single **AppDevOps** team is responsible for workload operation. Independent of the model every DevOps team manages several workload staging environments (DEV, UAT, PROD) deployed to individual landing zones/subscriptions. Each landing zone has a set of RBAC permissions managed with Azure AD PIM provided by the Platform SecOps team.
+Enterprise-scale landing zones support both centralized and federated application DevOps models. The most common model are dedicated **DevOps** teams which are each associated with a single workload. In case of smaller workloads, COTS, or 3rd party applications, a single **AppDevOps** team is responsible for the workload's operation. Independent of the model every DevOps team manages several workload staging environments (DEV, UAT, PROD), deployed to individual landing zones /subscriptions. Each landing zone has a set of RBAC permissions managed with Azure AD PIM provided by the Platform SecOps team.
 
-When the landing zones/subscriptions are handed over to the DevOps team, the team is end-to-end responsible for the workload. They can independently operate within the security guardrails provided by the platform team. If dependency on central teams or functions are discovered, it is highly recommended to review the process and eliminated as soon as possible to unblock DevOps teams.
+When the landing zones / subscriptions are handed over to the DevOps team, the team is end-to-end responsible for the workload. They can operate within the security guardrails provided by the platform team independently. If dependencies on central teams or functions are discovered, it is highly recommended to review the process and eliminate these as soon as possible to unblock DevOps teams.
 
 ## Enterprise-Scale Management Group Structure
 
@@ -69,12 +67,12 @@ The Management Group structure implemented with Enterprise-Scale is as follows:
 
   - **Management:** This Management Group contains the dedicated subscription for management, monitoring, and security, which will host Azure Log Analytics, Azure Automation, and Azure Sentinel. Specific Azure policies are assigned to harden and manage the resources in the management subscription.
 
-  - **Connectivity:** This Management Group contains the dedicated subscription for connectivity, which will host the Azure networking resources required for the platform, such as Azure Virtual WAN/Virtual Network for the hub, Azure Firewall, DNS Private Zones, Express Route circuits, ExpressRoute/VPN Gateways etc among others. Specific Azure policies are assigned to harden and manage the resources in the connectivity subscription.
+  - **Connectivity:** This Management Group contains the dedicated subscription for connectivity, which will host the Azure networking resources required for the platform, such as Azure Virtual WAN/Virtual Network for the hub, Azure Firewall, DNS Private Zones, Express Route circuits, ExpressRoute/VPN Gateways etc. among others. Specific Azure policies are assigned to harden and manage the resources in the connectivity subscription.
   - **Identity:** This Management Group contains the dedicated subscription for identity, which is a placeholder for Windows Server Active Directory Domain Services (AD DS) VMs, or Azure Active Directory Domain Services to enable AuthN/AuthZ for workloads within the landing zones. Specific Azure policies are assigned to harden and manage the resources in the identity subscription.
 
-- **Landing Zones:** This is the parent Management Group for all the landing zone subscriptions and will have workload agnostic Azure Policies assigned to ensure workloads are secure and compliant.
+- **Landing Zones:** This is the parent Management Group for all the landing zone subscriptions and will have workload-agnostic Azure Policies assigned to ensure workloads are secure and compliant.
 
-  - **Online:** This is the dedicated Management Group for Online landing zones, meaning workloads that may require direct internet inbound/outbound connectivity or also for workloads that may not require a VNet..
+  - **Online:** This is the dedicated Management Group for Online landing zones, meaning workloads that may require direct internet inbound/outbound connectivity or also for workloads that may not require a VNet.
   - **Corp:** This is the dedicated Management Group for Corp landing zones, meaning workloads that requires connectivity/hybrid connectivity with the corporate network thru the hub in the connectivity subscription.
 
 - **Sandboxes:** This is the dedicated Management Group for subscriptions that will solely be used for testing and exploration by an organization’s application teams. These subscriptions will be securely disconnected from the Corp and Online landing zones.
@@ -86,7 +84,7 @@ By default, all recommended settings and resources recommendations are enabled a
 
 - A scalable Management Group hierarchy aligned to core platform capabilities, allowing you to operationalize at scale using centrally managed Azure RBAC and Azure Policy where platform and workloads have clear separation.
 
-- Azure Policies that will enable autonomy for the platform and the landing zones. The full list of policies leveraged by Enterprise-Scale, their intent, assignment scope, and life-cycle can be [viewed here](./ALZ-Policies).
+- Azure Policies that will enable autonomy for the platform and the landing zones. The full list of policies leveraged by Enterprise-Scale, their intent, assignment scope, and life-cycle can be viewed [here](./ALZ-Policies).
 - An Azure subscription dedicated for **Management**, which enables core platform capabilities at scale using Azure Policy such as:
 
   - A Log Analytics workspace and an Automation account
@@ -96,7 +94,7 @@ By default, all recommended settings and resources recommendations are enabled a
   - Azure Sentinel
   - Diagnostics settings for Activity Logs, VMs, and PaaS resources sent to Log Analytics
 
-- When deploying **Adventure Works** and **Contoso**: An Azure subscription dedicated for **Connectivity**, which deploys core Azure networking resources such as:
+- When deploying [**Adventure Works**](./ALZ-Deploy-reference-implementations#deploy-a-reference-implementation) or [**Contoso**](./ALZ-Deploy-reference-implementations#deploy-a-reference-implementation): An Azure subscription dedicated for **Connectivity**, which deploys core Azure networking resources such as:
 
   - A hub virtual network
   - Azure Firewall
@@ -106,18 +104,18 @@ By default, all recommended settings and resources recommendations are enabled a
   - Azure Private DNS Zones for Private Link
 
 - (Optionally) An Azure subscription dedicated for **Identity** in case your organization requires to have Active Directory Domain Controllers to provide authorization and authentication for workloads deployed into the landing zones.
-- (Optionally) Integrate your Azure environment with GitHub, where you provide the PA Token to create a new repository and automatically discover and merge your deployment into Git.
+- (Optionally) Integrate your Azure environment with GitHub, where you provide the Personal Access Token (PAT) to create a new repository and automatically discover and merge your deployment into Git.
 
-- Landing Zone Management Group for **Corp** connected applications that require connectivity to on-premises, to other landing zones or to the internet via shared services provided in the hub virtual network.
+- A Landing Zone Management Group for **Corp**-connected applications that require connectivity to on-premises, to other landing zones or to the internet via shared services provided by the hub virtual network.
   - This is where you will create your subscriptions that will host your corp-connected workloads.
 
-- Landing Zone Management Group for **Online** applications that will be internet-facing, where a virtual network is optional and hybrid connectivity is not required.
+- A Landing Zone Management Group for **Online** applications that will be internet-facing, where a virtual network is optional and hybrid connectivity is not required.
-  - This is where you will create your Subscriptions that will host your online workloads.
+  - This is where you will create your subscriptions that will host your online workloads.
 
-- Landing zone subscriptions for Azure native, internet-facing **Online** applications and resources.
+- Landing zone subscriptions for Azure-native, internet-facing **Online** applications and resources.
 
-- Landing zone subscriptions for **Corp** connected applications and resources, including a virtual network that will be connected to the hub via VNet peering.
+- Landing zone subscriptions for **Corp**-connected applications and resources, including a virtual network that will be connected to the hub via virtual network peering.
-- Azure Policies for online and corp-connected landing zones, which include:
+- Azure Policies for online- and corp-connected landing zones, which include:
   - Enforce VM monitoring (Windows & Linux)
   - Enforce VMSS monitoring (Windows & Linux)
   - Enforce Azure Arc VM monitoring (Windows & Linux)
@@ -128,5 +126,5 @@ By default, all recommended settings and resources recommendations are enabled a
   - Enforce encryption for Azure SQL
   - Prevent IP forwarding
   - Prevent inbound RDP from internet
-  - Ensure subnets are associated with Network Security Groups
+  - Ensure subnets are associated with network security groups
-  - Ensure subnets are associated with User-Defined routes
+  - Ensure subnets are associated with user-defined routes