Skip to content

Commit cada2d0

Browse files
michaeltlombardimichaeltlombardi
committed
(Editorial) Updates from review
1 parent 3142073 commit cada2d0

File tree

5 files changed

+143
-68
lines changed

5 files changed

+143
-68
lines changed

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

Lines changed: 37 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ description: Learn how to create a machine configuration policy.
44
ms.date: 02/01/2024
55
ms.topic: how-to
66
---
7+
78
# How to create custom machine configuration policy definitions
89

910
Before you begin, it's a good idea to read the overview page for [machine configuration][01], and
@@ -105,20 +106,31 @@ Parameters of the `New-GuestConfigurationPolicy` cmdlet:
105106
- **Description**: Policy description.
106107
- **Parameter**: Policy parameters provided in a hash table.
107108
- **PolicyVersion**: Policy version.
108-
- **Path**: Destination path where policy definitions are created. This is NOT a path a local copy of the package.
109+
- **Path**: Destination path where policy definitions are created. Don't specify this parameter as
110+
the path to a local copy of the package.
109111
- **Platform**: Target platform (Windows/Linux) for machine configuration policy and content
110112
package.
111-
- **Mode**: (case sensitive: `ApplyAndMonitor`, `ApplyAndAutoCorrect`, `Audit`) choose if the policy should audit
112-
or deploy the configuration. The default is `Audit`.
113-
- **Tag** adds one or more tag filters to the policy definition
114-
- **Category** sets the category metadata field in the policy definition
115-
- **LocalContentPath** (Optional) - The path to the local copy of the `.zip` Machine Configuration package file (Required if you are using a User Assigned Managed Identity to provide access to an Azure Storge blob)
116-
- **ManagedIdentityResourceId** (Optional) - The resourceId of the User Assigned Managed Identity with read access to the Azure Storage blob containing the `.zip` Machine Configuration package file (Required if you are using a User Assigned Managed Identity to provide access to an Azure Storge blob)
117-
- **`-ExcludeArcMachines`** (Optional) - A flag to exclude Arc machines from the generated Policy definition (Required if you are using a User Assigned Managed Identity to provide access to an Azure Storge blob)
113+
- **Mode**: (case sensitive: `ApplyAndMonitor`, `ApplyAndAutoCorrect`, `Audit`) choose if the
114+
policy should audit or deploy the configuration. The default is `Audit`.
115+
- **Tag**: Adds one or more tag filters to the policy definition.
116+
- **Category**: Sets the category metadata field in the policy definition.
117+
- **LocalContentPath**: The path to the local copy of the `.zip` Machine Configuration package
118+
file. This parameter is required if you're using a User Assigned Managed Identity to provide
119+
access to an Azure Storge blob.
120+
- **ManagedIdentityResourceId**: The `resourceId` of the User Assigned Managed Identity that has
121+
read access to the Azure Storage blob containing the `.zip` Machine Configuration package file.
122+
This parameter is required if you're using a User Assigned Managed Identity to provide access to
123+
an Azure Storge blob.
124+
- **ExcludeArcMachines**: Specifies that the Policy definition should exclude Arc machines. This
125+
parameter is required if you are using a User Assigned Managed Identity to provide access to an
126+
Azure Storge blob.
118127

119128
> [!IMPORTANT]
120-
> - Please note that, 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.
121-
> - Additionally, for the Azure VM to download the assigned package and apply the policy, the Guest Configuration Windows Agent Version 1.29.82.0 OR Linux Agent Version 1.26.76.0 is required
129+
> Unlike Azure VMs, Arc-connected machines currently do not support User Assigned Managed
130+
> Identities. As a result, the `-ExcludeArcMachines` flag is required to ensure the exclusion of
131+
> those machines from the policy definition. For the Azure VM to download the assigned package and
132+
> apply the policy, the Guest Configuration Agent must be version `1.29.82.0` or higher for Windows
133+
> and version `1.26.76.0` or higher for Linux.
122134
123135
For more information about the **Mode** parameter, see the page
124136
[How to configure remediation options for machine configuration][02].
@@ -156,26 +168,29 @@ $PolicyConfig2 = @{
156168
New-GuestConfigurationPolicy @PolicyConfig2
157169
```
158170

159-
Create a policy definition that **enforces** a custom configuration package using a User-Assigned Managed Identity:
171+
Create a policy definition that **enforces** a custom configuration package using a User-Assigned
172+
Managed Identity:
160173

161174
```powershell
162175
$PolicyConfig3 = @{
163-
PolicyId = '_My GUID_'
164-
ContentUri = $contentUri
165-
DisplayName = 'My deployment policy'
166-
Description = 'My deployment policy'
167-
Path = './policies/deployIfNotExists.json'
168-
Platform = 'Windows'
169-
PolicyVersion = 1.0.0
170-
Mode = 'ApplyAndAutoCorrect'
171-
contentLocalPath = "C:\Local\Path\To\Package" # Required parameter for managed identity
172-
managedIdentityResourceId = "YourManagedIdentityResourceId" # Required parameter for managed identity
176+
PolicyId = '_My GUID_'
177+
ContentUri = $contentUri
178+
DisplayName = 'My deployment policy'
179+
Description = 'My deployment policy'
180+
Path = './policies/deployIfNotExists.json'
181+
Platform = 'Windows'
182+
PolicyVersion = 1.0.0
183+
Mode = 'ApplyAndAutoCorrect'
184+
ContentLocalPath = "C:\Local\Path\To\Package" # Required parameter for managed identity
185+
ManagedIdentityResourceId = "YourManagedIdentityResourceId" # Required parameter for managed identity
173186
}
174187
175188
New-GuestConfigurationPolicy @PolicyConfig3 -ExcludeArcMachines
176189
```
190+
177191
> [!NOTE]
178-
> You can retrieve the resorceId of a nmanaged identity using the `Get-AzUserAssignedIdentity` Powershell cmdlet.
192+
> You can retrieve the resorceId of a nmanaged identity using the `Get-AzUserAssignedIdentity`
193+
> PowerShell cmdlet.
179194
180195
The cmdlet output returns an object containing the definition display name and path of the policy
181196
files. Definition JSON files that create audit policy definitions have the name

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,8 @@ $contentUri = New-AzStorageBlobSASToken @tokenParams
110110
## Next step
111111

112112
> [!div class="nextstepaction"]
113-
> [Sign a custom machine configuration package](./6-sign-package.md)
113+
> [Provide secure access to a custom machine configuration package](./5-access-package.md)
114+
114115

115116
<!-- Reference link definitions -->
116117
[01]: ../../overview.md

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

Lines changed: 45 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7,22 +7,43 @@ ms.custom: devx-track-azurepowershell
77
---
88

99
# How to provide secure access to custom machine configuration packages
10-
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.
10+
11+
This page provides a guide on how to provide access to Machine Configuration packages stored in
12+
Azure storage by using the resource ID of a user-assigned managed identity or a Shared Access
13+
Signature (SAS) token.
1114

1215
## Prerequisites
16+
1317
- Azure subscription
1418
- Azure Storage account with the Machine Configuration package
15-
19+
1620
## Steps to provide access to the package
21+
22+
The following steps prepare your resources for more secure operations. TThe code snippets for the
23+
steps include values in angle brackets, like `<storage-account-container-name>`, which you must
24+
replace with a valid value when following the steps. If you just copy and paste the code, the
25+
commands may raise errors due to invalid values.
26+
1727
### Using a User Assigned Identity
1828

1929
> [!IMPORTANT]
20-
> Please note that, unlike Azure VMs, Arc-connected machines currently do not support User-Assigned Managed Identities.
30+
> Please note that, unlike Azure VMs, Arc-connected machines currently do not support User-Assigned
31+
> Managed Identities.
2132
22-
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. You can assign a User Assigned Identity at scale in your server fleet using Azure Policy, learn more [here][02].
33+
You can grant private access to a machine configuration package in an Azure Storage blob by
34+
assigning a [User-Assigned Identity][01] to a scope of Azure VMs. For this to work, you need to
35+
grant the managed identity read access to the Azure storage blob. This involves assigning the
36+
"Storage Blob Data Reader" role to the identity at the scope of the blob container. This setup
37+
ensures that your Azure VMs can securely read from the specified blob container using the
38+
user-assigned managed identity. To learn how you can assign a User Assigned Identity at scale, see
39+
[Use Azure Policy to assign managed identities][02].
2340

24-
### Using a SAS Token
25-
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.
41+
### Using a SAS Token
42+
43+
Optionally, you can add a shared access signature (SAS) token in the URL to ensure secure access to
44+
the package. The below example generates a blob SAS token with read access and returns the full
45+
blob URI with the shared access signature token. In this example, the token has a time limit of
46+
three years.
2647

2748
```powershell
2849
$startTime = Get-Date
@@ -31,23 +52,32 @@ $endTime = $startTime.AddYears(3)
3152
$tokenParams = @{
3253
StartTime = $startTime
3354
ExpiryTime = $endTime
34-
Container = 'machine-configuration'
35-
Blob = 'MyConfig.zip'
55+
Container = '<storage-account-container-name>'
56+
Blob = '<configuration-blob-name>'
3657
Permission = 'r'
37-
Context = $context
58+
Context = '<storage-account-context>'
3859
FullUri = $true
3960
}
61+
4062
$contentUri = New-AzStorageBlobSASToken @tokenParams
4163
```
4264

4365
## Summary
44-
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 and flags ensure that the package is retrieved using the managed identity and that Azure Arc machines are not included in the policy scope.
66+
67+
By using the resource ID of a user-assigned managed identity or SAS token, you can securely provide
68+
access to Machine Configuration packages stored in Azure storage. The additional parameters ensure
69+
that the package is retrieved using the managed identity and that Azure Arc machines aren't
70+
included in the policy scope.
4571

4672
## Next Steps
47-
- After creating the policy definition, you can assign it to the appropriate scope (e.g., management group, subscription, resource group) within your Azure environment.
48-
- 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.
73+
- After creating the policy definition, you can assign it to the appropriate scope, like management
74+
group, subscription, or resource group, within your Azure environment.
75+
- Remember to monitor the policy compliance status and make any necessary adjustments to your
76+
Machine Configuration package or policy assignment to meet your organizational requirements.
4977

50-
<!-- Reference link definitions -->
51-
[01]: https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/managed-identity-best-practice-recommendations#using-user-assigned-identities-to-reduce-administration
52-
[02]: https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/how-to-assign-managed-identity-via-azure-policy
78+
> [!div class="nextstepaction"]
79+
> [Sign a custom machine configuration package](./6-sign-package.md)
5380
81+
<!-- Reference link definitions -->
82+
[01]: /entra/identity/managed-identities-azure-resources/managed-identity-best-practice-recommendations#using-user-assigned-identities-to-reduce-administration
83+
[02]: /entra/identity/managed-identities-azure-resources/how-to-assign-managed-identity-via-azure-policy

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

Lines changed: 53 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,14 @@ ms.custom: linux-related-content
88

99
# How to sign machine configuration packages
1010

11-
Machine configuration custom policies use SHA256 hash to validate the policy package hasn't
11+
Machine configuration custom policies use a SHA256 hash to validate that the policy package hasn't
1212
changed. Optionally, customers may also use a certificate to sign packages and force the machine
1313
configuration extension to only allow signed content.
1414

15-
To enable this scenario, there are two steps you need to complete. Run the cmdlet to sign the
16-
content package, and append a tag to the machines that should require code to be signed.
15+
To enable this scenario, there are two steps you need to complete:
16+
17+
1. Run the cmdlet to sign the content package.
18+
1. Append a tag to the machines that should require code to be signed.
1719

1820
## Signature validation using a code signing certificate
1921

@@ -24,7 +26,7 @@ testing purposes to follow along with the example.
2426

2527
## Windows signature validation
2628

27-
```azurepowershell-interactive
29+
```powershell
2830
# How to create a self sign cert and use it to sign Machine Configuration
2931
# custom policy package
3032
@@ -34,26 +36,35 @@ $codeSigningParams = @{
3436
DnsName = 'GCEncryptionCertificate'
3537
HashAlgorithm = 'SHA256'
3638
}
37-
$mycert = New-SelfSignedCertificate @codeSigningParams
39+
$certificate = New-SelfSignedCertificate @codeSigningParams
3840
3941
# Export the certificates
40-
$mypwd = ConvertTo-SecureString -String "Password1234" -Force -AsPlainText
41-
$mycert | Export-PfxCertificate -FilePath C:\demo\GCPrivateKey.pfx -Password $mypwd
42-
$mycert | Export-Certificate -FilePath "C:\demo\GCPublicKey.cer" -Force
42+
$privateKey = @{
43+
Cert = $certificate
44+
Password = Read-Host "Enter password for private key" -AsSecureString
45+
FilePath = '<full-path-to-export-private-key-pfx-file>'
46+
}
47+
$publicKey = @{
48+
Cert = $certificate
49+
FilePath = '<full-path-to-export-public-key-cer-file>'
50+
Force = $true
51+
}
52+
Export-PfxCertificate @privateKey
53+
Export-Certificate @publicKey
4354
4455
# Import the certificate
4556
$importParams = @{
46-
FilePath = 'C:\demo\GCPrivateKey.pfx'
47-
Password = $mypwd
57+
FilePath = $privateKey.FilePath
58+
Password = $privateKey.Password
4859
CertStoreLocation = 'Cert:\LocalMachine\My'
4960
}
5061
Import-PfxCertificate @importParams
5162
5263
# Sign the policy package
53-
$certToSignThePackage = Get-ChildItem -Path cert:\LocalMachine\My |
54-
Where-Object { $_.Subject-eq "CN=GCEncryptionCertificate" }
64+
$certToSignThePackage = Get-ChildItem -Path Cert:\LocalMachine\My |
65+
Where-Object { $_.Subject -eq "CN=GCEncryptionCertificate" }
5566
$protectParams = @{
56-
Path = 'C:\demo\AuditWindowsService.zip'
67+
Path = '<path-to-package-to-sign>'
5768
Certificate = $certToSignThePackage
5869
Verbose = $true
5970
}
@@ -62,51 +73,64 @@ Protect-GuestConfigurationPackage @protectParams
6273

6374
## Linux signature validation
6475

65-
```azurepowershell-interactive
76+
```powershell
6677
# generate gpg key
6778
gpg --gen-key
6879
80+
$emailAddress = '<email-id-used-to-generate-gpg-key>'
81+
$publicGpgKeyPath = '<full-path-to-export-public-key-gpg-file>'
82+
$privateGpgKeyPath = '<full-path-to-export-private-key-gpg-file>'
83+
6984
# export public key
70-
gpg --output public.gpg --export <email-id-used-to-generate-gpg-key>
85+
gpg --output $publicGpgKeyPath --export $emailAddress
7186
7287
# export private key
73-
gpg --output private.gpg --export-secret-key <email-id-used-to-generate-gpg-key>
88+
gpg --output $privateGpgKeyPath --export-secret-key $emailAddress
7489
7590
# Sign linux policy package
7691
Import-Module GuestConfiguration
7792
$protectParams = @{
78-
Path = './not_installed_application_linux.zip'
79-
PrivateGpgKeyPath = './private.gpg'
80-
PublicGpgKeyPath = './public.gpg'
93+
Path = '<path-to-package-to-sign>'
94+
PrivateGpgKeyPath = $privateGpgKeyPath
95+
PublicGpgKeyPath = $publicGpgKeyPath
8196
Verbose = $true
8297
}
8398
Protect-GuestConfigurationPackage
8499
```
85100

86101
Parameters of the `Protect-GuestConfigurationPackage` cmdlet:
87102

88-
- **Path**: Full path of the machine configuration package.
103+
- **Path**: Full path to the machine configuration package.
89104
- **Certificate**: Code signing certificate to sign the package. This parameter is only supported
90105
when signing content for Windows.
106+
- **PrivateGpgKeyPath**: Full path to the private key `.gpg` file. This parameter is only supported
107+
when signing content for Linux.
108+
- **PublicGpgKeyPath**: Full path to the public key `.gpg` file. This parameter is only supported
109+
when signing content for Linux.
110+
91111

92112
## Certificate requirements
93113

94-
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`
95-
on Linux machines. For the node to verify signed content, install the certificate public key on the
96-
machine before applying the custom policy. This process can be done using any technique inside the
97-
VM or by using Azure Policy. An example template is available
98-
[to deploy a machine with a certificate][01]. The Key Vault access policy must allow the Compute
99-
resource provider to access certificates during deployments. For detailed steps, see
114+
The machine configuration agent expects the certificate public key to be present in "Trusted
115+
Publishers" on Windows machines and in the path `/usr/local/share/ca-certificates/gc` on Linux
116+
machines. For the node to verify signed content, install the certificate public key on the machine
117+
before applying the custom policy.
118+
119+
You can install the certificate public key using normal tools inside the VM or by using Azure
120+
Policy. An [example template using Azure Policy][01] shows how you can deploy a machine with a
121+
certificate. The Key Vault access policy must allow the Compute resource provider to access
122+
certificates during deployments. For detailed steps, see
100123
[Set up Key Vault for virtual machines in Azure Resource Manager][02].
101124

102125
Following is an example to export the public key from a signing certificate, to import to the
103126
machine.
104127

105128
```azurepowershell-interactive
106-
$Cert = Get-ChildItem -Path cert:\LocalMachine\My |
107-
Where-Object { $_.Subject-eq "CN=mycert3" } |
129+
$Cert = Get-ChildItem -Path Cert:\LocalMachine\My |
130+
Where-Object { $_.Subject-eq 'CN=<CN-of-your-signing-certificate>' } |
108131
Select-Object -First 1
109-
$Cert | Export-Certificate -FilePath "$env:temp\DscPublicKey.cer" -Force
132+
133+
$Cert | Export-Certificate -FilePath '<path-to-export-public-key-cer-file>' -Force
110134
```
111135

112136
## Tag requirements

‎redirects/.openpublishing.redirection.machine-configuration.json

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,10 +125,15 @@
125125
"source_path_from_root": "/articles/governance/policy/how-to/guest-configuration-create-publish.md",
126126
"redirect_document_id": false
127127
},
128+
{
129+
"redirect_url": "/azure/governance/machine-configuration/how-to/develop-custom-package/6-sign-package",
130+
"source_path_from_root": "/articles/governance/machine-configuration/how-to/develop-custom-package/5-sign-package.md",
131+
"redirect_document_id": true
132+
},
128133
{
129134
"redirect_url": "/azure/governance/machine-configuration/how-to/develop-custom-package/5-sign-package",
130135
"source_path_from_root": "/articles/governance/machine-configuration/how-to-sign-package.md",
131-
"redirect_document_id": true
136+
"redirect_document_id": false
132137
},
133138
{
134139
"redirect_url": "/azure/governance/machine-configuration/how-to/develop-custom-package/5-sign-package",

0 commit comments

Comments
 (0)