diff --git a/vcpkg/TOC.yml b/vcpkg/TOC.yml index e56f6a95..ff330db3 100644 --- a/vcpkg/TOC.yml +++ b/vcpkg/TOC.yml @@ -39,6 +39,11 @@ - name: Install native dependencies in a CLR application displayName: .NET, C#, managed, CLI href: consume/cpp-cli.md + - name: Authenticate to third-party services + items: + - name: Authenticate to NuGet package feeds + displayName: binary cache, nuget.config, api key + href: consume/third-party-authentication.nuget.md - name: Install private or custom dependencies items: - name: Install a locally modified dependency using overlay ports diff --git a/vcpkg/consume/third-party-authentication.nuget.md b/vcpkg/consume/third-party-authentication.nuget.md new file mode 100644 index 00000000..81206895 --- /dev/null +++ b/vcpkg/consume/third-party-authentication.nuget.md @@ -0,0 +1,168 @@ +--- +title: "Authenticate to NuGet package feeds" +description: Explain authentication methods for accessing NuGet package feeds with vcpkg +author: vicroms +ms.author: viromer +ms.date: 03/03/2025 +ms.topic: tutorial +--- +# Authenticate to NuGet package feeds + +This article explains how to engage vcpkg features that require you to authenticate to NuGet package feeds. + +## Binary cache provider: NuGet + +NuGet package feeds are supported by many cloud-storage providers, like [Azure Artifacts]() +and [GitHub Package registry](). +They also provide access control capabilities, which make them suitable for limiting access within your organization or +work group. + +## Prerequisites + +- A NuGet packages feed + +## 1 - Add `nuget.exe` to PATH + +vcpkg acquires a copy of the `nuget.exe` executable to use for binary caching operations. + +Run the `vcpkg fetch nuget` command to obtain the location of the NuGet executable and add it to path. + +### Example of `vcpkg fetch nuget` output + +```PowerShell +vcpkg fetch nuget +C:\dev\vcpkg\downloads\tools\nuget-6.10.0-windows\nuget.exe +``` + +Modify your `PATH` environment variable to add the directory containing `nuget.exe`. + +### Example setting `PATH` in a PowerShell session + +```PowerShell +$env:PATH="$env:PATH;C:\dev\vcpkg\downloads\tools\nuget-6.10.0-windows" +``` + +## 2 - Add your private feed as a NuGet packages source + +### Method 1: Preload credentials with the NuGet CLI + +This method creates a NuGet packages source that stores your feed URL and the necessary credentials. + +> [!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. Add your feed as a NuGet source and include its authentication credentials. + +```PowerShell +nuget.exe sources add -Name -Source -UserName -Password +``` + +Replace `` and `` with your authentication credentials. Replace `` with your feed's URL. + +> [!WARNING] +> Storing passwords in clear text is strongly discouraged. For more information on managing credentials securely, refer +> to the [security best practies for consuming packages from private +> feeds](/nuget/consume-packages/consuming-packages-authenticated-feeds#security-best-practices-for-managing-credentials). + +On non-Windows you may need to add the `-StorePasswordInClearText` option to the command-line. + +### Method 2: Create a `nuget.config` file + +You can create a `nuget.config` file to configure NuGet packages sources. Use the template below as a base to add your own +NuGet feeds as package sources. + +#### Template `nuget.config` + +> [!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 practies for consuming packages +> from private feeds](/nuget/consume-packages/consuming-packages-authenticated-feeds#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**](). + +```XML + + + + + + + + + + + + + + + + + +``` + +Replace `` with your NuGet feed's URL. You can reference environment variables by surronding them with `%`, for +example `%NUGET_USERNAME%` and `%NUGET_PASSWORD%`. + +> [!WARNING] +> Storing passwords in clear text is strongly discouraged. + +On non-Windows, you may need to use `ClearTextPassword` instead of `Password`. + +Read the [NuGet config file documentation](/nuget/reference/nuget-config-file) to learn more. + +## 3 - (Optional) Provide an API Key + +Some NuGet package feed providers require that you push packages to the feed using an API key. For example, GitHub Packages +requires a GitHub Personal Access Token as its API Key; while Azure Artifacts needs that the API key is not-empty, but can +have any arbitrary value. + +### Method 1: Set the API Key using the NuGet CLI + +Use the `nuget setapikey` command to set the API key for a specific feed URL. + +#### Example of setting API Key in PowerShell + +```PowerShell +.$(vcpkg fetch nuget) setapikey $GITHUB_PAT_TOKEN -Source https://nuget.pkg.github.com/$GITHUB_OWNER/index.json +``` + +### Method 2: Set the API key using a NuGet config file + +If you're using a `nuget.config` file to add your package feed sources, you can set their API keys in the same file by adding +an [``](/nuget/reference/nuget-config-file#apikeys) section. + +### Example of setting API Key using a `nuget.config` file + +```XML + + + +``` + +## 4 - Configure binary caching to use your NuGet feed + +Set the `VCPKG_BINARY_SOURCES` environment variable as follows: + +```PowerShell +$env:VCPKG_BINARY_SOURCES="nuget,,readwrite" +``` + +If you're using a `nuget.config` file, use the following configuration instead: + +```PowerShell +$env:VCPKG_BINARY_SOURCES="nugetconfig,,readwrite" +``` + +The `readwrite` permission is optional and can be changed to `read` or `write` only. + +## Next steps + +Here are other tasks to try next: + +- [Change the default binary cache location](binary-caching-default.md) +- [Set up a local binary cache](binary-caching-local.md) +- [Set up a binary cache in your GitHub Actions workflow using GitHub Packages]binary-caching-github-packages.md) +- [Set up a binary cache in your GitHub Actions workflow using GitHub Actions Cache](binary-caching-github-actions-cache.md)