Skip to content

Commit 0dc93bd

Browse files
JekataJekata
authored
docs: promote the api keys usage
1 parent ee095a7 commit 0dc93bd

File tree

1 file changed

+51
-71
lines changed

1 file changed

+51
-71
lines changed

‎deployment/nuget-keys.md‎

Lines changed: 51 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -8,105 +8,85 @@ position: 6
88

99
# Restoring NuGet Packages in Your CI Workflow
1010

11-
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.
11+
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.
1212

13-
The Telerik NuGet server allows you to authenticate by using two methods:
13+
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.
1414

15-
* Basic authentication by providing your Telerik user name and password.
16-
* Token-based authentication by providing a NuGet Key.
15+
## Generating API Keys
1716

18-
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.
17+
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.
1918

20-
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.
19+
1. Go to the [API Keys](https://www.telerik.com/account/downloads/api-keys) page in your Telerik account.
20+
1. Click **Generate New Key +**.
21+
1. In the **Key Note** field, add a note that describes the API key.
22+
1. Click **Generate Key**.
23+
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.
24+
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.
2125

22-
## Generating NuGet Keys
26+
## Storing API Keys
2327

24-
1. Go to the [**Manage NuGet Keys**](https://www.telerik.com/account/downloads/nuget-keys) page in your Telerik account.
28+
>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.
2529
26-
![Manage NuGet Keys](../deployment/images/manage-nuget-keys.png)
30+
To protect the API key, store it as a secret environment variable. The exact store steps depend on your workflow and environment:
2731

28-
1. To create a new key, select the **Generate New Key** button.
32+
* In GitHub Actions, save the key as a [GitHub Actions Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
33+
* 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.
34+
* In Docker images, save the key as a [Docker secret](https://docs.docker.com/tags/secrets/).
2935

30-
1. Enter a name for the NuGet Key, and then select **Generate Key**.
36+
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.
3137

32-
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.
38+
The examples below assume that the secret environment variable name is `TELERIK_NUGET_KEY`.
3339

34-
![Copy Generated NuGet Key](../deployment/images/copy-nuget-key.png)
3540

36-
## Storing a NuGet Key
41+
## Using API Keys
3742

38-
> 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.
43+
There are two common ways to use a [stored API key](#storing-api-keys) with the Telerik NuGet server during a build:
3944

40-
To protect the NuGet Key, store it as a secret environment variable. The exact steps depend on your workflow:
45+
* [Use a NuGet.Config file](#using-a-nuget-config-file)
46+
* [Use only CLI commands](#using-net-cli-commands)
4147

42-
* In GitHub Actions, save the key as a GitHub Actions Secret. Go to **Settings** > **Security** > **Secrets** > **Actions** > **Add new secret**.
48+
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.
4349

44-
* In Azure DevOps Classic, save the key as a secret pipeline variable. Go to the **Variables** tab and then select **Pipeline variables**.
50+
### Using a NuGet.Config File
4551

46-
* 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.
52+
In your `NuGet.Config` file, set the `Username` value to `api-key` and the `ClearTextPassword` value to an environment variable name:
4753

48-
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.
54+
<div class="skip-repl"></div>
4955

50-
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.
56+
````XML
57+
<?xml version="1.0" encoding="utf-8" ?>
58+
<configuration>
59+
<packageSources>
60+
<clear />
61+
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
62+
<add key="TelerikOnlineFeed" value="https://nuget.telerik.com/v3/index.json" protocolVersion="3" />
63+
</packageSources>
64+
<packageSourceCredentials>
65+
<TelerikOnlineFeed>
66+
<add key="Username" value="api-key" />
67+
<add key="ClearTextPassword" value="%TELERIK_NUGET_KEY%" />
68+
</TelerikOnlineFeed>
69+
</packageSourceCredentials>
70+
</configuration>
71+
````
5172

52-
## Using a NuGet Key
73+
### Using .NET CLI Commands
5374

54-
There are two popular ways to use the Telerik NuGet server in a build:
55-
56-
* [Using a nuget.config file with your projects](#using-a-nugetconfig-file-with-your-projects)
57-
58-
* [Using only CLI commands](#using-only-cli-commands)
59-
60-
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.
61-
62-
### Using a nuget.config File with Your Projects
63-
64-
1. In your `nuget.config` file, set the `Username` value to `api-key` and the `ClearTextPassword` value to an environment variable name:
65-
66-
```xml
67-
<configuration>
68-
<packageSources>
69-
<clear/>
70-
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
71-
<add key="MyTelerikFeed" value="https://nuget.telerik.com/v3/index.json" protocolVersion="3"/>
72-
</packageSources>
73-
<packageSourceCredentials>
74-
<MyTelerikFeed>
75-
<add key="Username" value="api-key" />
76-
<add key="ClearTextPassword" value="%MY_API_KEY%" />
77-
</MyTelerikFeed>
78-
</packageSourceCredentials>
79-
...
80-
</configuration>
81-
```
82-
83-
1. Set the `MY_API_KEY` environment variable by using the value of your pipeline/workflow secret.
84-
85-
The exact steps to set the `MY_API_KEY` environment variable depend on your workflow. For more details, refer to the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy.
86-
87-
### Using Only CLI Commands
88-
89-
You can use the CLI `add source` (or `update source`) command to set the credentials of a package source. This CLI approach is applicable if your CI system doesn't support default environment variable secrets or if you do not use a custom `nuget.config`.
75+
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).
9076

9177
* To set the credentials in Azure DevOps:
9278

93-
```
94-
dotnet nuget add source 'MyTelerikFeed' --source 'https://nuget.telerik.com/v3/index.json' --username 'api-key' --password '$(TELERIK_NUGET_KEY)' --configfile './nuget.config' --store-password-in-clear-text
95-
```
79+
````SH.skip-repl
80+
dotnet nuget add source 'https://nuget.telerik.com/v3/index.json' --name 'TelerikOnlineFeed' --username 'api-key' --password '$(TELERIK_NUGET_KEY)' --configfile './NuGet.Config' --store-password-in-clear-text
81+
````
9682
9783
* To set the credentials in GitHub Actions:
9884
99-
```
100-
dotnet nuget add source 'MyTelerikFeed' --source 'https://nuget.telerik.com/v3/index.json' --username 'api-key' --password '${{ secrets.TELERIK_NUGET_KEY }}' --configfile './nuget.config' --store-password-in-clear-text
101-
```
102-
103-
## Additional Resources
104-
105-
If you just start using the Telerik NuGet server in your CI or inter-department workflows, check the two blog posts below. You will learn about the various use cases and find practical implementation details.
106-
107-
* [Azure DevOps and Telerik NuGet Packages](https://www.telerik.com/blogs/azure-devops-and-telerik-nuget-packages)
85+
````SH.skip-repl
86+
dotnet nuget add source 'https://nuget.telerik.com/v3/index.json' --name 'TelerikOnlineFeed' --username 'api-key' --password '${{ "{{secrets.TELERIK_NUGET_KEY}}" }}' --configfile './NuGet.Config' --store-password-in-clear-text
87+
````
10888
109-
* [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys)
89+
> When restoring NuGet packages through the CLI, [use `dotnet restore` rather than `nuget restore` to avoid compatibility errors](slug:common-kb-package-telerik-pivot-not-compatible-with-netframework).
11090
11191
## See Also
11292

0 commit comments

Comments
 (0)