Merge pull request #1034 from Azure/feature/apy/keepDFCPlanAssignments

Added capabilities to manage DFC Plan Policy Assignments via EPAC

Author: apybar

Docs/guidance-exemptions.md

@@ -8,7 +8,7 @@ In the past, CSV has been the preferred tool in EPAC. However, the introduction
 
 ## Updating exemptions manually
 
-There are some usecases for manual update of the exemptions file. Generally, it is a consideration of what will be less effort to complete.
+There are some use cases for manual update of the exemptions file. Generally, it is a consideration of what will be less effort to complete.
 
 ### Expiration Update
 
@@ -20,7 +20,7 @@ Rather than update and export, an update to the date field can be accomplished w
 1. Open the json/jsonc/csv file used to manage Exemptions
 1. Update Content
     1. Search for the policyAssignmentId, including the full assignment path
-        1. Example: ```"policyAssignmentId": "/providers/Microsoft.Management/managementGroups/[ManagmenetGroupName]/providers/Microsoft.Authorization/policyAssignments/[PolicyAssignmentName]"```
+        1. Example: ```"policyAssignmentId": "/providers/Microsoft.Management/managementGroups/[ManagementGroupName]/providers/Microsoft.Authorization/policyAssignments/[PolicyAssignmentName]"```
     1. Modify the ```expiresOn``` field within the related block with the new timestamp
         1. Format: "YYYY-MM-DDTmm:hh:ssZ"
         1. Example: "2025-01-01T01:00:00Z"
@@ -37,7 +37,7 @@ In these cases, find each listing for affected assignments in the CSV/JSON file,
 
 1. Export Current Exemptions for pacSelector
 1. Update Content
-    1. Replace Root Management Group Name (Tenant GUID) with current assignment location (Tenant Intermediate Root Managment Group Name):
+    1. Replace Root Management Group Name (Tenant GUID) with current assignment location (Tenant Intermediate Root Management Group Name):
         1. ```"policyAssignmentId"```
         1. Epac Managed Exemptions: ```metadata\epacMetadata\"policyAssignmentId"```
     1. Replace temporary pacSelector with main pacSelector:

Docs/guidance-lighthouse.md

@@ -0,0 +1,108 @@
+# Lighhouse Subscription Management with EPAC
+
+## Overview
+
+While EPAC is not currently able to handle all use cases for lighthouse integration, there are twe specific use cases requested through GH issues that have been accounted for.  The following is offered as guidance around those use cases.  It is possible that the work done to account for these use cases does allow for other, untested, functionality; so trying different permutations of below mentioned pacEnv settings may result in additional, undocumented functionality.
+
+## Use-case 1: Additional role assignment from managing tenant to managed subscriptions
+
+There are some instances where you may need to make additional role assignments to managed subscriptions while assigning policy at your managing tenant.  The guidance below will cover a specific use case and all EPAC configurations necessary to achieve this use case.
+
+### Use-case
+
+When assigning Deploy Diagnostics Settings type policies at a scope in your managing tenant, you want to write the diagnostics data to a managed (lighhouse joined) subscription.
+
+### Configurations
+
+1. pacSelector Configuration.
+
+In your global settings file find the specific pagEnvironments that will have diagnostic settings policy deployed to them where the diagnostics data needs to be written to lighthouse managed subscription.  Add the following to that pacSelector in the global settings file:
+
+                "managedTenant": {
+                    "managedTenantId": "00000000-1111-2222-3333-444444444444",
+                    "managedTenantScopes": [
+                        "/subscriptions/00000000-1111-2222-3333-444444444444",
+                        "/subscriptions/00000000-1111-2222-3333-444444444444"
+                    ]
+                },
+
+managedTenantId - The tenant containing the lighthouse managed (joined) subsciptions.
+managedTenantScopes - A list of all subscriptions that may need "remote" role assignments made to them.  These would be the subscriptions that contain, for example, the Log Analytics Workspace or Storage Account that your are writing diagnostics data to across tenants.  Every subscription where this pacEnvironment may need to make a role assignment to must be listed.
+
+1. In the assignment file add an additionalRoleAssignments section for the file or node so that the assignment knows that for assigning this policy, at this (managing) pacEnvironment, it needs to perform and additional role assignment at the remote (managed) scope.  The scope of the assignment must be included in the managedTenantScopes for the pacEnvironment in the globalSettings file.
+
+                "additionalRoleAssignments": {
+                    "managingTenantScopeEnv": [
+                        {
+                            "roleDefinitionId": "/providers/microsoft.authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
+                            "scope": "/subscriptions/00000000-1111-2222-3333-444444444444",
+                            "crossTenant": true
+                        }
+                    ]
+                },
+        
+## Use-case 2: Make role assignments at lighthouse managed scopes while deploying to the cast instance of that subscription in your tenant.
+
+This feature is primarily meant for MSPs managing customer subscriptions.  While the complete implementation is not perfiect, this is due to a deficiency in lighthouse functionality and guidance on the best way to work around that with EPAC is provided.  
+
+### Use-case
+
+This feature allows users to assign policies with role assignments to managed subscriptions without direct access to the customer tenant.
+
+### Configurations
+
+1. Lighthouse Setup  - Before any of the EPAC functionality can work, you must first provide the service principal executing EPAC (in the managing tenant) the appropriate access in the managed (lighthouse invited) subscriptions.  There are two components to this.  Because you can configure EPAC to run plans, policy deployments, and role deployments with different service principals or use the same service principal for all of these actions, the guidance here will be written for an implementation using a singular service principal to perform all 3 actions.  If you are using a different service principal for each of these stages, adjust the lighthouse template accordingly.  
+    1. Determing which roles and permissions are needed for basic EPAC functionality.  The combined required roles are Reader, Resource Policy Contributor, and User Access Administrator.
+    1. Determine which roles will be need to be assigned to your policies (DINE/Modify).  This is likely a dynamic list and will change over time.  Be as proactive and forward thinking as you can in developing this list as any changes to this list will require a re-invite for each lighthouse subscription.
+
+Once These two lists have been developed create your lighthouse invite template.
+
+1. Open Lighthouse in your managing tenant
+1. Click "Manage your Customers"
+1. Click "Create ARM Template"
+1. Give the offer a name and description.
+1. Choose the scopt your will request to manage
+1. Click "+ Add authorization"
+    1. Choose "Principal type" (Service Principal for EPAC)
+    1. Select your principal
+    1. Add Display name
+    1. Select your role (from the list developed in item 1 above e.g. Reader, Resource Policy Contributor, and User Access Administrator)
+    1. Add authorization for all roles that need to be assigned to your principal
+    1. Click "View template"
+    1. Download the template and open it to edit
+    1. In the "authorizations" section, find all instances where you are assigning the User Access Administrator (18d7d88d-d35e-4fb5-a5c3-7773c20a72d9)
+    1. Add the roles determined above in item 2 in a "delegatedRoleDefinitionIds" array, the delegated roles that your User Access Administrator will be able to add and remove.
+
+        Example:
+
+        "delegatedRoleDefinitionIds": [
+            "b24988ac-6180-42a0-ab88-20f7382dd24c",   <----Contributor
+            "f353d9bd-d4a6-484e-a77a-8050b599b867",   <----Automation Contributor
+            "91c1777a-f3dc-4fae-b103-61d183457e46"    <----Managed Services Registration assignment Delete Role
+        ]
+
+    Once this is completed send this file to your customer to be executed in each of their subscriptions where you will need to manage policies.  It will take between 30 seconds and 30 minutes for the registration to comnplete (usually closere to 30 seconds).  To view your customers go to lighthouse in your tenant and view customers.  If you are not seeing all of them you need to change your global filters.
+
+    After the Lighthouse portion is complete you will need to set things up in EPAC for each target subscription.  Below is an example with explanation of the relevant properties.
+
+            {
+                "pacSelector": "epac-ManagedCustomerSubscription1",
+                "cloud": "AzureCloud",
+                "tenantId": "00000000-1111-2222-3333-444444444444",                                <----My Tenant
+                "deploymentRootScope": "/subscriptions/999999-8888-7777-6666-555555555555",        <----Customer subscription
+                "managedSubscription": true,                                                       <----Indicates this is a managed subscription
+                "managedIdentityLocation": "eastus2",
+                "managedTenant": {
+                    "managedTenantId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",                     <----Customer tenant ID
+                    "managedTenantScopes": [
+                        "/subscriptions/999999-8888-7777-6666-555555555555"                        <----Customer subscription
+                    ]
+                },
+                "desiredState": {
+                    "strategy": "full",
+                    "keepDfcSecurityAssignments": false
+                },
+                "deployedBy": "My Org Admins"                                                      <----Friendly name to indicate who is deploying policy
+            },
+
+NOTE:  Because Lighthouse does not allow grouping of "cast" lighthouse subscriptions to be grouped in the managing tenant, and does not allow for management groups to be cast, each unique subscription must be a unique pacEnvironment.  The best way to perform "mass" deployments is through custom pipelines that will create multiples plans with unique names and then run multiple deployments.  It is recommended to use Self-hosted agents in this scenario as you can create larger SKU agents that will allow for parallelism.

Docs/guidance-remediation.md

@@ -15,11 +15,11 @@ There are several different ways that policies that affect change can be deploye
     1. Allows use of Remediation Tasks for the policyAssignment even though it is disabled
     1. Considerations:
         1. Much faster, requiring little planning
-        1. Will not update new deployments, but allows remediation of existing deployments as approval is receieved
+        1. Will not update new deployments, but allows remediation of existing deployments as approval is received
         1. New-AzRemediationTasks **will** by default enforce policyAssignments with the *DoNotEnforce* configuration. It is recommended to either use the switch parameter `-OnlyDefaultEnforcementMode`, have these policyAssignments removed or set to default enforcement before that pipeline is enabled
 1. Use of Effect *Override* functionality
     1. Override can be set to any Effect that is supported by that policy
-    1. When overriding a policySet, the policyDefinitionReferenceId will be used to identify which policies recieve audit vs auditIfNotExist effect if both exist
+    1. When overriding a policySet, the policyDefinitionReferenceId will be used to identify which policies receive audit vs auditIfNotExist effect if both exist
     1. If no effects are available, an override to *audit* was accepted in all tested cases
     1. Considerations:
         1. Much more granular control, requiring review of available effects and generating a list of overrides
@@ -58,7 +58,7 @@ When this is enabled, Azure Resource Manager Configuration is being managed at o
 
 The objective at this point is to reduce the administration teams' effort to correct deployments that do not meet security standards outlined by the company by maintaining the configuration proactively, which is to say without prompting from human administrators to do so. While this *can* be a manual task, the EPAC CI/CD Pipeline for Remediation provided in the StarterKit should be leveraged for this in order to reduce the effort of the administration team.
 
-While Infrastructure as Code is an excellent first layer, the second layer in a Defense In Depth model is to enforce this. In Azure Resource Manager, we use Azure Policy Remediation Tasks to accomplish this. Whereas Start-AzPolicyRemediation does allow very targetted deployments, EPAC seeks to take corrective action in broad swaths using the security structure that has been implemented. To this end, the cmdlet New-AzRemediationTasks was created, and can be used in a pipeline to remediate all policyAssignments (that have that capability) in a single pipeline action that should be scheduled with a cron trigger.
+While Infrastructure as Code is an excellent first layer, the second layer in a Defense In Depth model is to enforce this. In Azure Resource Manager, we use Azure Policy Remediation Tasks to accomplish this. Whereas Start-AzPolicyRemediation does allow very targeted deployments, EPAC seeks to take corrective action in broad swaths using the security structure that has been implemented. To this end, the cmdlet New-AzRemediationTasks was created, and can be used in a pipeline to remediate all policyAssignments (that have that capability) in a single pipeline action that should be scheduled with a cron trigger.
 
 Once the *Updating Security Posture* Workstreams above are complete, it is time to move on into the upper tiers of CMM for ARM Governance, congratulations! The environment will be largely self-correcting after this is complete.
 

Docs/guidance-scope-exclusions.md

@@ -8,7 +8,7 @@ There are several means of excluding a scope from a policyAssignment; however, i
 
 There are several ways of accomplishing scope changes, and the logic behind these decisions is fairly straightforward. However, that does not mean that there is an objectively right answer in all cases, and these pieces of guidance should aid in choosing a path forward.
 
-In all cases, simply moving the assignments down to a more specific level could solve the problem, but it is rarely the most effecient. Certainly assigning by each Resource Group can reduce the number of exclusions, but at the cost of a fail-open configuration for new Resource Groups as well as a significantly higher number of assignments. This is rarely, if ever, preferred.
+In all cases, simply moving the assignments down to a more specific level could solve the problem, but it is rarely the most efficient. Certainly assigning by each Resource Group can reduce the number of exclusions, but at the cost of a fail-open configuration for new Resource Groups as well as a significantly higher number of assignments. This is rarely, if ever, preferred.
 
 ### Decision: Periodic Review
 
@@ -18,7 +18,7 @@ If there is a requirement to review the scope change periodically, to confirm th
 
 While a decision around the scope will determine to which scope policyAssignments are applied, there are often changes to the Effect in order to descope individual items within a policySet. In this case, NotScope is generally the focus within the policyAssignment in order to provide that level of control.
 
-Example: Exempt a workload contained within a managment group from requiring Storage to use TLS 1.2 defined in the policySet [Enforce-EncryptTransit_20241211](https://www.azadvertizer.net/azpolicyinitiativesadvertizer/Enforce-EncryptTransit_20241211.html) in order to support a legacy service which must use TLS 1.1, while retaining the enforcement for all other Services.
+Example: Exempt a workload contained within a management group from requiring Storage to use TLS 1.2 defined in the policySet [Enforce-EncryptTransit_20241211](https://www.azadvertizer.net/azpolicyinitiativesadvertizer/Enforce-EncryptTransit_20241211.html) in order to support a legacy service which must use TLS 1.1, while retaining the enforcement for all other Services.
 
 ### Decision: Scope at policyAssignment or pacSelector
 

Docs/index.md

@@ -4,10 +4,12 @@ Enterprise Azure Policy as Code (EPAC for short) is a number of PowerShell scrip
 
 ## Latest Updates
 
-For all EPAC changes and newest updates, please visit our [GitHub Releases Page](https://github.com/Azure/enterprise-azure-policy-as-code/releases).
+### v11.0.0 is Coming!
 
 > [!CAUTION]
-> Review the Breaking changes in v10.0.0 carefully to avoid issues with your EPAC instance. The changes are [documented here](start-changes.md#breaking-changes-in-v1000).
+> Review the Breaking changes in v11.0.0 carefully to avoid issues with your EPAC instance. The changes are [documented here](start-changes.md).
+
+For all EPAC changes and newest updates, please visit our [GitHub Releases Page](https://github.com/Azure/enterprise-azure-policy-as-code/releases).
 
 > [!IMPORTANT]
 > Starting with v8.0.0, Enterprise Policy as Code (EPAC) is tracking the usage using [Customer Usage Attribution](https://learn.microsoft.com/en-us/partner-center/marketplace/azure-partner-customer-usage-attribution). In accordance with Microsoft's privacy policies, you have the right to **opt-out** of this tracking. Please review [Telemetry below](#telemetry-tracking-using-customer-usage-attribution-pid) and [Microsoft Privacy](https://privacy.microsoft.com/en-US/) for more information.