Merge pull request #287793 from MutemwaRMasheke/mc-user-assigned-identity

Mc user assigned identity

Author: v-shils

articles/governance/machine-configuration/how-to/create-policy-definition.md

@@ -4,6 +4,7 @@ description: Learn how to create a machine configuration policy.
 ms.date: 02/01/2024
 ms.topic: how-to
 ---
+
 # How to create custom machine configuration policy definitions
 
 Before you begin, it's a good idea to read the overview page for [machine configuration][01], and
@@ -105,18 +106,36 @@ Parameters of the `New-GuestConfigurationPolicy` cmdlet:
 - **Description**: Policy description.
 - **Parameter**: Policy parameters provided in a hash table.
 - **PolicyVersion**: Policy version.
-- **Path**: Destination path where policy definitions are created.
+- **Path**: Destination path where policy definitions are created. Don't specify this parameter as
+  the path to a local copy of the package.
 - **Platform**: Target platform (Windows/Linux) for machine configuration policy and content
   package.
-- **Mode**: (case sensitive: `ApplyAndMonitor`, `ApplyAndAutoCorrect`, `Audit`) choose if the policy should audit
-  or deploy the configuration. The default is `Audit`.
-- **Tag** adds one or more tag filters to the policy definition
-- **Category** sets the category metadata field in the policy definition
+- **Mode**: (case sensitive: `ApplyAndMonitor`, `ApplyAndAutoCorrect`, `Audit`) choose if the
+  policy should audit or deploy the configuration. The default is `Audit`.
+- **Tag**: Adds one or more tag filters to the policy definition.
+- **Category**: Sets the category metadata field in the policy definition.
+- **LocalContentPath**: The path to the local copy of the `.zip` Machine Configuration package
+  file. This parameter is required if you're using a User Assigned Managed Identity to provide
+  access to an Azure Storge blob.
+- **ManagedIdentityResourceId**: The `resourceId` of the User Assigned Managed Identity that has
+  read access to the Azure Storage blob containing the `.zip` Machine Configuration package file.
+  This parameter is required if you're using a User Assigned Managed Identity to provide access to
+  an Azure Storge blob.
+- **ExcludeArcMachines**: Specifies that the Policy definition should exclude Arc machines. This
+  parameter is required if you are using a User Assigned Managed Identity to provide access to an
+  Azure Storge blob.
+
+> [!IMPORTANT]
+> Unlike Azure VMs, Arc-connected machines currently do not support User Assigned Managed
+> Identities. As a result, the `-ExcludeArcMachines` flag is required to ensure the exclusion of
+> those machines from the policy definition. For the Azure VM to download the assigned package and
+> apply the policy, the Guest Configuration Agent must be version `1.29.82.0` or higher for Windows
+> and version `1.26.76.0` or higher for Linux.
 
 For more information about the **Mode** parameter, see the page
 [How to configure remediation options for machine configuration][02].
 
-Create a policy definition that audits using a custom configuration package, in a specified path:
+Create a policy definition that **audits** using a custom configuration package, in a specified path:
 
 ```powershell
 $PolicyConfig      = @{
@@ -132,8 +151,7 @@ $PolicyConfig      = @{
 New-GuestConfigurationPolicy @PolicyConfig
 ```
 
-Create a policy definition that deploys a configuration using a custom configuration package, in a
-specified path:
+Create a policy definition that **enforces** a custom configuration package, in a specified path:
 
 ```powershell
 $PolicyConfig2      = @{
@@ -150,6 +168,30 @@ $PolicyConfig2      = @{
 New-GuestConfigurationPolicy @PolicyConfig2
 ```
 
+Create a policy definition that **enforces** a custom configuration package using a User-Assigned
+Managed Identity:
+
+```powershell
+$PolicyConfig3      = @{
+  PolicyId                  = '_My GUID_'
+  ContentUri                = $contentUri
+  DisplayName               = 'My deployment policy'
+  Description               = 'My deployment policy'
+  Path                      = './policies/deployIfNotExists.json'
+  Platform                  = 'Windows'
+  PolicyVersion             = 1.0.0
+  Mode                      = 'ApplyAndAutoCorrect'
+  ContentLocalPath          = "C:\Local\Path\To\Package"      # Required parameter for managed identity
+  ManagedIdentityResourceId = "YourManagedIdentityResourceId" # Required parameter for managed identity
+}
+
+New-GuestConfigurationPolicy @PolicyConfig3 -ExcludeArcMachines
+```
+
+> [!NOTE]
+> You can retrieve the resorceId of a nmanaged identity using the `Get-AzUserAssignedIdentity`
+> PowerShell cmdlet.
+
 The cmdlet output returns an object containing the definition display name and path of the policy
 files. Definition JSON files that create audit policy definitions have the name
 `auditIfNotExists.json` and files that create policy definitions to apply configurations have the

articles/governance/machine-configuration/how-to/develop-custom-package/4-publish-package.md

@@ -110,7 +110,8 @@ $contentUri = New-AzStorageBlobSASToken @tokenParams
 ## Next step
 
 > [!div class="nextstepaction"]
-> [Sign a custom machine configuration package](./5-sign-package.md)
+> [Provide secure access to a custom machine configuration package](./5-access-package.md)
+
 
 <!-- Reference link definitions -->
 [01]: ../../overview.md

articles/governance/machine-configuration/how-to/develop-custom-package/5-access-package.md

@@ -0,0 +1,83 @@
+---
+title: How to access custom machine configuration package artifacts
+description: Learn how to provide access to a machine configuration package file in Azure blob storage .
+ms.date: 08/28/2024
+ms.topic: how-to
+ms.custom: devx-track-azurepowershell
+---
+
+# How to provide secure access to custom machine configuration packages
+
+This page provides a guide on how to provide access to Machine Configuration packages stored in
+Azure storage by using the resource ID of a user-assigned managed identity or a Shared Access
+Signature (SAS) token.
+
+## Prerequisites
+
+- Azure subscription
+- Azure Storage account with the Machine Configuration package
+
+## Steps to provide access to the package
+
+The following steps prepare your resources for more secure operations. TThe code snippets for the
+steps include values in angle brackets, like `<storage-account-container-name>`, which you must
+replace with a valid value when following the steps. If you just copy and paste the code, the
+commands may raise errors due to invalid values.
+
+### Using a User Assigned Identity 
+
+> [!IMPORTANT]
+> Please note that, unlike Azure VMs, Arc-connected machines currently do not support User-Assigned
+> Managed Identities.
+
+You can grant private access to a machine configuration package in an Azure Storage blob by
+assigning a [User-Assigned Identity][01] to a scope of Azure VMs. For this to work, you need to
+grant the managed identity read access to the Azure storage blob. This involves assigning the
+"Storage Blob Data Reader" role to the identity at the scope of the blob container. This setup
+ensures that your Azure VMs can securely read from the specified blob container using the
+user-assigned managed identity. To learn how you can assign a User Assigned Identity at scale, see
+[Use Azure Policy to assign managed identities][02].
+
+### Using a SAS Token
+
+Optionally, you can add a shared access signature (SAS) token in the URL to ensure secure access to
+the package. The below example generates a blob SAS token with read access and returns the full
+blob URI with the shared access signature token. In this example, the token has a time limit of
+three years.
+
+```powershell
+$startTime = Get-Date
+$endTime   = $startTime.AddYears(3)
+
+$tokenParams = @{
+    StartTime  = $startTime
+    ExpiryTime = $endTime
+    Container  = '<storage-account-container-name>'
+    Blob       = '<configuration-blob-name>'
+    Permission = 'r'
+    Context    = '<storage-account-context>'
+    FullUri    = $true
+}
+
+$contentUri = New-AzStorageBlobSASToken @tokenParams
+```
+
+## Summary
+
+By using the resource ID of a user-assigned managed identity or SAS token, you can securely provide
+access to Machine Configuration packages stored in Azure storage. The additional parameters ensure
+that the package is retrieved using the managed identity and that Azure Arc machines aren't
+included in the policy scope.
+
+## Next Steps
+- After creating the policy definition, you can assign it to the appropriate scope, like management
+  group, subscription, or resource group, within your Azure environment.
+- Remember to monitor the policy compliance status and make any necessary adjustments to your
+  Machine Configuration package or policy assignment to meet your organizational requirements.
+
+> [!div class="nextstepaction"]
+> [Sign a custom machine configuration package](./6-sign-package.md)
+
+<!-- Reference link definitions -->
+[01]: /entra/identity/managed-identities-azure-resources/managed-identity-best-practice-recommendations#using-user-assigned-identities-to-reduce-administration
+[02]: /entra/identity/managed-identities-azure-resources/how-to-assign-managed-identity-via-azure-policy

articles/governance/machine-configuration/how-to/develop-custom-package/5-sign-package.md renamed to articles/governance/machine-configuration/how-to/develop-custom-package/6-sign-package.md

@@ -8,12 +8,14 @@ ms.custom: linux-related-content
 
 # How to sign machine configuration packages
 
-Machine configuration custom policies use SHA256 hash to validate the policy package hasn't
+Machine configuration custom policies use a SHA256 hash to validate that the policy package hasn't
 changed. Optionally, customers may also use a certificate to sign packages and force the machine
 configuration extension to only allow signed content.
 
-To enable this scenario, there are two steps you need to complete. Run the cmdlet to sign the
-content package, and append a tag to the machines that should require code to be signed.
+To enable this scenario, there are two steps you need to complete:
+
+1. Run the cmdlet to sign the content package.
+1. Append a tag to the machines that should require code to be signed.
 
 ## Signature validation using a code signing certificate
 
@@ -24,7 +26,7 @@ testing purposes to follow along with the example.
 
 ## Windows signature validation
 
-```azurepowershell-interactive
+```powershell
 # How to create a self sign cert and use it to sign Machine Configuration
 # custom policy package
 
@@ -34,26 +36,35 @@ $codeSigningParams = @{
     DnsName       = 'GCEncryptionCertificate'
     HashAlgorithm = 'SHA256'
 }
-$mycert = New-SelfSignedCertificate @codeSigningParams
+$certificate = New-SelfSignedCertificate @codeSigningParams
 
 # Export the certificates
-$mypwd = ConvertTo-SecureString -String "Password1234" -Force -AsPlainText
-$mycert | Export-PfxCertificate -FilePath C:\demo\GCPrivateKey.pfx -Password $mypwd
-$mycert | Export-Certificate -FilePath "C:\demo\GCPublicKey.cer" -Force
+$privateKey = @{
+    Cert     = $certificate
+    Password = Read-Host "Enter password for private key" -AsSecureString
+    FilePath = '<full-path-to-export-private-key-pfx-file>'
+}
+$publicKey = @{
+    Cert     = $certificate
+    FilePath = '<full-path-to-export-public-key-cer-file>'
+    Force    = $true
+}
+Export-PfxCertificate @privateKey
+Export-Certificate    @publicKey
 
 # Import the certificate
 $importParams = @{
-    FilePath          = 'C:\demo\GCPrivateKey.pfx'
-    Password          = $mypwd
+    FilePath          = $privateKey.FilePath
+    Password          = $privateKey.Password
     CertStoreLocation = 'Cert:\LocalMachine\My'
 }
 Import-PfxCertificate @importParams
 
 # Sign the policy package
-$certToSignThePackage = Get-ChildItem -Path cert:\LocalMachine\My |
-    Where-Object { $_.Subject-eq "CN=GCEncryptionCertificate" }
+$certToSignThePackage = Get-ChildItem -Path Cert:\LocalMachine\My |
+    Where-Object { $_.Subject -eq "CN=GCEncryptionCertificate" }
 $protectParams = @{
-    Path        = 'C:\demo\AuditWindowsService.zip'
+    Path        = '<path-to-package-to-sign>'
     Certificate = $certToSignThePackage
     Verbose     = $true
 }
@@ -62,51 +73,64 @@ Protect-GuestConfigurationPackage @protectParams
 
 ## Linux signature validation
 
-```azurepowershell-interactive
+```powershell
 # generate gpg key
 gpg --gen-key
 
+$emailAddress      = '<email-id-used-to-generate-gpg-key>'
+$publicGpgKeyPath  = '<full-path-to-export-public-key-gpg-file>'
+$privateGpgKeyPath = '<full-path-to-export-private-key-gpg-file>'
+
 # export public key
-gpg --output public.gpg --export <email-id-used-to-generate-gpg-key>
+gpg --output $publicGpgKeyPath --export $emailAddress
 
 # export private key
-gpg --output private.gpg --export-secret-key <email-id-used-to-generate-gpg-key>
+gpg --output $privateGpgKeyPath --export-secret-key $emailAddress
 
 # Sign linux policy package
 Import-Module GuestConfiguration
 $protectParams = @{
-    Path              = './not_installed_application_linux.zip'
-    PrivateGpgKeyPath = './private.gpg'
-    PublicGpgKeyPath  = './public.gpg'
+    Path              = '<path-to-package-to-sign>'
+    PrivateGpgKeyPath = $privateGpgKeyPath
+    PublicGpgKeyPath  = $publicGpgKeyPath
     Verbose           = $true
 }
 Protect-GuestConfigurationPackage
 ```
 
 Parameters of the `Protect-GuestConfigurationPackage` cmdlet:
 
-- **Path**: Full path of the machine configuration package.
+- **Path**: Full path to the machine configuration package.
 - **Certificate**: Code signing certificate to sign the package. This parameter is only supported
   when signing content for Windows.
+- **PrivateGpgKeyPath**: Full path to the private key `.gpg` file. This parameter is only supported
+  when signing content for Linux.
+- **PublicGpgKeyPath**: Full path to the public key `.gpg` file. This parameter is only supported
+  when signing content for Linux.
+
 
 ## Certificate requirements
 
-The machine configuration agent expects the certificate public key to be present in "Trusted Publishers" on Windows machines and in the path `/usr/local/share/ca-certificates/gc`
-on Linux machines. For the node to verify signed content, install the certificate public key on the
-machine before applying the custom policy. This process can be done using any technique inside the
-VM or by using Azure Policy. An example template is available
-[to deploy a machine with a certificate][01]. The Key Vault access policy must allow the Compute
-resource provider to access certificates during deployments. For detailed steps, see
+The machine configuration agent expects the certificate public key to be present in "Trusted
+Publishers" on Windows machines and in the path `/usr/local/share/ca-certificates/gc` on Linux
+machines. For the node to verify signed content, install the certificate public key on the machine
+before applying the custom policy.
+
+You can install the certificate public key using normal tools inside the VM or by using Azure
+Policy. An [example template using Azure Policy][01] shows how you can deploy a machine with a
+certificate. The Key Vault access policy must allow the Compute resource provider to access
+certificates during deployments. For detailed steps, see
 [Set up Key Vault for virtual machines in Azure Resource Manager][02].
 
 Following is an example to export the public key from a signing certificate, to import to the
 machine.
 
 ```azurepowershell-interactive
-$Cert = Get-ChildItem -Path cert:\LocalMachine\My |
-    Where-Object { $_.Subject-eq "CN=mycert3" } |
+$Cert = Get-ChildItem -Path Cert:\LocalMachine\My |
+    Where-Object { $_.Subject-eq 'CN=<CN-of-your-signing-certificate>' } |
     Select-Object -First 1
-$Cert | Export-Certificate -FilePath "$env:temp\DscPublicKey.cer" -Force
+
+$Cert | Export-Certificate -FilePath '<path-to-export-public-key-cer-file>' -Force
 ```
 
 ## Tag requirements

articles/governance/machine-configuration/how-to/develop-custom-package/overview.md

@@ -33,7 +33,8 @@ non-Azure machine.
 1. [Create a custom machine configuration package artifact][04]
 1. [Test the package artifact][05]
 1. [Publish the package artifact][06]
-1. [Sign the package artifact][07]
+1. [Provide access to a package][07]
+1. [Sign the package artifact][08]
 
 <!-- Link reference definitions -->
 [01]: ../../overview.md
@@ -42,4 +43,5 @@ non-Azure machine.
 [04]: ./2-create-package.md
 [05]: ./3-test-package.md
 [06]: ./4-publish-package.md
-[07]: ./5-sign-package.md
+[07]: ./5-access-package.md
+[08]: ./6-sign-package.md

articles/governance/machine-configuration/toc.yml

@@ -41,11 +41,15 @@ items:
           href: ./how-to/develop-custom-package/3-test-package.md
         - name: 4. Publish a custom package
           href: ./how-to/develop-custom-package/4-publish-package.md
-        - name: 5. Sign a custom package
-          href: ./how-to/develop-custom-package/5-sign-package.md
+        - name: 5. Access a custom package
+          href: ./how-to/develop-custom-package/5-access-package.md
+        - name: 6. Sign a custom package
+          href: ./how-to/develop-custom-package/6-sign-package.md
     # Planned, not written
     # - name: Update a custom configuration
     #   href: ./how-to/update-configuration.md
+    - name: Create a custom policy definition
+      href: ./how-to/create-policy-definition.md
     - name: Assign a configuration
       items:
         - name: Overview
@@ -56,8 +60,6 @@ items:
           href: ./how-to/assign-configuration/bicep.md
         - name: Using Terraform
           href: ./how-to/assign-configuration/terraform.md
-    - name: Create a custom policy definition
-      href: ./how-to/create-policy-definition.md
 
 - name: Concepts
   items: