Merge pull request #299588 from mumian/0507-secure-output

Document the secure outputs decorator

Author: prmerger-automator[bot]

articles/azure-resource-manager/bicep/data-types.md

@@ -2,7 +2,7 @@
 title: Data types in Bicep
 description: This article describes the data types that are available in Bicep.
 ms.topic: reference
-ms.date: 01/10/2025
+ms.date: 05/09/2025
 ms.custom: devx-track-bicep
 ---
 
@@ -423,7 +423,7 @@ You can use the union type syntax in [user-defined data types](./user-defined-da
 
 Secure strings use the same format as string, and secure objects use the same format as object. With Bicep, you add the `@secure()` [decorator](./parameters.md#use-decorators) to a string or object.
 
-When you set a parameter to a secure string or secure object, the value of the parameter isn't saved to the deployment history or logged. If you set that secure value to a property that isn't expecting a secure value, the value isn't protected. For example, if you set a secure string to a tag, that value is stored as plain text. Use secure strings for passwords and secrets.
+When you set a parameter (or an output) to a secure string or secure object, the value of the parameter (or the output) isn't saved to the deployment history or logged. If you set that secure value to a property that isn't expecting a secure value, the value isn't protected. For example, if you set a secure string to a tag, that value is stored as plain text. Use secure strings for passwords and secrets.
 
 The following example shows two secure parameters:
 
@@ -435,6 +435,8 @@ param password string
 param configValues object
 ```
 
+For more information, see [Secure parameters](./parameters.md#secure-parameters) and [Secure outputs](./outputs.md#secure-outputs).
+
 ## Data type assignability
 
 In Bicep, you can assign a value of one type (source type) to another type (target type). The following table shows which source type (listed horizontally) you can or can't assign to which target type (listed vertically). In the table, _X_ means assignable, an empty space means not assignable, and _?_ means only if the types are compatible.

articles/azure-resource-manager/bicep/modules.md

@@ -3,7 +3,7 @@ title: Bicep modules
 description: This article describes how to define a module in a Bicep file and how to use module scopes.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 03/25/2025
+ms.date: 05/09/2025
 ---
 
 # Bicep modules
@@ -545,6 +545,8 @@ module stgModule '../create-storage-account/main.bicep' = {
 output storageEndpoint object = stgModule.outputs.storageEndpoint
 ```
 
+With Bicep version 0.35.1 and later, the `@secure()` decorator can be applied to module outputs to mark them as sensitive, ensuring that their values are not exposed in logs or deployment history. This is useful when a module needs to return sensitive data, such as a generated key or connection string, to the parent Bicep file without risking exposure. For more information, see [Secure outputs](./outputs.md#secure-outputs).
+
 ## Related content
 
 - For a tutorial, see [Build your first Bicep template](/training/modules/deploy-azure-resources-by-using-bicep-templates/).

articles/azure-resource-manager/bicep/outputs.md

@@ -3,7 +3,7 @@ title: Outputs in Bicep
 description: Learn how to define output values in Bicep.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 03/25/2025
+ms.date: 05/09/2025
 ---
 
 # Outputs in Bicep
@@ -68,6 +68,7 @@ Decorators are written in the format `@expression` and are placed above output d
 | [minLength](#length-constraints) | array, string | int | This provides the minimum length for string and array outputs, and the value is inclusive. |
 | [minValue](#integer-constraints) | int | int | This provides the minimum value for the integer output, and the value is inclusive. |
 | [sealed](#sealed) | object | none | Elevate [BCP089](./diagnostics/bcp089.md) from a warning to an error when a property name of a use-define data type is likely a typo. For more information, see [Elevate error level](./user-defined-data-types.md#elevate-error-level). |
+| [secure](#secure-outputs) | string, object | none | Marks the output as secure. The value for a secure output isn't saved to the deployment history and isn't logged. For more information, see [Secure strings and objects](data-types.md#secure-strings-and-objects). |
 
 Decorators are in the [`sys` namespace](bicep-functions.md#namespaces-for-functions). If you need to differentiate a decorator from another item with the same name, preface the decorator with `sys`. For example, if your Bicep file includes a parameter named `description`, you must add the `sys` namespace when using the **description** decorator.
 
@@ -150,6 +151,20 @@ When you provide a `@metadata()` decorator with a property that conflicts with a
 
 See [Elevate error level](./user-defined-data-types.md#elevate-error-level).
 
+### Secure outputs
+
+With Bicep version 0.35.1 and later, you can mark string or object outputs as secure. When an output is decorated with `@secure()`, Azure Resource Manager treats the output value as sensitive, preventing it from being logged or displayed in deployment history, Azure portal, or command-line outputs.
+
+```bicep
+@secure()
+output demoPassword string
+
+@secure()
+output demoSecretObject object
+```
+
+The `@secure()` decorator is valid only for outputs of type string or object, as these align with the [secureString](../templates/syntax.md#outputs) and [secureObject](../templates/syntax.md#outputs) types in ARM templates. To pass arrays or numbers securely, wrap them in a secureObject or serialize them as a secureString.
+
 ## Conditional output
 
 When the value to return depends on a condition in the deployment, use the `?` operator.

articles/azure-resource-manager/bicep/parameters.md

@@ -3,7 +3,7 @@ title: Parameters in Bicep files
 description: Learn how to define and use parameters in a Bicep file.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 03/25/2025
+ms.date: 05/09/2025
 ---
 
 # Parameters in Bicep
@@ -207,7 +207,7 @@ See [Elevate error level](./user-defined-data-types.md#elevate-error-level).
 
 ### Secure parameters
 
-You can mark string or object parameters as secure. The value of a secure parameter isn't saved to the deployment history and isn't logged.
+You can mark string or object parameters as secure. When a parameter is decorated with `@secure()`, Azure Resource Manager treats the parameter value as sensitive, preventing it from being logged or displayed in deployment history, Azure Portal, or command-line outputs.
 
 ```bicep
 @secure()
@@ -232,6 +232,8 @@ resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
 }
 ```
 
+The `@secure()` decorator is valid only for parameters of type string or object, as these align with the [secureString](../templates/syntax.md#parameters) and [secureObject](../templates/syntax.md#parameters) types in ARM templates. To pass arrays or numbers securely, wrap them in a secureObject or serialize them as a secureString.
+
 ## Use objects as parameters
 
 It can be easier to organize related values by passing them in as an object. This approach also reduces the number of parameters in the template.