You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Use Azure Key Vault to pass a secret from a key vault as a parameter during Bicep deployment
9
+
# Use Azure Key Vault to pass a secret as a parameter during Bicep deployment
10
10
11
-
Instead of entering a secure value like a password directly into your Bicep file or parameters file, you can retrieve the value from an [Azure Key Vault](/azure/key-vault/general/overview) during a deployment. When a [module](./modules.md) expects a `string` parameter with a `secure:true` modifier, you can use the [`getSecret` function](bicep-functions-resource.md#getsecret) to obtain a key vault secret. The value is never exposed because you only reference its key vault ID.
11
+
This article explains how to use Azure Key Vault to pass a secret as a parameter during Bicep deployment. Instead of entering a secure value like a password directly into your Bicep file or parameters file, you can retrieve the value from [Azure Key Vault](/azure/key-vault/general/overview) during a deployment.
12
+
13
+
When a [module](./modules.md) expects a string parameter with a `secure:true` modifier applied, you can use the [`getSecret` function](bicep-functions-resource.md#getsecret) to obtain a key vault secret. You don't expose the value because you reference only its key vault ID.
12
14
13
15
> [!IMPORTANT]
14
16
> This article focuses on how to pass a sensitive value as a template parameter. When the secret is passed as a parameter, the key vault can exist in a different subscription than the resource group to which you're deploying.
15
-
>
16
-
> This article doesn't cover how to set a virtual-machine property to a certificate's URL in a key vault. For a quickstart template of that scenario, see [WinRM on a Windows VM](https://github.com/Azure/azure-quickstart-templates/tree/master/demos/vm-winrm-keyvault-windows).
17
+
18
+
This article doesn't cover how to set a virtualmachine (VM) property to a certificate's URL in a key vault. For a quickstart template of that scenario, see [WinRM on a Windows VM](https://github.com/Azure/azure-quickstart-templates/tree/master/demos/vm-winrm-keyvault-windows).
17
19
18
20
## Deploy key vaults and secrets
19
21
20
22
To access a key vault during Bicep deployment, set `enabledForTemplateDeployment` on the key vault to `true`.
21
23
22
24
If you already have a key vault, make sure it permits template deployments.
23
25
24
-
# [Azure CLI](#tab/azure-cli)
26
+
###[Azure CLI](#tab/azure-cli)
25
27
26
28
```azurecli-interactive
27
29
az keyvault update --name ExampleVault --enabled-for-template-deployment true
As the owner of the key vault, you automatically have access to create secrets. If the user working with secrets isn't the owner of the key vault, grant access with:
69
+
The owner of the key vaultautomatically has access to create secrets. If the user who is working with secrets isn't the owner of the key vault, you can grant access with:
68
70
69
-
# [Azure CLI](#tab/azure-cli)
71
+
###[Azure CLI](#tab/azure-cli)
70
72
71
73
```azurecli-interactive
72
74
az keyvault set-policy \
@@ -75,7 +77,7 @@ az keyvault set-policy \
75
77
--secret-permissions set delete get list
76
78
```
77
79
78
-
# [Azure PowerShell](#tab/azure-powershell)
80
+
###[Azure PowerShell](#tab/azure-powershell)
79
81
80
82
```azurepowershell-interactive
81
83
$userPrincipalName = "<Email Address of the deployment operator>"
@@ -90,8 +92,8 @@ Set-AzKeyVaultAccessPolicy `
90
92
91
93
For more information about creating key vaults and adding secrets, see:
92
94
93
-
-[Set and retrieve a secret by using CLI](/azure/key-vault/secrets/quick-create-cli)
94
-
-[Set and retrieve a secret by using PowerShell](/azure/key-vault/secrets/quick-create-powershell)
95
+
-[Set and retrieve a secret by using the Azure CLI](/azure/key-vault/secrets/quick-create-cli)
96
+
-[Set and retrieve a secret by using Azure PowerShell](/azure/key-vault/secrets/quick-create-powershell)
95
97
-[Set and retrieve a secret by using the Azure portal](/azure/key-vault/secrets/quick-create-portal)
96
98
-[Set and retrieve a secret by using .NET](/azure/key-vault/secrets/quick-create-net)
97
99
-[Set and retrieve a secret by using Node.js](/azure/key-vault/secrets/quick-create-node)
@@ -100,7 +102,7 @@ For more information about creating key vaults and adding secrets, see:
100
102
101
103
The user who deploys the Bicep file must have the `Microsoft.KeyVault/vaults/deploy/action` permission for the scope of the resource group and key vault. The [Owner](../../role-based-access-control/built-in-roles.md#owner) and [Contributor](../../role-based-access-control/built-in-roles.md#contributor) roles both grant this access. If you created the key vault, you're the owner and have the permission.
102
104
103
-
The following procedure shows how to create a role with the minimum permission and how to assign the user.
105
+
The following procedure shows how to create a role with the minimum permission and how to assign the user:
104
106
105
107
1. Create a custom JSON file with a role definition:
106
108
@@ -123,9 +125,9 @@ The following procedure shows how to create a role with the minimum permission a
123
125
124
126
Replace "00000000-0000-0000-0000-000000000000" with the subscription ID.
125
127
126
-
2. USe the JSON file to create the new role:
128
+
2. Use the JSON file to create the new role:
127
129
128
-
# [Azure CLI](#tab/azure-cli)
130
+
### [Azure CLI](#tab/azure-cli)
129
131
130
132
```azurecli-interactive
131
133
az role definition create --role-definition "<path-to-role-file>"
@@ -135,7 +137,7 @@ The following procedure shows how to create a role with the minimum permission a
@@ -147,17 +149,17 @@ The following procedure shows how to create a role with the minimum permission a
147
149
148
150
---
149
151
150
-
The samples assign the custom role to the user on the resource-group level.
152
+
The preceding examples assign the custom role to the user on the resource-group level.
151
153
152
-
When using a key vault with the Bicep file for a [Managed Application](../managed-applications/overview.md), you must grant access to the **Appliance Resource Provider** service principal. For more information, see [Access Key Vault secret when deploying Azure Managed Applications](../managed-applications/key-vault-access.md).
154
+
If you use a key vault with a Bicep file for a [managed application](../managed-applications/overview.md), you must grant access to the **Appliance Resource Provider** service principal. For more information, see [Access a Key Vault secret when deploying Azure managed applications](../managed-applications/key-vault-access.md).
153
155
154
-
## Retrieve secrets in Bicep file
156
+
## Retrieve secrets in a Bicep file
155
157
156
-
You can use the [`getSecret` function](./bicep-functions-resource.md#getsecret) in Bicep files to obtain a key vault secret. Note that the `getSecret` function is exclusively applicable to a `Microsoft.KeyVault/vaults` resource. Additionally, it's restricted to usage within the `params` section of a module and can only be used with parameters with the `@secure()` decorator.
158
+
You can use the [`getSecret` function](./bicep-functions-resource.md#getsecret) in a Bicep file to obtain a key vault secret. The `getSecret` function can be used only with a `Microsoft.KeyVault/vaults` resource. Additionally, it can be used only within the `params` section of a module and only with parameters that have the `@secure()` decorator.
157
159
158
-
Another function called `az.getSecret()` function can be used in Bicep parameters files to retrieve key vault secrets. For more information, see [Retrieve secrets in parameters file](#retrieve-secrets-in-parameters-file).
160
+
You can use another function called `az.getSecret()` in a Bicep parameters file to retrieve key vault secrets. For more information, see [Retrieve secrets in a parameters file](#retrieve-secrets-in-a-parameters-file).
159
161
160
-
Since the `getSecret` function can only be used in the `params` section of a module, create a _sql.bicep_ file in the same directory as the _main.bicep_ file with the following content:
162
+
Since the `getSecret` function can be used only in the `params` section of a module, create a _sql.bicep_ file in the same directory as the _main.bicep_ file with the following content:
The `adminPassword` parameter has a `@secure()` decorator in the preceding file.
182
184
183
-
The following Bicep file consumes _sql.bicep_ as a module. The Bicep file references an existing key vault, calls the `getSecret` function to retrieve the key vault secret, and then passes the value as a parameter to the module:
185
+
The following Bicep file consumes _sql.bicep_ as a module. The Bicep file references an existing key vault, calls the `getSecret` function to retrieve the key vault secret, and then passes the value as a parameter to the module:
184
186
185
187
```bicep
186
188
param sqlServerName string
@@ -205,9 +207,9 @@ module sql './sql.bicep' = {
205
207
}
206
208
```
207
209
208
-
## Retrieve secrets in parameters file
210
+
## Retrieve secrets in a parameters file
209
211
210
-
If you don't want to use a module, you can retrieve key vault secrets in a parameters file. However, the approach varies depending on whether you're using a JSON or Bicep parameters file.
212
+
If you don't want to use a module, you can retrieve key vault secrets in a parameters file. However, the approach varies depending on whether you use a JSON or Bicep parameters file.
211
213
212
214
The following Bicep file deploys a SQL server that includes an administrator password. While the password parameter is set to a secure string, Bicep doesn't specify the origin of that value:
213
215
@@ -234,7 +236,7 @@ Next, create a parameters file for the preceding Bicep file.
234
236
235
237
### Bicep parameters file
236
238
237
-
The [`az.getSecret`](./bicep-functions-parameters-file.md#getsecret) function can be used in a `.bicepparam` file to retrieve the value of a secret from a key vault:
239
+
The [`az.getSecret` function](./bicep-functions-parameters-file.md#getsecret) can be used in a `.bicepparam` file to retrieve the value of a secret from a key vault:
In a JSON parameters file, specify a parameter that matches the name of the parameter in the Bicep file. For the parameter value, reference the secret from the key vault; you do this by passing the resource identifier of the key vault and the name of the secret. In the following parameters file, the key vault secret must already exist, and you provide a static value for its resource ID:
251
+
In a JSON parameters file, specify a parameter that matches the name of the parameter in the Bicep file. For the parameter value, reference the secret from the key vault. Pass the resource identifier of the key vault and the name of the secret. In the following parameters file, the key vault secret must already exist. You provide a static value for its resource ID.
250
252
251
253
```json
252
254
{
@@ -278,8 +280,8 @@ If you need to use a version of the secret other than the current one, include a
- For general information about key vaults, see [About Azure Key Vault](/azure/key-vault/general/overview)
284
-
- For complete GitHub examples of how to reference key vault secrets, see [keyvaultexamples](https://github.com/rjmax/ArmExamples/tree/master/keyvaultexamples).
285
+
- For general information about key vaults, see [About Azure Key Vault](/azure/key-vault/general/overview).
286
+
- For complete GitHub examples that demonstrate how to reference key vault secrets, see [Key vault examples](https://github.com/rjmax/ArmExamples/tree/master/keyvaultexamples).
285
287
- For a Learn module that covers how to use a key vault to pass a secure value, see [Manage complex cloud deployments by using advanced JSON ARM template features](/training/modules/manage-deployments-advanced-arm-template-features/).
0 commit comments