從已驗證摘要取用套件

發行項
03/08/2024

許多 NuGet 作業，例如還原和安裝，都需要與一或多個套件來源通訊，這些來源可以在 nuget.config 檔案中設定。針對 HTTP 摘要，NuGet 會提出未經驗證的要求，如果伺服器以 HTTP 401 回應回應，NuGet 會依下列順序搜尋認證：

環境變數 NuGetPackageSourceCredentials_{name}。
nuget.config 檔案中的認證。
如果您的套件來源提供 NuGet 認證提供者，請使用 NuGet 認證提供者。

您需要使用的認證取決於套件來源。因此，除非您使用認證提供者，否則您應該向套件來源檢查要使用的認證。套件來源通常會禁止您使用您的密碼（使用登入網站）與 NuGet。您通常需要建立個人存取令牌作為 NuGet 的密碼，但您應該檢查您使用的 NuGet 伺服器檔。某些套件來源，例如 Azure DevOps 和 GitHub，具有限定範圍的存取令牌，因此您可能需要確定您所建立的任何令牌都包含必要的範圍。

管理認證的安全性最佳做法

雖然 NuGet 會依上述順序搜尋認證，但建議您依照下列順序，在使用私人摘要進行驗證時安全地管理認證：

認證提供者：強烈建議盡可能使用認證提供者。此方法可避免將秘密儲存在純文本中，並將不小心透過原始檔控制公開秘密的風險降到最低。此外，它通常會減少認證到期或變更時需要更新的位置數目。如果認證提供者支援單一登錄，它可能會降低登入的頻率，或儲存認證的位置數目。如需詳細資訊，請參閱認證提供者一節。
nuget.config 中的加密認證：如果認證提供者無法使用，您應該考慮使用加密的認證。此方法藉由以加密格式儲存認證來提供額外的安全性層。如需詳細資訊，請參閱 nuget.config 檔案中認證一節。

注意

請注意，只有 Windows 支援加密的密碼。此外，他們只能在同一部計算機上和原本加密它們的相同使用者解密。
在 nuget.config 中使用環境變數宏：如果無法使用加密認證，請考慮使用環境變數宏將 認證儲存在 nuget.config 檔案中。此方法可讓您參考包含實際認證的環境變數。其可增強透明度，並協助使用者瞭解其認證設定方式。如需詳細資訊，請參閱 nuget.config 檔案中認證一節。
直接使用環境變數：作為後援選項，您可以將認證直接儲存在環境變數中。不過，請注意，相較於在 nuget.config 檔案中使用環境變數宏，此方法可提供較少的可見度和控制。如需詳細資訊，請參閱環境變數中認證一節。
NuGet.Config 中的純文本認證：強烈建議您使用上述其中一個選項。如果這些選項不可行，您可以將認證儲存在 nuget.config 檔案中。不過，只有在沒有其他安全選項可供使用的環境中，才應該使用此選項。如需詳細資訊，請參閱 nuget.config 檔案中認證一節。

警告

將認證以純文本儲存在 nuget.config 檔案中，特別是在原始檔控制中儲存盤案時，可能會有風險，因為它會增加意外認證流失的機會。如果您必須將認證儲存在 nuget.config 檔案中，請考慮使用上述其中一個更安全的選項。

藉由遵守這些最佳做法，您可以安全地驗證私人摘要，同時將敏感性資訊暴露的風險降到最低。

環境變數中的認證

NuGet 會搜尋名為 NuGetPackageSourceCredentials_{name}的環境變數，其中 {name} 是 nuget.config 檔案套件來源中的值key="name"。環境變數的值必須是 Username={username};Password={password}，而且可以選擇性地包含 ;ValidAuthenticationTypes={types}。如果環境變數不符合 NuGet 慣例，或值不符合 NuGet 的預期模式，NuGet 會以無訊息方式忽略環境變數，並繼續搜尋其他地方套件來源的認證。沒有記錄可發出 NuGet 使用環境變數認證的訊號，如果環境變數包含過期的秘密，而且新密碼會新增至 nuget.config 檔案，因為組態 檔優先順序較低，因此在偵錯驗證問題時可能會造成困難。

提示

在 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 中的 NuGet 找不到處理來源的 Visual Studio 認證提供者，則會回復至命令行認證提供者。

Visual Studio 2017 15.9 版和更新版本包含適用於 Azure Artifacts 的認證提供者，可在 Visual Studio、MSBuild 和 NuGet.exe 內運作。不過，Visual Studio 不包含 .NET SDK 的認證提供者，因此必須個別安裝才能使用 dotnet CLI。

認證提供者清單

有功能要求可透過 .NET 工具安裝認證提供者，這可能會讓您更容易探索其他認證提供者。在實作之前，以下是我們所知道的認證提供者清單：

AWS CodeArtifact NuGet 認證提供者
Azure Artifacts 認證提供者。此連結僅適用於命令行認證提供者。
適用於 Visual Studio 的 MyGet 認證提供者。