Key vault secret reference for secure string module param

docs/spec/modules.md

@@ -71,4 +71,47 @@ module publicIp './publicIpAddress.bicep' = {
 }
 ```
 
-Please see [Resource Scopes](./resource-scopes.md) for more information and advanced usage.
+Please see [Resource Scopes](./resource-scopes.md) for more information and advanced usage.
+
+## Using existing Key Vault's secret as input for secure string module parameter
+
+When a module expects a `string` parameter with `secure: true` modifier, you can use existing secret from a Key Vault. To obtain the secret you need to use special method `getSecret` that can be called on a Microsoft.KeyVault/vaults resource only and can be used only with parameter with `@secure()` decorator. For example:
+
+```bicep
+// Module accepting secure string
+@secure()
+param myPassword string
+@secure()
+param mySecondPassword string
+```
+
+```bicep
+param keyVaultName string
+param keyVaultSubscription string
+param keyVaultResourceGroup string
+param secret1Name string
+param secret1Version  string
+param secret2Name string
+
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: keyVaultName
+  scope: resourceGroup(keyVaultSubscription, keyVaultResourceGroup)
+}
+
+module secretModule './secretModule.bicep' = {
+  name: 'secretModule'  
+  params: {
+    myPassword: kv.getSecret(secret1Name, secret1Version)
+    mySecondPassword: kv.getSecret(secret2Name)
+  }
+}
+```
+
+### Notes
+* Key Vault must have `enabledForDeployment` property set to `true`
+* Key Vault and secret must exist before entire deployment starts.
+* Secret version is optional. It defaults to latest version if omitted.
+
+### Additional links
+ * https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/key-vault-parameter
+ * https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-tutorial-use-key-vault

src/Bicep.Core.IntegrationTests/ScenarioTests.cs

@@ -663,7 +663,7 @@ param groupReaderId string
                 ("BCP139", DiagnosticLevel.Error, "The root resource scope must match that of the Bicep file. To deploy a resource to a different root scope, use a module."),
             });
         }
-        
+
         [TestMethod]
         // https://github.com/azure/bicep/issues/1364
         public void Test_Issue1364()
@@ -685,7 +685,7 @@ public void Test_Issue569_success()
             var result = CompilationHelper.Compile(@"
 param myparam string
 var myvar = 'hello'
-        
+
 output myparam string = myparam
 output myvar string = myvar
 ");
@@ -791,8 +791,8 @@ param tags object
     name: 'CosmosDb-PrimaryKey'
     value: global_resources.outputs.cosmosDbKey
   }
-] 
- 
+]
+
 module stamp_0_secrets './kevault-secrets.bicep' = [for secret in secrets: {
   name: 'stamp_0_secrets-${deploymentId}'
   scope: resourceGroup(rg_stamps[0].name)

src/Bicep.Core.IntegrationTests/Scenarios/ParamKeyVaultSecretReferenceTests.cs

@@ -0,0 +1,304 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+using Bicep.Core.UnitTests.Assertions;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using FluentAssertions;
+using Bicep.Core.UnitTests.Utils;
+using FluentAssertions.Execution;
+using Bicep.Core.Diagnostics;
+using System.Linq;
+
+namespace Bicep.Core.IntegrationTests.Scenarios
+{
+    [TestClass]
+    public class ParamKeyVaultSecretReferenceTests
+    {
+
+        [TestMethod]
+        public void ValidKeyVaultSecretReference()
+        {
+            var (template, diags, _) = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+
+
+module secret 'secret.bicep' = {
+  name: 'secret'
+  params: {
+    mySecret: kv.getSecret('mySecret')
+  }
+}
+"),
+                ("secret.bicep", @"
+@secure()
+param mySecret string
+
+output exposed string = mySecret
+"));
+
+            diags.Should().BeEmpty();
+            template!.Should().NotBeNull();
+            var parameterToken = template!.SelectToken("$.resources[?(@.name == 'secret')].properties.parameters.mySecret")!;
+            using (new AssertionScope())
+            {
+                parameterToken.SelectToken("$.value")!.Should().BeNull();
+                parameterToken.SelectToken("$.reference.keyVault.id")!.Should().DeepEqual("[resourceId('Microsoft.KeyVault/vaults', 'testkeyvault')]");
+                parameterToken.SelectToken("$.reference.secretName")!.Should().DeepEqual("mySecret");
+                parameterToken.SelectToken("$.reference.secretVersion")!.Should().BeNull();
+            }
+        }
+
+        [TestMethod]
+        public void ValidKeyVaultSecretReferenceWithSecretVersion()
+        {
+            var (template, diags, _) = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+
+module secret 'secret.bicep' = {
+  name: 'secret'
+  params: {
+    mySecret: kv.getSecret('mySecret','secretversionguid')
+  }
+}
+"),
+                ("secret.bicep", @"
+@secure()
+param mySecret string = 'defaultSecret'
+
+output exposed string = mySecret
+"));
+
+            diags.Should().BeEmpty();
+            template!.Should().NotBeNull();
+            var parameterToken = template!.SelectToken("$.resources[?(@.name == 'secret')].properties.parameters.mySecret")!;
+            using (new AssertionScope())
+            {
+                parameterToken.SelectToken("$.value")!.Should().BeNull();
+                parameterToken.SelectToken("$.reference.keyVault.id")!.Should().DeepEqual("[resourceId('Microsoft.KeyVault/vaults', 'testkeyvault')]");
+                parameterToken.SelectToken("$.reference.secretName")!.Should().DeepEqual("mySecret");
+                parameterToken.SelectToken("$.reference.secretVersion")!.Should().DeepEqual("secretversionguid");
+            }
+        }
+
+        [TestMethod]
+        public void InvalidKeyVaultSecretReferenceUsageInOutput()
+        {
+            var result = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+
+output exposed string = kv.getSecret('mySecret','secretversionguid')
+"));
+
+            result.Should().NotGenerateATemplate();
+            result.Should().OnlyContainDiagnostic("BCP180", DiagnosticLevel.Error, "Function \"getSecret\" is not valid at this location. It can only be used when directly assigning to a module parameter with a secure decorator.");
+        }
+
+        [TestMethod]
+        public void InvalidKeyVaultSecretReferenceUsageInVariable()
+        {
+            var result = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+
+var secret = kv.getSecret('mySecret','secretversionguid')
+"));
+
+            result.Should().NotGenerateATemplate();
+            result.Should().OnlyContainDiagnostic("BCP180", DiagnosticLevel.Error, "Function \"getSecret\" is not valid at this location. It can only be used when directly assigning to a module parameter with a secure decorator.");
+        }
+
+
+        [TestMethod]
+        public void InvalidKeyVaultSecretReferenceUsageInNonSecretParam()
+        {
+            var result = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+
+module secret 'secret.bicep' = {
+  name: 'secret'
+  params: {
+    notSecret: kv.getSecret('mySecret','secretversionguid')
+  }
+}
+"),
+                ("secret.bicep", @"
+param notSecret string
+"));
+
+            result.Should().NotGenerateATemplate();
+            result.Should().OnlyContainDiagnostic("BCP180", DiagnosticLevel.Error, "Function \"getSecret\" is not valid at this location. It can only be used when directly assigning to a module parameter with a secure decorator.");
+        }
+
+        [TestMethod]
+        public void InvalidKeyVaultSecretReferenceUsageInSecureParamInterpolation()
+        {
+            var result = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+
+module secret 'secret.bicep' = {
+  name: 'secret'
+  params: {
+    testParam: '${kv.getSecret('mySecret','secretversionguid')}'
+  }
+}
+"),
+                ("secret.bicep", @"
+@secure()
+param testParam string
+"));
+
+            result.Should().NotGenerateATemplate();
+            result.Should().OnlyContainDiagnostic("BCP180", DiagnosticLevel.Error, "Function \"getSecret\" is not valid at this location. It can only be used when directly assigning to a module parameter with a secure decorator.");
+        }
+
+        [TestMethod]
+        public void InvalidKeyVaultSecretReferenceUsageInObjectParam()
+        {
+            var result = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+
+module secret 'secret.bicep' = {
+  name: 'secret'
+  params: {
+    testParam: kv.getSecret('mySecret','secretversionguid')
+  }
+}
+"),
+                ("secret.bicep", @"
+param testParam object
+"));
+
+
+            result.Should().NotGenerateATemplate();
+            result.Should().OnlyContainDiagnostic("BCP180", DiagnosticLevel.Error, "Function \"getSecret\" is not valid at this location. It can only be used when directly assigning to a module parameter with a secure decorator.");
+        }
+
+        [TestMethod]
+        public void InvalidKeyVaultSecretReferenceUsageInArrayParam()
+        {
+            var result = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+
+module secret 'secret.bicep' = {
+  name: 'secret'
+  params: {
+    testParam: [
+      kv.getSecret('mySecret','secretversionguid')
+    ]
+  }
+}
+"),
+                ("secret.bicep", @"
+param testParam array
+"));
+
+            result.Should().NotGenerateATemplate();
+            result.Should().OnlyContainDiagnostic("BCP180", DiagnosticLevel.Error, "Function \"getSecret\" is not valid at this location. It can only be used when directly assigning to a module parameter with a secure decorator.");
+        }
+
+
+        [TestMethod]
+        public void ValidKeyVaultSecretReferenceInLoopedModule()
+        {
+            var (template, diags, _) = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+var secrets = [
+{
+  name: 'secret01'
+  version: 'versionA'
+}
+{
+  name: 'secret02'
+  version: 'versionB'
+}
+]
+module secret 'secret.bicep' = [for (secret, i) in secrets : {
+  name: 'secret'
+  scope: resourceGroup('secret-${i}-rg')
+  params: {
+    mySecret: kv.getSecret('super-${secret.name}', secret.version)
+  }
+}]
+"),
+                ("secret.bicep", @"
+@secure()
+param mySecret string = 'defaultSecret'
+
+output exposed string = mySecret
+"));
+
+            diags.Should().BeEmpty();
+            template!.Should().NotBeNull();
+            var parameterToken = template!.SelectToken("$.resources[?(@.name == 'secret')].properties.parameters.mySecret")!;
+            using (new AssertionScope())
+            {
+                parameterToken.SelectToken("$.value")!.Should().BeNull();
+                parameterToken.SelectToken("$.reference.keyVault.id")!.Should().DeepEqual("[resourceId('Microsoft.KeyVault/vaults', 'testkeyvault')]");
+                parameterToken.SelectToken("$.reference.secretName")!.Should().DeepEqual("[format('super-{0}', variables('secrets')[copyIndex()].name)]");
+                parameterToken.SelectToken("$.reference.secretVersion")!.Should().DeepEqual("[variables('secrets')[copyIndex()].version]");
+            }
+        }
+
+        [TestMethod]
+        public void InvalidKeyVaultSecretReferenceInLoopedModule()
+        {
+            var result = CompilationHelper.Compile(
+                ("main.bicep", @"
+resource kv 'Microsoft.KeyVault/vaults@2019-09-01' existing = {
+  name: 'testkeyvault'
+}
+var secrets = [
+{
+  name: 'secret01'
+  version: 'versionA'
+}
+{
+  name: 'secret02'
+  version: 'versionB'
+}
+]
+module secret 'secret.bicep' = [for (secret, i) in secrets : {
+  name: 'secret-{i}'
+  params: {
+    mySecret: '${kv.getSecret(secret.name, secret.version)}'
+  }
+}]
+"),
+                ("secret.bicep", @"
+@secure()
+param mySecret string = 'defaultSecret'
+
+output exposed string = mySecret
+"));
+
+            result.Should().NotGenerateATemplate();
+            result.Should().OnlyContainDiagnostic("BCP180", DiagnosticLevel.Error, "Function \"getSecret\" is not valid at this location. It can only be used when directly assigning to a module parameter with a secure decorator.");
+        }
+    }
+}
+