diff --git a/getting-started/Installation/generating-api-keys.md b/getting-started/Installation/generating-api-keys.md new file mode 100644 index 00000000..14a0f9b5 --- /dev/null +++ b/getting-started/Installation/generating-api-keys.md @@ -0,0 +1,42 @@ +--- +title: Generating API Keys +page_title: Generating API Keys +description: Learn how to use API Keys to authenticate with the Telerik NuGet server and restore Telerik Document Processing packages in your CI or desktop environment. +slug: generating-api-keys +tags: telerik, document, processing, restore, nuget, packages, ci, continuous, integration, installation, api, key +published: True +position: 9 +--- + +# Generating API Keys + +Using API Keys provides a secure way to authenticate. This method does not require you to provide your Telerik credentials anywhere. Unlike your Telerik credentials, 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. + +1. Go to the [API Keys](https://www.telerik.com/account/downloads/api-keys) page in your Telerik account. + +1. Click **Generate New Key +**. + + ![Generate API key](images/generate-api-key.png) + +1. In the **Key Note** field, add a note that describes the API key. + +1. Click `Generate Key`. + + ![Generate API key](images/generate-key-button.png) + +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. + + ![Copy and Close API key](images/generated-api-key-copy-close.png) + + >note The illustrated API key above is used just for demonstration purposes and it is not valid! + + ![Generated API key](images/generatee-api-key.png) + + >important The validity of the API key is 2 years. + +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. + +## See Also + +* [Restoring NuGet Packages in Your CI Workflow]({%slug using-nuget-keys%}) +* [Install using NuGet Packages]({%slug installation-nuget-packages%}) \ No newline at end of file diff --git a/getting-started/Installation/images/generate-api-key.png b/getting-started/Installation/images/generate-api-key.png new file mode 100644 index 00000000..fefcb413 Binary files /dev/null and b/getting-started/Installation/images/generate-api-key.png differ diff --git a/getting-started/Installation/images/generate-key-button.png b/getting-started/Installation/images/generate-key-button.png new file mode 100644 index 00000000..1d086b0b Binary files /dev/null and b/getting-started/Installation/images/generate-key-button.png differ diff --git a/getting-started/Installation/images/generated-api-key-copy-close.png b/getting-started/Installation/images/generated-api-key-copy-close.png new file mode 100644 index 00000000..a089b077 Binary files /dev/null and b/getting-started/Installation/images/generated-api-key-copy-close.png differ diff --git a/getting-started/Installation/images/generatee-api-key.png b/getting-started/Installation/images/generatee-api-key.png new file mode 100644 index 00000000..e2ef60df Binary files /dev/null and b/getting-started/Installation/images/generatee-api-key.png differ diff --git a/getting-started/Installation/images/installation-nuget-packages003.png b/getting-started/Installation/images/installation-nuget-packages003.png index 411e86fa..d4392125 100644 Binary files a/getting-started/Installation/images/installation-nuget-packages003.png and b/getting-started/Installation/images/installation-nuget-packages003.png differ diff --git a/getting-started/Installation/install-nuget-packages.md b/getting-started/Installation/install-nuget-packages.md index 5a01040a..1e6826fe 100644 --- a/getting-started/Installation/install-nuget-packages.md +++ b/getting-started/Installation/install-nuget-packages.md @@ -49,7 +49,25 @@ This approach allows you to setup a local NuGet package source, so you can insta ## Download from the NuGet server -Before you can install Telerik NuGet packages, you must configure the Telerik NuGet server (https://nuget.telerik.com/v3/index.json) as a package source in Visual Studio: +To install the Telerik Document Processing Libraries, you can use the NuGet packages hosted on the public Telerik NuGet server. This online source lets you download and install various versions of the Document Processing libraries and enables quick updates with minimal manual intervention. + +Before adding the Telerik NuGet server to Visual Studio, make sure you have: + +* A commercial or trial license that includes Document Processing. Note that the Telerik NuGet server requires authentication and checks if you have a valid license. + +* Generate an 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 .NET CLI or the NuGet.Config file. + +### Generate an API Key + +As the Telerik NuGet server requires authentication, the first step is to [obtain an API key]({%slug generating-api-keys%}) 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 .NET CLI or the NuGet.Config file. + +### Add the Telerik NuGet Package Source to Visual Studio + +Before you can install Telerik NuGet packages, you must configure the Telerik NuGet server as a package source in Visual Studio: + +``` +https://nuget.telerik.com/v3/index.json +``` 1\. In the Visual Studio Solution Explorer, right-click a Project, select **Manage NuGet Packages...**, and then select the **Settings** icon: @@ -67,6 +85,22 @@ Before you can install Telerik NuGet packages, you must configure the Telerik Nu ![installation-nuget-packages 004](images/installation-nuget-packages004.png) +You have successfully added the Telerik NuGet feed as a Package source. + +### Reset Store Credentials + +If you previously stored credentials for the Telerik NuGet server, you need to reset them to be able to authenticate with your new API key. Here are the steps you need to follow: + +1. Remove the saved credentials in the [Windows Credential Manager](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0). These credentials will appear as `nuget.telerik.com` or `VSCredentials_nuget.telerik.com` entries. +2. Remove the Telerik NuGet package source from Visual Studio. +3. If you have added the Telerik package source by using the .NET CLI, try to remove it by running the following commands: + * [`dotnet nuget list source`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-list-source) + * [`dotnet nuget remove source`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-remove-source) +4. Check if you have any credentials stored in `%AppData%\NuGet\Nuget.Config`. If so, remove them. +5. Try to reset the Visual Studio user data by [forcing NuGet to ask for authentication](https://stackoverflow.com/questions/43550797/how-to-force-nuget-to-ask-for-authentication-when-connecting-to-a-private-feed). +6. Restart Visual Studio. +7. Add the Telerik NuGet package source again through Visual Studio or .NET CLI. If you are using the Telerik NuGet feed in a .NET Core application, use a NuGet API key in the NuGet.Config file]({%slug telerik-nuget-source%}#edit-the-nugetconfig-file). + ## See Also * [Restoring NuGet Packages in Your CI Workflow]({%slug using-nuget-keys%}) diff --git a/getting-started/Installation/nuget-keys.md b/getting-started/Installation/nuget-keys.md index fd4a87ae..5dda49be 100644 --- a/getting-started/Installation/nuget-keys.md +++ b/getting-started/Installation/nuget-keys.md @@ -3,64 +3,39 @@ title: Restoring NuGet Packages in CI page_title: Restoring NuGet Packages in CI description: Learn how to use NuGet Keys to authenticate with the Telerik NuGet server and restore Telerik Document Processing packages in your CI or desktop environment. slug: using-nuget-keys -tags: telerik, document, processing, restore, nuget, packages, ci, continuous, integration, installation +tags: telerik, document, processing, restore, nuget, packages, ci, continuous, integration, installation, api, key published: True position: 9 --- # Restoring NuGet Packages in Your CI Workflow -This article provides an overview of the most popular approaches for using token-based authentication to restore Telerik NuGet packages in your CI (Continuous Integration) workflow. +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 allows you to authenticate by using two methods: +When you need to restore the [Telerik NuGet packages]({%slug installation-nuget-packages%}#download-from-the-nuget-server) 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 by providing your Telerik user name and password. -* Token-based authentication by providing a NuGet Key. +## Generating API Keys -When you need to restore Telerik NuGet packages as part of your CI, using NuGet keys is the more secure way to authenticate. This method does not require you to provide your Telerik username and password anywhere in the CI workflow. - -Unlike your Telerik credentials, 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. - -## Generating NuGet Keys - -1. Go to the [**Manage NuGet Keys**](https://www.telerik.com/account/downloads/nuget-keys) page in your Telerik account. - -1. Alternatively, select the **Downloads** tab from your Telerik account and then **NuGet Keys**. - - ![Manage NuGet Keys](images/manage-nuget-keys.png) - - The **NuGet Keys** can be accessed from the **License Keys** section as well: - - ![NuGet Keys from License Keys](images/access-nuget-keys-from-license-keys.png) - - -1. To create a new key, select the **Generate New Key** button. - -1. Enter a name for the NuGet Key, and then select **Generate Key**. - - ![Generate NuGet Key](images/generate-nuget-key.png) - -1. To copy the key, select **Copy and Close**. Once you close the window, 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](images/copy-nuget-key.png) +As the Telerik NuGet server requires authentication, the first step is to [obtain an API key]({%slug generating-api-keys%}) 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 .NET CLI or the NuGet.Config file. ## Storing a NuGet Key -> Never check in a NuGet Key with your source code or leave it publicly visible in plain text, for example, as a raw key value in a `nuget.config` file. A NuGet Key is valuable as bad actors can use it to access the NuGet packages that are licensed under your account. A potential key abuse could lead to a review of the affected account. +> Never check-in NuGet API Keys with your source code or leave it publicly visible in plain text, for example, as a raw key value in a `nuget.config` file. A NuGet API Key is valuable as bad actors can use it to access the NuGet packages that are licensed under your account. A potential key abuse could lead to a review of the affected account. To protect the NuGet Key, store it as a secret environment variable. The exact steps depend on your workflow: -* In GitHub Actions, save the key as a GitHub Actions Secret. Go to **Settings** > **Security** > **Secrets** > **Actions** > **Add new secret**. +* In GitHub Actions, save the key as a [GitHub Actions Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). Go to **Settings** > **Security** > **Secrets** > **Actions** > **Add new secret**. -* In Azure DevOps Classic, save the key as a secret pipeline variable. Go to the **Variables** tab and then select **Pipeline variables**. +* 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 Azure DevOps YAML pipelines, save the key as a secret variable as well. Click the YAML editor's **Variables** button and complete the **New variable** form. -If you use Azure DevOps Service connection instead of secret environment variables, enter `api-key` in the username filed and the NuGet 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 a NuGet Key +## Using a NuGet API Key There are two popular ways to use the Telerik NuGet server in a build: diff --git a/getting-started/Installation/nuget-packages.md b/getting-started/Installation/nuget-packages.md index 65f088cb..b14eb5dc 100644 --- a/getting-started/Installation/nuget-packages.md +++ b/getting-started/Installation/nuget-packages.md @@ -77,11 +77,6 @@ The following list represents the available NuGet packages for the Document Proc * __Telerik.Documents.SpreadsheetStreaming:__ The main package for generating huge spreadsheet files while using minimum resources. * __Telerik.Zip:__ It can be used as a standalone library as well. -## See Also - -- [How to Obtain Telerik Document Processing Libraries for .NET Framework, .NET Standard, {{site.dotnetversions}}]({%slug distribute-telerik-document-processing-libraries-net-versions%}) - - ## See Also * [Restoring NuGet Packages in Your CI Workflow]({%slug using-nuget-keys%}) diff --git a/getting-started/Installation/telerik-nuget-source.md b/getting-started/Installation/telerik-nuget-source.md index 729b78c2..5a5a394d 100644 --- a/getting-started/Installation/telerik-nuget-source.md +++ b/getting-started/Installation/telerik-nuget-source.md @@ -119,8 +119,8 @@ To edit a `NuGet.Config` file and add the Telerik feed, you need to: - - + + @@ -131,7 +131,9 @@ To edit a `NuGet.Config` file and add the Telerik feed, you need to: 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 using-nuget-keys%}) as the password. +* Use `api-key` (**recommended**) as the **username** and your personal [NuGet API Key]({%slug using-nuget-keys%}) as the password. + +>important Using an API key minimizes the risk of exposing client credentials when configuring NuGet access. User credentials grant full access to the user account, while the API key limits access to the NuGet feed only. You can [generate your Telerik NuGet API Key on telerik.com](https://www.telerik.com/account/downloads/nuget-keys). Read more about [Restoring NuGet Packages in Your CI Workflow]({%slug using-nuget-keys%}).