document security best practices for managing credentials. (#3240)

Author: kartheekp-ms

docs/concepts/Security-Best-Practices.md

@@ -119,7 +119,9 @@ For more information about Dependabot alerts & security updates, [see the follow
 
 When using multiple public & private NuGet source feeds, a package can be downloaded from any of the feeds. To ensure your build is predictable and secure from known attacks such as [Dependency Confusion](https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610), knowing what specific feed(s) your packages are coming from is a best practice. You can use a single feed or private feed with upstreaming capabilities for protection.
 
-For more information to secure your package feeds, see [3 Ways to Mitigate Risk When Using Private Package Feeds](https://azure.microsoft.com/resources/3-ways-to-mitigate-risk-using-private-package-feeds/).
+For more information to secure your package feeds, see [3 Ways to Mitigate Risk When Using Private Package Feeds](https://azure.microsoft.com/resources/3-ways-to-mitigate-risk-using-private-package-feeds/en-us/).
+
+When using a private feed, refer to the [security best practices for managing credentials](../consume-packages/consuming-packages-authenticated-feeds.md#security-best-practices-for-managing-credentials).
 
 ### Client trust policies
 

docs/consume-packages/consuming-packages-authenticated-feeds.md

@@ -16,18 +16,50 @@ For HTTP feeds, NuGet will make an unauthenticated request, and if the server re
 1. [Credentials in *nuget.config* files](#credentials-in-nugetconfig-files).
 1. [Use a NuGet credential provider, if your package source provides one](#credential-providers).
 
-> [!NOTE]
-> We recommend using a credential provider when possible.
-> Using a credential provider avoids secrets in the *nuget.config* file, reducing risk of accidentally leaking secrets via source control.
-> Additionally, it typically reduces the number of places you need to update when a credential expires or changes.
-> If the credential provider supports single sign-on, it may reduce the number of times you need to login, or the number of places that credentials need to be saved.
-
 The credentials you need to use are determined by the package source.
 Therefore, unless you're using a credential provider, you should check with your package source for what credentials to use.
 It is very common for package sources to forbid you from using your password (that you log into the website with) with NuGet.
 Typically you need to create a Personal Access Token to use as NuGet's password, but you should check the documentation for the NuGet server you're using.
 Some package sources, such as Azure DevOps and GitHub, have scoped access tokens, so you may need to ensure that any tokens you create include the required scope.
 
+## Security best practices for managing credentials
+
+Although NuGet searches for credentials in the order mentioned above, we recommend the following sequence for securely managing credentials when authenticating with private feeds:
+
+1. **Credential Provider**: It is highly recommended to use a credential provider whenever possible.
+This approach avoids storing secrets in plain text and minimizes the risk of accidentally exposing secrets through source control.
+Moreover, it generally reduces the number of places you need to update when a credential expires or changes.
+If the credential provider supports single sign-on, it may decrease the frequency of logins or the number of places where credentials need to be saved.
+Refer to the [credential providers](#credential-providers) section for more information.
+
+1. **Encrypted Credentials in nuget.config**: If a credential provider is not available, you should consider using encrypted credentials.
+This approach provides an extra layer of security by storing the credentials in an encrypted format.
+For more information, refer to the section on [credentials in *nuget.config* files](#credentials-in-nugetconfig-files).
+
+    > [!NOTE]
+    > Be aware that encrypted passwords are only supported on Windows. 
+    > Moreover, they can only be decrypted on the same machine and by the same user who originally encrypted them.
+
+1. **Using Environment Variable Macros in nuget.config**: If using encrypted credentials is not possible, consider storing the credentials in the *nuget.config* file with environment variable macros.
+This approach allows you to reference environment variables that contain the actual credentials. 
+It enhances transparency and helps end users understand how their credentials are configured.
+For more information, refer to the section on [credentials in *nuget.config* files](#credentials-in-nugetconfig-files).
+
+1. **Using Environment Variables Directly**: As a fallback option, you can store the credentials directly in environment variables.
+However, be aware that this approach may offer less visibility and control compared to using environment variable macros in the *nuget.config* file.
+For more information, refer to the section on [credentials in environment variables](#credentials-in-environment-variables).
+
+1. **Clear Text Credentials in NuGet.Config**: It is highly recommended to use one of the previously mentioned options.
+If these options are not feasible, you can store the credentials in the *nuget.config* file.
+However, this option should only be used in environments where no other secure option is available.
+For more information, refer to the section on [credentials in *nuget.config* files](#credentials-in-nugetconfig-files).
+
+    > [!WARNING]
+    > Storing credentials in clear text in the *nuget.config* file, especially when saving the file in source control, is risky as it increases the chances of accidental credential leaks.
+    > If you must store credentials in the *nuget.config* file, consider using one of the more secure options mentioned above.
+
+By adhering to these best practices, you can securely authenticate private feeds while minimizing the risk of sensitive information exposure.
+
 ## Credentials in environment variables
 
 NuGet will search for an environment variable named `NuGetPackageSourceCredentials_{name}`, where `{name}` is the value of `key="name"` in your *nuget.config* file's package source.
@@ -68,7 +100,7 @@ For more information about valid authentication types, see [the docs on package
 See [the *nuget.config* file reference doc section on package source credentials](../reference/nuget-config-file.md#packagesourcecredentials) for more information, including syntax.
 However, it's easier to use [`dotnet nuget update source`](/dotnet/core/tools/dotnet-nuget-update-source) on the command line to set the credentials.
 
-> ![Warning]
+> [!WARNING]
 > Take care when setting credentials in *nuget.config* files, especially when saving the credential as plain text.
 > If the credential is written to a *nuget.config* file that is in source control, there is an increased risk of accidentally leaking the secret.
 >

docs/reference/cli-reference/cli-ref-sources.md

@@ -53,6 +53,10 @@ where `<operation>` is one of *List, Add, Remove, Enable, Disable,* or *Update*,
 
   Specifies the password for authenticating with the source.
 
+  > [!NOTE]
+  > Be aware that encrypted passwords are only supported on Windows. 
+  > Moreover, they can only be decrypted on the same machine and by the same user who originally encrypted them.
+
 - **`-src|-Source`**
 
   Path to the package(s) source.
@@ -61,6 +65,10 @@ where `<operation>` is one of *List, Add, Remove, Enable, Disable,* or *Update*,
 
   Indicates to store the password in unencrypted text instead of the default behavior of storing an encrypted form.
 
+  > [!WARNING]
+  > Storing passwords in clear text is strongly discouraged.
+  > For more information on managing credentials securely, refer to the [security best practices for consuming packages from private feeds](../../consume-packages/consuming-packages-authenticated-feeds.md#security-best-practices-for-managing-credentials).
+
 - **`-UserName`**
 
   Specifies the user name for authenticating with the source.
@@ -80,9 +88,6 @@ where `<operation>` is one of *List, Add, Remove, Enable, Disable,* or *Update*,
 
   Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`.
 
-> [!Note]
-> Make sure to add the sources' password under the same user context as the nuget.exe is later used to access the package source. The password will be stored encrypted in the config file and can only be decrypted in the same user context as it was encrypted. So for example when you use a build server to restore NuGet packages the password must be encrypted with the same Windows user under which the build server task will run.
-
 Also see [Environment variables](cli-ref-environment-variables.md)
 
 ## Examples

docs/reference/nuget-config-file.md

@@ -150,6 +150,12 @@ Optionally, valid authentication types can be specified with the `-validauthenti
 | cleartextpassword | The unencrypted password for the source. Note: environment variables can be used for improved security. |
 | validauthenticationtypes | Comma-separated list of valid authentication types for this source. Set this to `basic` if the server advertises NTLM or Negotiate and your credentials must be sent using the Basic mechanism, for instance when using a PAT with on-premises Azure DevOps Server. Other valid values include `negotiate`, `kerberos`, `ntlm`, and `digest`, but these values are unlikely to be useful. |
 
+> [!WARNING]
+> Storing passwords in clear text is strongly discouraged.
+> Please note that encrypted passwords are only supported on Windows.
+> Furthermore, they can only be decrypted when used on the same machine and by the same user who originally encrypted them.
+> For more information on managing credentials securely, refer to the [security best practices for consuming packages from private feeds](../consume-packages/consuming-packages-authenticated-feeds.md#security-best-practices-for-managing-credentials).
+
 > [!Tip]
 > If a non-encrypted password is passed for `password` the error message ["The parameter is incorrect" will occur](https://github.com/NuGet/Home/issues/3245).
 
@@ -170,49 +176,51 @@ In the config file, the `<packageSourceCredentials>` element contains child node
 </packageSourceCredentials>
 ```
 
-When using unencrypted passwords stored in an environment variable:
+Additionally, valid authentication methods can be supplied.
 
 ```xml
 <packageSourceCredentials>
     <Contoso>
         <add key="Username" value="[email protected]" />
-        <add key="ClearTextPassword" value="%ContosoPassword%" />
+        <add key="Password" value="..." />
+        <add key="ValidAuthenticationTypes" value="basic" />
     </Contoso>
     <Test_x0020_Source>
         <add key="Username" value="user" />
-        <add key="ClearTextPassword" value="%TestSourcePassword%" />
+        <add key="Password" value="..." />
+        <add key="ValidAuthenticationTypes" value="basic, negotiate" />
     </Test_x0020_Source>
 </packageSourceCredentials>
 ```
 
-When using unencrypted passwords:
+When using unencrypted passwords stored in an environment variable:
 
 ```xml
 <packageSourceCredentials>
     <Contoso>
         <add key="Username" value="[email protected]" />
-        <add key="ClearTextPassword" value="33f!!lloppa" />
+        <add key="ClearTextPassword" value="%ContosoPassword%" />
     </Contoso>
     <Test_x0020_Source>
         <add key="Username" value="user" />
-        <add key="ClearTextPassword" value="hal+9ooo_da!sY" />
+        <add key="ClearTextPassword" value="%TestSourcePassword%" />
     </Test_x0020_Source>
 </packageSourceCredentials>
 ```
 
-Additionally, valid authentication methods can be supplied:
+When using unencrypted passwords:
+> [!WARNING]
+> Storing passwords in clear text is strongly discouraged.
 
 ```xml
 <packageSourceCredentials>
     <Contoso>
         <add key="Username" value="[email protected]" />
-        <add key="Password" value="..." />
-        <add key="ValidAuthenticationTypes" value="basic" />
+        <add key="ClearTextPassword" value="33f!!lloppa" />
     </Contoso>
     <Test_x0020_Source>
         <add key="Username" value="user" />
         <add key="ClearTextPassword" value="hal+9ooo_da!sY" />
-        <add key="ValidAuthenticationTypes" value="basic, negotiate" />
     </Test_x0020_Source>
 </packageSourceCredentials>
 ```