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
This article provides best practices on protecting secrets in Azure Pipelines. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, or cryptographic keys.
13
-
14
-
Azure Pipelines doesn't generate secret values. However, you might need to add a secret to a pipeline to store sensitive data like an API key. To learn more about setting secret variables, see [Set secret variables](../process/set-secret-variables.md).
12
+
This article provides best practices on protecting secrets in Azure Pipelines. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, or cryptographic keys. Azure Pipelines doesn't generate secret values, but you might need to add a secret to a pipeline to store sensitive data like an API key.
## Don't use secrets if another method is available
19
-
20
-
The best method to protect a secret isn't to have a secret in the first place. Check to see if your pipeline can use a different method than using a secret to perform a task.
16
+
## Use another method
21
17
22
-
***Use service connections:**
23
-
- When you're targeting Azure or other services, use service connections instead of managing secrets in variables.
24
-
- Service connections allow you to securely connect to external services without exposing sensitive information directly in your pipeline configuration.
25
-
- For more information, see [Manage service connections](../library/service-endpoints.md) and [Connect to Microsoft Azure with an Azure Resource Manager service connection](../library/connect-to-azure.md).
18
+
Secrets present inherent security risks, so it's best not to use them at all. Instead of managing secrets in variables or exposing them in your pipeline configuration, see if your pipeline can use one of these other methods to do a task.
26
19
27
-
-**Use managed identities:**
28
-
- Consider using managed identities instead of handling secrets directly.
29
-
- Managed identities allow your applications and services to authenticate with Azure services without requiring explicit credentials.
30
-
- You can [use managed identities to access other Azure services](/entra/identity/managed-identities-azure-resources/managed-identities-status).
20
+
- Set up [service connections](../library/service-endpoints.md) to securely connect to Azure or other services like GitHub or Docker. For more information, see [Connect to Azure with an Azure Resource Manager service connection](../library/connect-to-azure.md).
21
+
- Use [managed identities](/entra/identity/managed-identities-azure-resources/managed-identities-status) to let your applications and services authenticate with Azure services without using explicit credentials.
22
+
- Use the [Azure CLI task](/azure/devops/pipelines/tasks/reference/azure-cli-v2) with the `addSpnToEnvironment` option to let your pipeline access service principal details without explicitly passing secrets.
31
23
32
-
-**Azure CLI task:**
33
-
- If you're using the [Azure CLI task](/azure/devops/pipelines/tasks/reference/azure-cli-v2), in your pipeline, consider using the `addSpnToEnvironment` setting to access service principal details in script without explicitly passing secrets.
34
-
35
-
For more information, see [Use service principals & managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md)
24
+
For more information, see [Use service principals and managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md).
36
25
37
26
## Use secret variables
38
27
39
-
Never store sensitive values as plaintext in an Azure Pipelines **.yml** file.
40
-
41
-
Secret variables can be used for private information like passwords, IDs, and other identifying data that you wouldn't want exposed in a pipeline. We recommend that you [set secret variables](../process/set-secret-variables.md) with Azure Key Vault. You can also set secret variables in the UI or in a variable group. We don't recommend using a logging command to set a secret variable. When you set a secret with a logging command, anyone who can access your pipeline can also see the secret.
28
+
Never store sensitive values as plain text in an *azure-pipelines.yml* file. You can [use secret variables](../process/set-secret-variables.md) for private information like passwords, IDs, and other identifying data you don't want exposed. Secret variables are encrypted, so you can use them in pipelines without exposing their values.
42
29
43
-
Secret variables are encrypted and can be used in pipelines without exposing their values. Although their values aren't exposed, never echo secrets as output and don't pass secrets on the command line. Instead, we suggest that you map your secrets into environment variables.
30
+
- It's best to securely manage secret variables in [Azure Key Vault](/azure/key-vault/general/overview). You can also set secret variables in the pipeline definition UI or in a variable group.
31
+
- Don't use a logging command to set a secret variable, because anyone who can access your pipeline can also see the secret.
32
+
- Never echo secrets as output, and don't pass secrets on the command line. Instead, it's best to map your secrets into environment variables.
33
+
- When you create a secret, follow [variable naming guidelines](../process/variables.md#variable-naming-restrictions), and make sure your secret name doesn't disclose sensitive information.
44
34
45
-
When you create a secret, follow [variable naming guidelines](../process/variables.md#variable-naming-restrictions) and make sure that your secret name doesn't disclose sensitive information.
35
+
To learn more about setting secrets in variables, see [Set secret variables](../process/set-secret-variables.md).
46
36
47
37
### Limit access to secret variables
48
38
49
-
To limit access to secrets in Azure DevOps, follow these best practices:
50
-
51
-
- Store your secrets in [Azure Key Vault](/azure/key-vault/). With Azure Key Vault, you can then use Azure's role-based access control model to limit access to a secret or group of secrets.
52
-
- Set secret variables in the UI for a pipeline. Secret variables set in the pipeline settings UI for a pipeline are scoped to the pipeline where they're set. So, you can have secrets that are only visible to users with access to that pipeline.
53
-
- Set secrets in a variable group. Variable groups follow the [library security model](../library/index.md#library-security). You can control who can define new items in a library, and who can use an existing item.
39
+
To limit access to secrets in Azure DevOps, follow one of these practices:
40
+
41
+
- Store your secrets in [Azure Key Vault](/azure/key-vault/). By using Azure Key Vault, you can use Azure role-based access control to limit access to a secret or group of secrets.
42
+
- Set secret variables in the pipeline UI. These variables are scoped to the pipeline where they're set, so are visible only to users of that pipeline.
43
+
- Set secrets in [variable groups](../library/variable-groups.md). Variable groups follow the [library security](../library/index.md#library-security) model, so you can control who can access or create items.
54
44
55
45
## Don't write secrets to logs
56
46
57
-
Azure Pipelines attempts to scrub secrets from logs wherever possible, but it's not foolproof. Avoid echoing secrets to the console, using them in command line parameters, or logging them to files. Be cautious when you use Azure CLI commands that output sensitive information. Use the [`None output format`](https://aka.ms/clisecrets), and if you need to retrieve a secret from an Azure CLI call, [`Use none output format and retrieve security information to a secret variable`](/cli/azure/format-output-azure-cli#use-none-and-retrieve-security-information-at-a-later-time).
47
+
Azure Pipelines attempts to scrub secrets from logs wherever possible, but isn't foolproof. Avoid echoing secrets to the console, using them in command line parameters, or logging them to files.
48
+
49
+
Be cautious when you use Azure CLI commands that output sensitive information. Use the [None output format](https://aka.ms/clisecrets), and if you need to retrieve a secret from an Azure CLI call, [retrieve security information from a secret variable`](/cli/azure/format-output-azure-cli#retrieve-security-information-at-a-later-time).
58
50
59
51
## Don't use structured data as secrets
60
52
61
-
Avoid using structured data formats like JSON, XML, or YAML, to encapsulate secret values, including control characters such as carriage return,`\r`, and line feed,`\n`. Instead, create individual secrets for each sensitive value. This approach ensures better redaction accuracy and minimizes the risk of exposing sensitive data inadvertently.
53
+
Avoid using structured data formats like JSON, XML, or YAML to encapsulate secret values, including control characters such as carriage return `\r` and line feed`\n`. Instead, create individual secrets for each sensitive value. This approach ensures better redaction accuracy and minimizes the risk of inadvertently exposing sensitive data.
62
54
63
-
## Audit how secrets are handled
55
+
## Audit secret use
64
56
65
-
To audit how secrets are used in Azure Pipelines, follow these best practices:
57
+
To audit how your pipelines use secrets, follow these best practices:
66
58
67
-
-**Review source code:** Examine the source code of the repository hosting the pipeline. To ensure secrets get handled correctly, check any tasks used in the pipeline. For instance, verify that secrets aren't inadvertently sent to unintended hosts or explicitly printed to log output.
68
-
-**Inspect run logs:** After testing valid and invalid inputs, view the run logs for your pipeline. Ensure that secrets are properly redacted and not exposed. Sometimes, errors in commands or tools might inadvertently leak secrets into error logs. While Azure Pipelines attempts to scrub secrets from logs, manual review is still essential.
59
+
-**Review source code.** Examine the source code of the repository that hosts the pipeline. To ensure secrets are handled correctly, check all tasks the pipeline uses. Verify that secrets aren't inadvertently sent to unintended hosts or explicitly printed to log output.
60
+
-**Inspect run logs.** After testing valid and invalid inputs, view the run logs for your pipeline. Ensure that secrets are properly redacted and not exposed. Sometimes, errors in commands or tools might inadvertently leak secrets into error logs. While Azure Pipelines attempts to scrub secrets from logs, manual review is still essential.
69
61
70
62
## Audit and rotate secrets
71
63
72
64
To audit and rotate secrets, follow these best practices:
73
65
74
-
-**Review registered secrets:** Periodically assess the secrets registered in your pipelines. Confirm that they're still necessary, and remove any that are no longer needed, which helps reduce clutter and potential security risks.
75
-
-**Rotate secrets:** Regularly rotate secrets to minimize the window of time during which a compromised secret could be exploited. By changing secrets periodically, you enhance security.
76
-
-**[Secret variables](../process/set-secret-variables.md):** Use secret variables to securely store sensitive information like API keys, passwords, or other credentials within your pipeline.
77
-
-**[Azure Key Vault](/azure/key-vault/general/overview):** Use Azure Key Vault to store and manage secrets securely.
78
-
-**[Service connections](../library/service-endpoints.md):** These service connections allow your pipeline to connect to external services (for example, Azure, GitHub, Docker Hub). Ensure proper configuration and secure handling of service connection secrets.
79
-
-[**Personal access tokens (PATs)**](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md): Keep PAT duration short and choose the minimal permissions needed during creation.
66
+
- Periodically review the secrets registered in your pipelines. Confirm that they're still necessary and remove any that are no longer needed. This practice helps reduce clutter and potential security risks.
67
+
- Ensure proper configuration and secure handling of service connection secrets.
68
+
- Keep [Personal Access Token (PAT)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) duration short and choose the minimal permissions needed during creation.
69
+
- Regularly rotate secrets to minimize the amount of time that a compromised secret could be exploited. Changing secrets periodically enhances security.
80
70
81
71
## Use YAML templates
82
72
83
73
Instead of including inline scripts with secret parameters directly in your pipeline YAML, use [templates](templates.md). This approach enhances security by abstracting sensitive information away from the main pipeline.
84
74
85
-
To implement this approach, create a separate YAML file for your script and then store that script in a separate, secure repository. You can then reference the template and pass a secret variable in your YAML as a parameter. The secure variable should come from Azure Key Vault, a variable group, or the pipeline UI. For more information on using templates, see the [Template usage reference](../process/templates.md).
75
+
To implement this approach, create a separate YAML file for your script and store that script in a separate, secure repository. You can then reference the template and pass a secret variable from Azure Key Vault, a variable group, or the pipeline UI in your YAML as a parameter. For more information about using templates, see the [Template usage reference](../process/templates.md).
86
76
87
77
## Limit secrets with branch policies and variable group permissions
88
78
89
-
To make sure that secrets are tied to the `main` branch and not accessible to random branches, you can use a combination of variable group permissions, conditional job insertion, and branch policies.
79
+
To make sure that secrets are tied to a certain branch and not accessible to random branches, you can use a combination of variable group permissions, conditional job insertion, and branch policies.
90
80
91
-
With branch policies, you can enforce [build validation policies](../../repos/git/branch-policies.md#build-validation) that only allow builds from the main branch. Then, you can use [variable group permissions](../library/variable-groups.md) to make sure that only authorized pipelines have access to the secrets stored in your variable group. Last, you can use a condition in your pipeline to make sure that the variable group can only be referenced by a push to the `main` branch.
81
+
Enforce [build validation policies](../../repos/git/branch-policies.md#build-validation) that allow builds only from a certain branch. Thenuse [variable group permissions](../library/variable-groups.md) to ensure that only authorized pipelines can access the secrets stored in your variable group. Finally, use a condition in your pipeline to ensure that only a push to the designated branch can reference the variable group.
92
82
93
83
```yaml
94
84
jobs:
@@ -103,12 +93,8 @@ jobs:
103
93
- group: your-variable-group-name
104
94
```
105
95
106
-
## Next steps
107
-
108
-
> [!div class="nextstepaction"]
109
-
> [Best practices for protecting Azure secrets](/azure/security/fundamentals/secrets-best-practices)
110
-
111
-
## Related articles
96
+
## Related content
112
97
98
+
- [Best practices for protecting Azure secrets](/azure/security/fundamentals/secrets-best-practices)
113
99
- [Key and secret management considerations in Azure](/azure/well-architected/security/design-storage-keys)
0 commit comments