使用经过身份验证的源中的包

  • 项目

许多 NuGet 操作（如还原和安装）都需要与一个或多个包源进行通信，可在 nuget.config 文件中进行配置。 如果是 HTTP 源，NuGet 会发出未经过身份验证的请求，如果服务器响应为 HTTP 401 响应，NuGet 会按以下顺序搜索凭证。

  1. 环境变量 NuGetPackageSourceCredentials_{name}。
  2. nuget.config 文件中的凭证。
  3. 如果包源提供一个，则使用 NuGet 凭证提供程序。

需要使用的凭证由包源决定。 因此，除非使用的是凭证提供程序，否则应检查包源要使用什么凭证。 很常见的情况是，包源会禁止你使用 NuGet 密码（即登录网站时所使用的密码）。 通常需要创建个人访问令牌才能使用 NuGet 的密码，但应该查看文档了解正在使用的的 NuGet 服务器。 Azure DevOps 和 GitHub 等某些包源具有有范围的访问令牌，因此可能需要确保创建的任何令牌包含所需的范围。

管理凭证的安全最佳做法

虽然 NuGet 按上述顺序搜索凭证，不过建议在对私有源进行身份验证时按照以下顺序进行搜索，以确保安全地管理凭证：

  1. 凭证提供程序：强烈建议尽可能使用凭证提供程序。 这样做可以避免在纯文本中存储密钥，且最大限度减少通过源控件意外泄露密钥的风险。 此外，一般还可减少当凭证过期或更改时，需要更新的地点数量。 如果凭证提供程序支持单一登录，则可能减少登录频率或需要保存凭证的地点数量。 有关详细信息，请参阅凭证提供程序部分。

  2. nuget.config 中的加密凭证：如果没有凭证提供程序，应该考虑使用加密凭证。 这样做可通过以加密格式存储凭证，提供多一层的安全保护。 有关详细信息，请参阅 nuget.config 中的凭证部分。

    注意

    请注意，仅在 Windows 上支持加密密码。 此外，加密密码只能在同一台计算机，由最初对其进行加密的同一用户解密。

  3. 使用 nuget.config 中的环境变量宏：如果不能使用加密凭证，请考虑在包含环境变量宏的 nuget.config 文件中存储凭证。 这样做可以引用包含实际凭证的环境变量。 既能提高透明度，也有助于最终用户了解其凭证是如何配置的。 有关详细信息，请参阅 nuget.config 中的凭证部分。

  4. 直接使用环境变量：作为应变选项，可直接将凭证存储在环境变量中。 但请注意，与使用 nuget.config 文件中的环境变量宏相比，这样做的可见性更低且控制力更弱。 有关详细信息，请参阅环境变量中的凭证部分。

  5. NuGet.Config 中的明文文本凭证：强烈建议使用之前提到的选项之一。 如果这些选项不可行，则可以将凭证存储在 nuget.config 文件。 但是，此选项只能在不提供其他安全选项的环境中使用。 有关详细信息，请参阅 nuget.config 中的凭证部分。

    警告

    以明文文本形式将凭证存储在 nuget.config 文件中存在风险，尤其是将文件保存在源控件中时，会增加意外泄露凭证的机率。 如果必须将凭证存储在 nuget.config 文件中，请考虑使用上述更安全的选项之一。

遵循这些最佳做法，可以安全地对私有源进行身份验证，同时最大限度减少敏感信息泄露的风险。

环境变量中的凭证

NuGet 会搜索名为“NuGetPackageSourceCredentials_{name}”的环境变量，其中 {name} 是 nuget.config 文件的包源中的值。 该环境变量的值必须是 Username={username};Password={password}，且可以包含 ;ValidAuthenticationTypes={types}（可选）。 如果该环境变量不匹配 NuGet 的约定，或该值不满足 NuGet 的预期模式，NuGet 会悄悄地忽略该环境变量，然后在其他地方继续搜索包源的凭证。 没有日志显示 NuGet 使用该环境变量中的凭证，这会导致以下问题：如果环境变量包含过期密钥，且 nuget.config 文件添加了新的密钥，则很难 debug 身份难问题，因为配置文件的优先级更低。

提示

在 CI/CD 管道中使用环境变量是一个不错的选择，可以最大程度地降低在日志中捕获机密的风险。

例如，请考虑以下 nuget.config 文件：

<configuration>
  <packageSources>
    <clear />
    <add key="Contoso" value="https://nuget.contoso.com/v3/index.json" />
  </packageSources>
</configuration>

这种情况下，源名称为 Contoso，而 NuGet 会寻找名为“NuGetPackageSourceCredentials_Contoso”的环境变量。 如 nuget.config 文件中定义的，一些平台区分大小写，因此使用环境名称和源名称时注意大小写拼写正确。

如果用户名为 nugetUser，密码为 secret123，则环境变量的值应设置为 Username=nugetUser;Password=secret123。 如果 NuGet 应仅使用 HTTP 基本身份验证的凭证，而不能使用其他身份验证方案，则可将环境变量设置为 Username=nugetUser;Password=secret123;ValidAuthenticationTypes=Basic。 有关有效的身份验证类型的详细信息，请参阅 nuget.config 文件中的包凭证文档。

注意

环境变量对允许使用的字符有限制，不同的操作系统可能有不同的限制。 例如，不允许使用空格。 因此，使用此环境变量功能为使用对平台的环境变量而言无效的任何字符的包源指定 NuGet 凭证。 这种情况下，应重命名 nuget.config 文件中的包源。

nuget.config 文件中的凭证

nuget.config 文件可以包含包源凭据。 请参阅 nuget.config 文件参考文件关于包源凭证的部分，了解包括语法在内的详细信息。 但是，在命令行上使用 dotnet nuget update source 设置凭证更简单。

警告

在 nuget.config 文件中设置凭证时要小心，尤其是将凭证保存为纯文本时。 如果将凭证写入到位于源控件中的 nuget.config 文件中，会增加意外泄露密钥的风险。

由于 NuGet 会累计多个文件的设置，因此建议将凭证保存到用户的 nuget.config 文件。 此外，出于版本可靠性的考虑，还建议将包源存储在解决方案（源代码存储库）nuget.config 文件中，包括 <clear /> 元素。

nuget.config 文件中的用户名和纯文本密码可通过在想要使用的环境变量的开头和结尾处添加 % 来使用环境变量。 有关详细信息，请参阅环境变量 nuget.config 参考文件。

凭据提示程序

NuGet 具有扩展性模型，允许插件提供 NuGet 凭证。 必须安装凭证提供的路径，NuGet 才能发现不同于 .NET Framework（NuGet.exe、MSBuild 和 Visual Studio）和 .NET SDK（在 .NET 5+ 运行时上运行）。

NuGet 具有在交互式模式和非交互式模式下运行的概念。 在非交互式模式下运行时，会要求凭证提供程序不要阻止 NuGet。 在交互式模式下运行时，凭证提供程序可能会提示你登录。 不同的工具会有不同的默认设置，因此根据具体应用场景，可能需要选择加入或退出交互式模式。

工具 默认 切换
dotnet CLI 非交互式 --interactive 参数。 例如 dotnet restore --interactive。
MSBuild 非交互式 NuGetInteractive MSBuild 属性。 例如 msbuild -t:restore -p:NuGetInteractive=true。
NuGet.exe 交互 -NonInteractive 参数。 例如 nuget.exe restore -NonInteractive。
Visual Studio 交互 无法在非交互模式下运行。

NuGet.exe 同时支持 V1 和 V2 凭证提供程序，而 MSBuild 和 .NET SDK 则仅支持跨平台 (V2) 插件。

在 Visual Studio 中，NuGet 具有 Visual Studio 凭证提供程序接口。凭证提供程序可使用此接口提供图形登录体验或在必要时调用 Visual Studio API。 如果不能找到能够处理源的 Visual Studio 凭证提供程序，Visual Studio 的 NuGet 会回退到命令行凭证提供程序。

Visual Studio 2017 版本 15.9 及更高版本包括适用于 Azure Artifacts 的凭证提供程序，该提供程序适用于 Visual Studio、MSBuild 和 NuGet.exe。 但是，Visual Studio 不包括 .NET SDK 的凭据提供程序，因此 必须单独 安装才能使用 dotnet CLI。

凭证提供程序列表

有一个功能请求希望通过 .NET 工具让凭证提供程序可安装，这可能会让发现其他凭证提供程序变得更简单。 在实现此操作之前，下面是我们了解的凭证提供程序列表：