Skip to content

Commit e47be58

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #313065 from msftadam/patch-782805
Revise ARM template guidelines for secret management
2 parents a45b5a6 + 4d79376 commit e47be58

1 file changed

Lines changed: 109 additions & 23 deletions

File tree

‎articles/operator-service-manager/configuration-guide.md‎

Lines changed: 109 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,10 @@ We now recommend that you use at least three CGS/CGV sets, organizing parameters
4545
* Security-specific parameters
4646
* Examples include passwords and certificates.
4747
* Uses CGS/CGV with secrets.
48-
* Store values in Azure Key Vault to obscure during deployments.
48+
* Store values in Azure Key Vault (AKV) to obscure during deployments.
49+
50+
> [!NOTE]
51+
> * When using secrets, consider restricting access to the role based access control (RBAC) scope `Microsoft.Resources/deployments/exportTemplate/action`.
4952
5053
## CGS without secrets
5154

@@ -91,15 +94,15 @@ This example shows the rendered CGV resource created after the CGV deployment co
9194
}
9295
```
9396

94-
## CGS with secrets
95-
Other than separating secrets into a unique CGS, no special requirements exist for CGS secret support.
97+
## CGV with secrets without AKV
9698

97-
## CGV with secrets
98-
Consider the following Azure Resource Manager (ARM) template requirements to properly obscure secret values throughout the entire CGV resource lifecycle.
99+
Where AKV isn't being used, consider the following Azure Resource Manager (ARM) template requirements to properly obscure secret values throughout CGV resource lifecycle.
100+
101+
* To contain all secrets, define an object parameter with `"type": "secureObject"`.
102+
* Before a CGV is deployed, this configuration obscures the display of secrets as template parameters.
103+
104+
This example shows how to define an object parameter `secretCgvContent`.
99105

100-
* Use `configurationType: 'Secret'` in the template under resource properties.
101-
* Once a CGV is deployed, this configuration prevents displaying the secret data via most Azure methods.
102-
103106
```json
104107
"parameters": {
105108
"secretCgvContent": {
@@ -108,9 +111,14 @@ Consider the following Azure Resource Manager (ARM) template requirements to pro
108111
}
109112
```
110113

111-
* Use `"type": "secureObject"` in the template under parameter type
112-
* This configuration obscures the display of the secrets as template parameters.
113-
114+
> [!NOTE]
115+
> * Don't hydrate `secretCgvContent` using the bicep loadJsonContent() function as it forces the use of insecure variables.
116+
117+
* Under CGV resource properties, use `configurationType: 'Secret'` and `"secretConfigurationValue": "[string(parameters('secretCgvContent'))]"`.
118+
* Once a CGV is deployed, this configuration prevents displaying the secret data via most Azure user interfaces.
119+
120+
This example shows how to pass all secrets in the object `secretCgvContent` to the CGV resource.
121+
114122
```json
115123
{
116124
"type": "Microsoft.HybridNetwork/configurationGroupValues",
@@ -121,25 +129,103 @@ Consider the following Azure Resource Manager (ARM) template requirements to pro
121129
}
122130
```
123131

124-
* Use a template reference to Azure Key Vault (AKV) in place of the plain-text secret.
125-
* This configuration obscures the display of the secrets as template variables.
132+
## CGV with secrets with AKV
126133

127-
> [!NOTE]
128-
> * ARM templates only support Azure Key Vault for secret reference substitution.
134+
Where AKV is being used, consider the following Azure Resource Manager (ARM) template requirements to properly obscure secret values throughout CGV resource lifecycle.
135+
136+
* Define a string `parameter` for each secret and one object `variable` to collect all secret values.
137+
* The object variable contains only a reference to the parameter string and exposes no secrets.
129138

130-
This example shows how to include an AKV reference to a secret named `secretName` in an ARM template.
139+
This example shows how to define a parameter `secretPassword` contained within the object variable `secretVal.configurationValue`.
131140

132141
```json
133-
"password": {
142+
"parameters": {
143+
"secretPassword": {
144+
"type": "string"
145+
}
146+
}
147+
"variables": {
148+
"configurationValue": {
149+
"secretVal": {
150+
"elastic_passwd": "secretPassword"
151+
}
152+
}
153+
}
154+
```
155+
156+
* Use a template reference to AKV in place of the plain-text secret.
157+
* Before the CGV is deployed, this configuration obscures the display of the secrets as template variables.
158+
159+
This example shows how to hydrate the secret `secretPassword` using AKV secret and key.
160+
161+
```json
162+
"secretPassword": {
134163
"reference": {
135164
"keyVault": {
136165
"id": "/subscriptions/xxx/resourceGroups/yyy/providers/Microsoft.KeyVault/vaults/zz"
137166
},
138-
"secretName": "passwd"
167+
"secretPassword": "<akv-secret-key>"
168+
}
169+
}
170+
```
171+
172+
* Under CGV resource properties, use `configurationType: 'Secret'` and `"secretConfigurationValue": "string(secretVal.configurationValue)"`.
173+
* Once a CGV is deployed, this configuration prevents displaying the secret data via most Azure user interfaces.
174+
175+
This example shows how to pass all secrets in the object `secretVal.configurationValue` to the new CGV.
176+
177+
```json
178+
{
179+
"resources": [ {
180+
"type": "Microsoft.HybridNetwork/configurationGroupValues",
181+
"properties": {
182+
"configurationType": "Secret"
183+
"secretConfigurationValue": "string(secretVal.configurationValue)"
139184
}
185+
}
186+
]
187+
```
188+
189+
## networkFunction with secrets
190+
191+
Consider the following Azure Resource Manager (ARM) template requirements to properly obscure secret values throughout network function (NF) resource lifecycle.
192+
193+
* Use `"type": "secureObject"` in the template for the `secretValues` and `config` parameter
194+
* This configuration obscures the display of the secrets as template parameters.
195+
196+
```json
197+
"parameters": {
198+
"siteSpecificValues": {
199+
"type": "object"
200+
},
201+
"secretValues": {
202+
"type": "secureObject"
203+
},
204+
"nfValues": {
205+
"type": "object"
206+
},
207+
"config": {
208+
"type": "secureObject",
209+
"defaultValue": "[union(parameters('nfValues'),parameters('siteSpecificValues'), parameters('secretValues'))]"
210+
}
211+
}
140212
```
141213

142-
To further secure resources, consider restricting access to the role based access control (RBAC) scope `Microsoft.Resources/deployments/exportTemplate/action` to only roles that absolutely need to this access.
214+
> [!NOTE]
215+
> * Don't hydrate `secretCgvContent` using the bicep loadJsonContent() function as it forces the use of insecure variables.
216+
217+
* Under networkFunctions resource properties, use `configurationType: 'Secret'` and `"secretDeploymentValues": "[string(parameters('config'))]"`.
218+
* Once a network function is deployed, this configuration prevents displaying the secret data via most Azure user interfaces.
219+
220+
```json
221+
"resources": [
222+
{
223+
"type": "Microsoft.HybridNetwork/networkFunctions",
224+
"configurationType": "Secret",
225+
"secretDeploymentValues": "[string(variables('config'))]",
226+
}
227+
]
228+
```
143229

144230
## Overview of JSON Schema
145231

@@ -159,7 +245,7 @@ For the CGS meta-schema, Azure Operator Service Manager implements support for J
159245
* For string types, keyword support isn't limited or filtered. See [string](https://json-schema.org/understanding-json-schema/reference/string) in the JSON Schema reference.
160246
* For numeric types, keyword support isn't limited or filtered. See [Numeric types](https://json-schema.org/understanding-json-schema/reference/numeric) in the JSON Schema reference.
161247

162-
## Optional and required fields
248+
### Optional and required fields
163249

164250
You declare a property as optional by including a `required` keyword, which omits the optional property. If you don't specify the `required` keyword, all properties are considered required. You need at least one required property type to support an optional property type.
165251

@@ -180,11 +266,11 @@ You declare a property as optional by including a `required` keyword, which omit
180266
}
181267
```
182268

183-
## Default values in JSON Schema
269+
### Default values in JSON Schema
184270

185271
For optional properties, Azure Operator Service Manager implements a custom method of handling default values. When a default value is defined in CGS meta-schema, Azure Operator Service Manager uses that value where the property is missing or undefined in the input CGV data. Azure Operator Service Manager validator logic essentially hydrates the CGV value with the default value when the operator doesn't provide a value.
186272

187-
### How to define defaults
273+
#### How to define defaults
188274

189275
Defaults must be specified either inside properties or inside items of an array. The following example demonstrates defaults with integer and string property types:
190276

@@ -204,7 +290,7 @@ Defaults must be specified either inside properties or inside items of an array.
204290
}
205291
```
206292

207-
### Rules for defining defaults
293+
#### Rules for defining defaults
208294

209295
The following rules are applied when you're validating a default value. Consider these rules when you're using default values to ensure expected outcomes.
210296

0 commit comments

Comments
 (0)