docs(readme): update #12, #16

- updates readme with newer end to end overview diagram - concept: slight changes, mark TODOs - removes unused and draft images
Azure · Mar 19, 2021 · ee1167a · ee1167a
1 parent b0326f4
commit ee1167a
Show file tree

Hide file tree

Showing 10 changed files with 73 additions and 77 deletions.
diff --git a/CONCEPT.md b/CONCEPT.md
@@ -1,28 +1,16 @@
 # Concept - Multi-tier Governance
 
+Status: Draft  
+Author: Julie Ng  
+Last Updated: March 2021
+
 ### Abstract
 
 When developing a governance model for your organization, it is important to remember that Azure Resource Management (ARM) is only _one_ way to manage resources. Other deployment methods must also be secured and governance applied.
 
 By introducing automation via CI/CD pipelines, be aware that the Role Based Access Control (RBAC) model must be applied at **multiple layers**. This code sample deploys many of these layers and show how they can be configured together in a unified governance model. 
 
-The following diagram illustrates a baseline CI/CD workflow with [Azure DevOps](https://dev.azure.com). The red lock icon <img src="./images/icon-lock.svg" valign="bottom"> indicates security permissions which must be configured by the user. Not configuring or mis-configuring permissions will leave your workloads vulnerable.
-
-![End to End Governance](./images/e2e-governance-scm-to-arm.svg)
-
-To successfully secure your workloads, you must leverage a combination of security permissions configurations and human checks in your workflow. RBAC will prevent individual developers from making destructive changes. Build pipelines, however often run with privileged identities and will happily destroy your workloads if instructed to do so in the pipeline code. To prevent this from happening, you should configure [branch policies](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops) on your repository to require human approval before accepting changes that trigger automation pipelines.
-
-| Deployment Step | Responsibility | Description |
-|:--|:--|:--|
-| **Pull Requests** | User | Engineers should peer review their work especially the Pipeline code. |
-| **Branch Protection** | [Shared](https://docs.microsoft.com/en-us/azure/security/fundamentals/shared-responsibility) | Configure [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops) or [GitHub](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/about-protected-branches) to reject changes that do not meet certain standards, e.g. CI checks and peer reviews (via pull requests). |
-| **Pipeline as Code** | User | A build server will happily delete your production environment if the pipeline code instructs it to do so. Prevent this using a combination of pull requests and branch protection rules. |
-| **[Service Connections](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml)** | [Shared](https://docs.microsoft.com/en-us/azure/security/fundamentals/shared-responsibility) | Configure Azure DevOps to restrict access to these credentials. |
-| **Azure Resources** | [Shared](https://docs.microsoft.com/en-us/azure/security/fundamentals/shared-responsibility) | Configure RBAC in the Azure Resource Manager. |
-
-Before examining the governance layers in detail, please consider the use case and assumptions of this example organization.
-
-## Example Use Case, Business Requirements
+## Example Scenario, Business Requirements
 
 This demo is open source and intended to be used as a **Teaching Tool** for organizations who are new to DevOps and need to create a governance model for deploying to Azure. Please read this carefully to understand the decisions behind the model used in this sample repository. 
 
@@ -43,34 +31,33 @@ Any governance model must be tied to the organization's business rules, which ar
 - **Cloud Journey - so far**  
   The organization started with an isolated project model to accelerate the journey to the cloud. But now they are exploring options to break silos and encourage collaboration by creating the "collaboration" and "supermarket" projects.
 
-## Azure Active Directory (AAD)
+## CI/CD Automation Workflow
 
-Azure Active Directory is central identity provider and will be leveraged on both Azure DevOps and ARM layers. The overlapping triangles illustrate common pattern of leveraging [additive permissions](https://docs.microsoft.com/en-us/azure/role-based-access-control/overview#multiple-role-assignments).
-
-In this example, each business domain has 2 AAD groups: a general group and a subset for admins only.
+The following diagram illustrates a baseline CI/CD workflow with [Azure DevOps](https://dev.azure.com). The red lock icon <img src="./images/icon-lock.svg" valign="bottom"> indicates security permissions which must be configured by the user. Not configuring or mis-configuring permissions will leave your workloads vulnerable.
 
-<img src="./images/aad-groups.svg" alt="" width="400">
+![End to End Governance](./images/e2e-governance-scm-to-arm.svg)
 
-### Roles
+TODO: introduce x-axis for "layers"
 
-The groups are assigned the following built-in roles in Azure and AzureDevOps. In both business units, administrators are given elevated privileges. 
+To successfully secure your workloads, you must leverage a combination of security permissions configurations and human checks in your workflow. RBAC will prevent individual developers from making destructive changes. Build pipelines, however often run with privileged identities and will happily destroy your workloads if instructed to do so in the pipeline code. To prevent this from happening, you should configure [branch policies](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops) on your repository to require human approval before accepting changes that trigger automation pipelines.
 
-| Group Name | ARM Role | Azure DevOps Role |
+| Deployment Step | Responsibility | Description |
 |:--|:--|:--|
-| `fruits` | Contributor | Contributor |
-| `fruits-admins` | Owner | Project Administrators |
-| `veggies` | Contributor | Contributor |
-| `veggies-admins` | Owner | Project Administrators |
+| **Pull Requests** | User | Engineers should peer review their work especially the Pipeline code. |
+| **Branch Protection** | [Shared](https://docs.microsoft.com/en-us/azure/security/fundamentals/shared-responsibility) | Configure [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops) or [GitHub](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/about-protected-branches) to reject changes that do not meet certain standards, e.g. CI checks and peer reviews (via pull requests). |
+| **Pipeline as Code** | User | A build server will happily delete your production environment if the pipeline code instructs it to do so. Prevent this using a combination of pull requests and branch protection rules. |
+| **[Service Connections](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml)** | [Shared](https://docs.microsoft.com/en-us/azure/security/fundamentals/shared-responsibility) | Configure Azure DevOps to restrict access to these credentials. |
+| **Azure Resources** | [Shared](https://docs.microsoft.com/en-us/azure/security/fundamentals/shared-responsibility) | Configure RBAC in the Azure Resource Manager. |
 
-In most cases, an `Owner` or `Project Administrator` has additional permissions to configure the product that can change the governance model. 
+Before examining the governance layers in detail, please consider the use case and assumptions of this example organization.
 
 ---
 
 ## Layer - Safeguard your Source Code with Branch Policies
 
 Because your source code defines and triggers deployments, your first line of defense is to secure your source code management (SCM) repository. In practice, this is achieved by using the [Pull Request workflow](https://docs.microsoft.com/en-us/azure/devops/repos/git/pull-requests-overview?view=azure-devops) and in combination with [branch policies](#) which define checks and requirements before code can be accepted. 
 
-![Pull Request Workflow](./images/git-pr-worflow.svg)
+![Pull Request Workflow](./images/flow-git-pr-worflow.svg)
 
 When planning your end to end governance model, your privileged users, e.g. `veggies-admins` will be responsible for configuring branch protection. Common branch protection checks to secure your deployments include:
 
@@ -97,6 +84,8 @@ Please note the workflow above is vendor agnostic. The pull request and branch p
 
 Once the code has been accepted into a protected branch the next layer of access controls will be applied by the build server, e.g. [Azure Pipelines](https://azure.microsoft.com/services/devops/pipelines/).
 
+---
+
 ## Layer - Secure Access to your Deployment Environments
 
 To deploy to Azure, Azure Pipelines needs access to your Azure resources. When deploying to Azure from a headless CI/CD agent, use a [service principal](https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) to which you also apply role based access controls. For example, create separate service principals for your production and non-production environments.
@@ -107,14 +96,15 @@ In Azure DevOps, a [Service Connection](https://docs.microsoft.com/azure/devops/
 
 <img src="./images/ado-service-connections-environments.svg">
 
+(TODO: replace image)
+
 _Note: the ["Environments"](https://docs.microsoft.com/azure/devops/pipelines/process/environments?view=azure-devops) feature in Azure DevOps serves more as a logical boundary and is useful for [audits and deployment histories](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/environments?view=azure-devops#deployment-history-within-environments). For details, see this [purple footnote](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/environments?view=azure-devops#user-permissions)._
 
 
 ### Securing Service Connections
 
 At a minimum configure [User](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml#user-permissions), [Project](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml#project-level-permissions) and [Pipeline](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml#pipeline-permissions) permissions for your Service Connection. This sets who or which pipeline can use the credentials underneath. Additionally we can in the Azure DevOps UI configure _under which conditions_ these credentials can be used by applying [Approvals and Checks](https://docs.microsoft.com/azure/devops/pipelines/process/approvals?view=azure-devops&tabs=check-pass).
 
-![Azure DevOps - Approvals and Checks](./images/ado-checks.png)
 
 When you configure a check, the Azure DevOps service will perform this check before giving the job (and required credentials) to a headless CI/CD agent to run. Common checks include:
 
@@ -126,10 +116,11 @@ When you configure a check, the Azure DevOps service will perform this check bef
 
 Note that these checks are often only applied to production environments, but not before to encourage innovation and experimentation by developers.
 
+---
+
 ## Layer - Apply RBAC to ARM Resources
 
-![Azure Pipelines - Deploy to ARM](./images/ado-deploy.svg)
+![Azure Pipelines - Deploy to ARM](./images/flow-ado-deploy.svg)
 
 Finally our deployment reaches ARM with the [RBAC options](https://docs.microsoft.com/en-us/azure/role-based-access-control/overview) you're already familiar with.
 
-_(11 December 2020 - Work in Progress)_
diff --git a/README.md b/README.md
@@ -2,22 +2,14 @@
 
 This demo project deploys Azure resources and bootstraps Azure DevOps projects to illustrate end-to-end RBAC, including best practices and pitfalls. It follows principles from Microsoft's [Cloud Adoption Framework (CAF)](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework).
 
-![End to End Governance](./images/e2e-governance-scm-to-arm.svg)
-
 | Status | Description |
 |:--|:--|
 | [![CD - Build Status](https://dev.azure.com/julie-msft/e2e-governance-demo/_apis/build/status/continuous-deployment-v2?branchName=deploy)](https://dev.azure.com/julie-msft/e2e-governance-demo/_build/latest?definitionId=34&branchName=deploy) | Deployment Azure Resources and Azure DevOps |
 | [![Detect Drift - Build Status](https://dev.azure.com/julie-msft/e2e-governance-demo/_apis/build/status/detect-drift-v2?branchName=deploy)](https://dev.azure.com/julie-msft/e2e-governance-demo/_build/latest?definitionId=35&branchName=deploy) | Detect Configuration Drift (scheduled nightly) |
 
-### Abstract
-
-When developing a governance model for your organization, it is important to remember that Azure Resource Management (ARM) is only _one_ way to manage resources. 
-
-When introducing automation via CI/CD pipelines, be aware that the Role Based Access Control (RBAC) model must be applied at **multiple layers**. This code sample deploys many of these layers and show how they can be configured together in a unified governance model. 
-
 ### Table of Contents
 
-- #### [Concept](./CONCEPT.md)
+- #### [Concept - End to End Governance](./docs/README.md)
   - Use Case, Requirements
   - Azure AD Groups and Role Based Access Controls (RBAC)
   - Securing environments - Production vs Non-production
@@ -31,24 +23,55 @@ When introducing automation via CI/CD pipelines, be aware that the Role Based Ac
   - Setup and Install
   - Deploy
 
-## Azure Resources Created
+## Abstract - Did You Close the Security Backdoor?
+
+When developing a governance model for your organization, it is important to remember that Azure Resource Management (ARM) is only _one_ way to manage resources. 
+
+[![End to End Governance](./images/e2e-governance-overview.svg)](./docs/README.md)
+
+When introducing automation via CI/CD pipelines, be aware that the Role Based Access Control (RBAC) model must be applied at **multiple layers**. This code sample deploys many of these layers and show how they can be configured together in a unified governance model. 
+
+In a nutshell, you can achieve this by leveraging Azure Active Directory and connecting all role assignments (both Azure DevOps _and_ ARM) to this single identity management plane.
+
+## How to Use this Demo
+
+The Terraform Infrastructure as Code in this repository will bootstrap various resources for you:
+
+- Azure Resources (ARM)
+- Azure AD Groups
+- Service Principals
+- Azure DevOps Projects incl. Service Connections, Security Group Assignments, etc.
+
+Preview of the Azure DevOps organization created by this code sample. Icons by [Smashicons](https://www.flaticon.com/authors/smashicons) not included.
+
+<img src="./images/ado-demo-home.png" alt="Preview of the Azure DevOps organization" width="600">
+
+#### Note: Random Generated Suffix
 
 When run Terraform will create the following resources. Note: random suffix used to ensure globally unique names, e.g. `u6t7` but are omitted here for clarity.
 
 ### Azure AD Groups
 
+Note: the `-all` groups are currently not in use but was introduced to address a conceptual problem (see [#12](https://github.com/Azure/devops-governance/issues/12)):
+
+- Azure Resource Manager uses an [_additive_ permissions](https://docs.microsoft.com/en-us/azure/role-based-access-control/overview#multiple-role-assignments) model
+- Azure DevOps uses a [_least_ permissions](https://docs.microsoft.com/en-us/azure/devops/organizations/security/about-permissions?view=azure-devops&tabs=preview-page) model
+
 | Group Name | ARM Role | Azure DevOps Role |
 |:--|:--|:--|
-| `infra` | Contributor | Contributor |
-| `fruits` | Contributor | Contributor |
-| `veggies` | Contributor | Contributor |
-| `infra-admins` | Owner | Project Administrators |
+| `fruits-all` | - | - |
+| `fruits-devs` | Contributor | Contributor |
 | `fruits-admins` | Owner | Project Administrators |
+| `veggies-all` | - | - |
+| `veggies-devs` | Contributor | Contributor |
 | `veggies-admins` | Owner | Project Administrators |
+| `infra-all` | - | - |
+| `infra-devs` | Contributor | Contributor |
+| `infra-admins` | Owner | Project Administrators |
 
-### Azure DevOps
+In the future when we bootstrap the `supermarket` project, we will need the `-all` groups as well.
 
-#### Projects
+### Azure DevOps Projects
 
 The project structure illustrates different governance models and their trade-offs. 
 
@@ -63,44 +86,29 @@ The project structure illustrates different governance models and their trade-of
 | `central-it` | No | Yes | Yes | 
 | `supermarket` | Yes | Yes | Yes | 
 
-
-Preview of the Azure DevOps organization created by this code sample. Icons by [Smashicons](https://www.flaticon.com/authors/smashicons) not included.
-
-<img src="./images/ado-demo-home.png" alt="" width="600">
-
-#### Azure Pipelines
+### Azure Pipelines
 
 - **Service Connection** using Contributor Service Principal
 - **Service Connection** using Key Vault read-only Service Principal for Pipeline Secrets Integration
 
-Note: At time of this writing there is [no REST API (v6 )for Key Vault Integration](https://docs.microsoft.com/en-us/rest/api/azure/devops/distributedtask/variablegroups/add?view=azure-devops-rest-6.0). Therefore it must be [configured manually](https://docs.microsoft.com/en-us/azure/devops/pipelines/release/azure-key-vault?view=azure-devops). 
-
+Note: At time of this writing there is [no REST API (v6) for Key Vault Integration](https://docs.microsoft.com/en-us/rest/api/azure/devops/distributedtask/variablegroups/add?view=azure-devops-rest-6.0). Therefore it must be [configured manually](https://docs.microsoft.com/en-us/azure/devops/pipelines/release/azure-key-vault?view=azure-devops). 
 
-### Azure Resources (ARM)
 
-#### Resource Groups aka Environment
+### Azure Resource Groups as "Environments"
 
-N.B. Each resource group is intended to be a logical and security boundary, i.e. "environment". In practice per [Cloud Adoption Framework](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework), these boundaries [should be Azure Subscriptions, not Resource Groups](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/govern/guides/standard/#governance-best-practices).
+To reduce complexity for CI/CD automation of _this_ open source repository, this project uses resource groups as a logical and security boundary for deployments.
 
 - `fruits-dev-rg`
 - `fruits-prod-rg`
 - `veggies-dev-rg`
 - `veggies-prod-rg`
 - `infra-shared-rg`
 
-#### Environment Resources
-
-Each "environment" has
-
-- Azure Storage Account
-- Azure Key Vault
-- Service Principal - Contributor for automation
-- Service Principal - Read-Only for Key Vault (used for Integration with Azure Pipelines Secrets)
-
+Be aware that in practice per [Cloud Adoption Framework](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework), these boundaries [should be Azure Subscriptions](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/govern/guides/standard/#governance-best-practices), not Resource Groups.
 
 # Contributing
 
-This demo was created with &hearts; by the FastTrack engineer [Julie Ng](https://github.com/julie-ng) and based on experience with Azure customers new to CI/CD and DevOps. After regularly breaking and fixing the demo in onboarding sessions, it was automated.
+This demo was created with &hearts; by the FastTrack engineer [Julie Ng](https://github.com/julie-ng) and based on previous experience as an Enterprise Architct and current experieince with Azure customers new to CI/CD and DevOps. After regularly breaking and fixing the demo in onboarding sessions, it was automated.
 
 Learn more about [FastTrack for Azure &rarr;](https://aka.ms/fasttrackforazure)
 

diff --git a/images/aad-groups.png b/images/aad-groups.png