diff --git a/_contentTemplates/common/get-started.md b/_contentTemplates/common/get-started.md index eeb3892e8..e8e262a12 100644 --- a/_contentTemplates/common/get-started.md +++ b/_contentTemplates/common/get-started.md @@ -21,11 +21,40 @@ #end +#generate-nuget-api-key + +As the Telerik NuGet server requires authentication, the first step is to obtain an API key that you will use instead of a password. Using an API key instead of a password is a more secure approach, especially when working with the [.NET CLI](#use-the-net-cli) or a [`NuGet.Config` file](#edit-the-nugetconfig-file). + +1. Go to the [API Keys](https://www.telerik.com/account/downloads/api-keys) page in your Telerik account. +1. Click **Generate New Key +**. +1. In the **Key Note** field, add a note that describes the API key. +1. Click **Generate Key**. +1. Select **Copy and Close**. Once you close the window, you can no longer copy the generated key. For security reasons, the **API Keys** page displays only a portion of the key. +1. Store the generated NuGet API key as you will need it in the next steps. + +Whenever you need to authenticate your system with the Telerik NuGet server, use `api-key` as the username and your generated API key as the password. +#end #add-nuget-feed ## Step 3: Add the Telerik NuGet Feed to Visual Studio -In this tutorial, you will use the [Telerik NuGet feed](slug:installation/nuget) to download the UI for Blazor components. This NuGet feed is private and requires you to authenticate with your Telerik user name and password: +In this tutorial, you will use the [Telerik NuGet feed](slug:installation/nuget) to download the UI for Blazor components. This NuGet feed is private and requires you to authenticate with a NuGet API key. + +To generate your NuGet API key: + +1. Go to the [API Keys](https://www.telerik.com/account/downloads/api-keys) page in your Telerik account. + +1. Click **Generate New Key +**. + +1. In the **Key Note** field, add a note that describes the API key. + +1. Click **Generate Key**. + +1. Select **Copy and Close**. Once you close the window, you can no longer copy the generated key. For security reasons, the **API Keys** page displays only a portion of the key. + +1. Store the generated NuGet API key as you will need it in the next steps. + +Next, add the Telerik NuGet feed to Visual Studio: 1. In Visual Studio and go to **Tools** > **NuGet Package Manager** > **Package Manager Settings**. @@ -37,9 +66,9 @@ In this tutorial, you will use the [Telerik NuGet feed](slug:installation/nuget) ![Add the Telerik NuGet Feed in Visual Studio](images/telerik-nuget-feed.png) -1. Whenever Visual Studio displays a dialog to enter credentials for `nuget.telerik.com`, use your Telerik account email and password. +1. Whenever Visual Studio displays a dialog to enter credentials for `nuget.telerik.com`, use `api-key` as the username and your NuGet API key as the password. ->tip For alternative NuGet package download options, check the [Workflow article](slug:getting-started/what-you-need). You can also [authenticate with `nuget.telerik.com` with an API key](slug:installation/nuget#use-nuget-api-key). +>tip For alternative NuGet package download options, check the [Workflow article](slug:getting-started/what-you-need). #end diff --git a/deployment/ci-cd-license-key.md b/deployment/ci-cd-license-key.md index 9e3c7a43a..615700b23 100644 --- a/deployment/ci-cd-license-key.md +++ b/deployment/ci-cd-license-key.md @@ -118,7 +118,7 @@ steps: TELERIK_LICENSE: ${{ "{{ secrets.Telerik_License_Key }}" }} ```` -Also see [Using NuGet Keys](slug:deployment-nuget#using-nuget-keys) in the article [Restoring NuGet Packages in Your CI Workflow](slug:deployment-nuget). It shows how to use the `TELERIK_NUGET_KEY` environment variable in your CI build environment. +Also see [Using API Keys](slug:deployment-nuget#using-api-keys) in the article [Restoring NuGet Packages in Your CI Workflow](slug:deployment-nuget). It shows how to use the `TELERIK_NUGET_KEY` environment variable in your CI build environment. ## Docker diff --git a/deployment/nuget-keys.md b/deployment/nuget-keys.md index 0c06780f6..1690571ca 100644 --- a/deployment/nuget-keys.md +++ b/deployment/nuget-keys.md @@ -1,7 +1,7 @@ --- title: Restoring NuGet Packages in CI page_title: Restoring NuGet Packages in CI -description: Get started with Telerik UI for Blazor and use NuGet Keys to authenticate with the Telerik NuGet server and restore packages in your CI or desktop environment. +description: Get started with Telerik UI for Blazor and use API Keys to authenticate with the Telerik NuGet server and restore packages in your CI or desktop environment. slug: deployment-nuget position: 10 --- @@ -10,52 +10,35 @@ position: 10 This article describes how to use token-based authentication for the Telerik NuGet feed. You will learn how to create and use NuGet API keys to restore Telerik NuGet packages in your Continuous Integration (CI) workflow. -The [Telerik NuGet server](slug:installation/nuget) provides two ways to authenticate: +When you need to restore the [Telerik NuGet packages](slug:getting-started/what-you-need#nuget-packages) as part of your CI, using API Keys provides a secure way to authenticate. This method does not require you to provide your Telerik credentials anywhere in the CI workflow. An API key has a limited scope and can be used only with the Telerik NuGet server. If any of your API Keys is compromised, you can quickly delete it and create a new one. -* Basic authentication with your Telerik username and password. -* Token-based authentication with a NuGet API key. +## Generating API Keys -When you need to restore the [Telerik NuGet packages](slug:getting-started/what-you-need#nuget-packages) as part of your CI, a NuGet API key is the more secure way to authenticate. This method does not require you to provide your Telerik credentials anywhere in the CI workflow. A NuGet Key has a limited scope and can be used only with the Telerik NuGet server. If any of your NuGet keys is compromised, you can quickly delete it and create a new one. +@[template](/_contentTemplates/common/get-started.md#generate-nuget-api-key) +## Storing API Keys -## Generating NuGet Keys +>warning Never check in NuGet API keys with your source code or leave them publicly visible in plain text (for example, in a `NuGet.Config` file). An API key is valuable and bad actors can use it to access the NuGet packages that are licensed under your account. A key abuse can lead to a review of the affected Telerik account. -1. In your Telerik account, go to the [**Manage NuGet Keys**](https://www.telerik.com/account/downloads/nuget-keys) page. - - ![Manage NuGet Keys](../deployment/images/manage-nuget-keys.png) - -1. Click **Generate New Key**. - -1. Enter a name for the NuGet Key and click **Generate Key**. - -1. To copy the key, click **Copy and Close**. Once you close the popup dialog, you can no longer copy the generated key. For security reasons, the **NuGet Keys** page displays only a portion of the key. - - ![Copy Generated NuGet Key](../deployment/images/copy-nuget-key.png) - - -## Storing NuGet Keys - ->warning Never check in Telerik account credentials or a NuGet API key with your source code or leave them publicly visible in plain text (for example, in a `NuGet.Config` file). A NuGet key is valuable and bad actors can use it to access the NuGet packages that are licensed under your account. A key abuse can lead to a review of the affected Telerik account. - -To protect the NuGet Key, store it as a secret environment variable. The exact store steps depend on your workflow and environment: +To protect the API key, store it as a secret environment variable. The exact store steps depend on your workflow and environment: * In GitHub Actions, save the key as a [GitHub Actions Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). -* In Azure DevOps, save the key as a [secret Azure DevOps pipeline variable](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-secret-variables). If you use an Azure DevOps Service connection instead of secret environment variables, enter `api-key` in the username field and the NuGet key as the password in the **New NuGet service connection** form editor. +* In Azure DevOps, save the key as a [secret Azure DevOps pipeline variable](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-secret-variables). If you use an Azure DevOps Service connection instead of secret environment variables, enter `api-key` in the username field and the API key as the password in the **New NuGet service connection** form editor. * In Docker images, save the key as a [Docker secret](https://docs.docker.com/tags/secrets/). -For more details on storing and protecting your NuGet Key, check the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy. +For more details on storing and protecting your API key, check the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy. The examples below assume that the secret environment variable name is `TELERIK_NUGET_KEY`. -## Using NuGet Keys +## Using API Keys -There are two common ways to use a [stored NuGet key](#storing-nuget-keys) with the Telerik NuGet server during a build: +There are two common ways to use a [stored API key](#storing-api-keys) with the Telerik NuGet server during a build: -* [Using a NuGet.Config file](#using-a-nuget-config-file) -* [Using only CLI commands](#using-net-cli-commands) +* [Use a NuGet.Config file](#using-a-nuget-config-file) +* [Use only CLI commands](#using-net-cli-commands) -For more information on how to use NuGet keys in a build, check the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy. +For more information on how to use API keys in a build, check the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy. ### Using a NuGet.Config File @@ -82,7 +65,7 @@ In your `NuGet.Config` file, set the `Username` value to `api-key` and the `Clea ### Using .NET CLI Commands -You can use the .NET CLI `add source` or `update source` commands to set the credentials of a package source. This CLI approach is applicable if your CI system doesn't support [environment variable secrets](#storing-nuget-keys) or if you do not [use a custom `NuGet.Config`](#using-a-nuget-config-file). +You can use the .NET CLI `add source` or `update source` commands to set the credentials of a package source. This CLI approach is applicable if your CI system doesn't support [environment variable secrets](#storing-api-keys) or if you do not [use a custom `NuGet.Config`](#using-a-nuget-config-file). * To set the credentials in Azure DevOps: diff --git a/getting-started/client-blazor.md b/getting-started/client-blazor.md index 44a9c688f..79619205b 100644 --- a/getting-started/client-blazor.md +++ b/getting-started/client-blazor.md @@ -48,7 +48,7 @@ This article explains how to get the \ ---password \ +--username api-key \ +--password \ --store-password-in-clear-text ```` -### Store Encrypted Credentials - -The .NET CLI supports NuGet password encryption only on the Windows platform. Note that [the encrypted password in the `NuGet.Config` file will work only for one user and one machine](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file#packagesourcecredentials). - -If you [add the Telerik package source in Visual Studio](#use-visual-studio), the credentials will be encrypted and stored in the Windows Credential Manager on Windows and in the Keychain on macOS. - -You can read more about the options provided by the NuGet tooling in the packageSourceCredentials section of the NuGet.Config reference article by Microsoft. Note the difference between the `password` and `cleartextpassword` options. - - ## Edit the NuGet.Config File NuGet package sources and other settings are stored in a `NuGet.Config` file. You can read more about the file structure in the Microsoft article [NuGet.Config Reference](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file). @@ -106,7 +103,7 @@ To edit a `NuGet.Config` file and add the Telerik feed, you need to: 1. Ensure you are editing the [correct and desired config file](https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior#config-file-locations-and-uses). You can also create a new one with the [`dotnet new nugetconfig` command](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new). -2. Add the Telerik package source to the config file. Use plain text credentials, because the .NET Core NuGet tooling does not fully support encrypted credentials. Here is an example of how your `NuGet.Config` file can look like: +2. Add the Telerik package source to the config file. For the authentication, use your [NuGet API key](#generate-a-nuget-api-key) as a password and `api-key` as a username. Add the API key in plain text, because the .NET Core NuGet tooling does not fully support encrypted credentials. Here is an example of how your `NuGet.Config` file can look like: ````XML.skip-repl @@ -119,25 +116,13 @@ To edit a `NuGet.Config` file and add the Telerik feed, you need to: - - + + ```` -## Use NuGet API Key - -There are two ways to authenticate with the Telerik NuGet server when you add the Telerik NuGet source [with the .NET CLI](#use-the-net-cli) or [edit the `NuGet.Config` file manually](#edit-the-nuget-config-file): - -* Use your Telerik account email as the username, and your Telerik password. -* Use `api-key` as the username and your personal [NuGet API Key](slug:deployment-nuget) as the password. - -You can [generate your Telerik NuGet API Key on telerik.com](https://www.telerik.com/account/downloads/nuget-keys). Read more about [using NuGet API Keys in different environments](slug:deployment-nuget). - -> Always use the NuGet API Key in plain text. - - ## Package Source Mapping The `Telerik.UI.for.Blazor` NuGet package and most of its dependencies reside on `nuget.telerik.com`. On the other hand, the [Telerik icon packages](slug:common-features-icons) and the [`Telerik.Licensing` package](slug:installation-license-key) reside on `nuget.org`. The correct [package source mapping](https://learn.microsoft.com/en-us/nuget/consume-packages/package-source-mapping) configuration should be similar to the one below. @@ -173,7 +158,6 @@ The `Telerik.UI.for.Blazor` NuGet package and most of its dependencies reside on ```` - ## Access NuGet Packages behind Firewall To access the Telerik NuGet feed behind a firewall that restricts outgoing requests, you may need to allow the following domains: @@ -183,12 +167,6 @@ To access the Telerik NuGet feed behind a firewall that restricts outgoing reque The firewall must allow some of the requests to be redirected from `nuget.telerik.com` to `downloads.cdn.telerik.com`. - -## Obsolete Telerik NuGet URL - -The NuGet v2 server at `https://nuget.telerik.com/nuget` was sunset in November 2024 and is no longer available. The v3 protocol offers faster package searches and restores, improved security, and more reliable infrastructure. To redirect your feed to the NuGet v3 protocol, all you have to do is to change your NuGet package source URL to `https://nuget.telerik.com/v3/index.json`. - - ## Troubleshooting See the [NuGet Troubleshooting](slug:troubleshooting-nuget) article for tips about common pitfalls when working with the Telerik NuGet feed. diff --git a/troubleshooting/nuget-feed.md b/troubleshooting/nuget-feed.md index eebe7e897..4e8cac899 100644 --- a/troubleshooting/nuget-feed.md +++ b/troubleshooting/nuget-feed.md @@ -64,14 +64,14 @@ If you suspect that your saved credentials are wrong, use the following steps to * No provided credentials * Incorrect password * [Correct password with unescaped special characters](#special-characters-in-the-password) -* Using an invalidated (removed) [Telerik NuGet API key](slug:installation/nuget#use-nuget-api-key), which no longer exists in your Telerik account. +* Using an invalidated (removed) [Telerik NuGet API key](slug:installation/nuget#use-nuget-api-key), which no longer exists in your Telerik account. * Using a valid Telerik NuGet API key with the wrong username. It must be `api-key`. An easy way to verify your credentials is to [access the Telerik NuGet server directly in the web browser](#tips-for-handling-common-nuget-issues). Then, depending on your setup, check or update your credentials in: * The applicable `NuGet.Config` file. There may be multiple such files on the device. * [Windows Credential Manager](#removing-saved-credentials) -* In a [CI/CD workflow](slug:deployment-nuget#using-net-cli-commands), which [obtains the credentials from a secret](slug:deployment-nuget#storing-nuget-keys). +* In a [CI/CD workflow](slug:deployment-nuget#using-net-cli-commands), which [obtains the credentials from a secret](slug:deployment-nuget#storing-api-keys). ### Special Characters in the Password