Introducing scoped API keys

Update 2/14 (05:00 PM PST): This feature is now live! Login to your nuget account and expand the API Keys section to see the new experience.

Since last year, we have been working on several fronts to advance NuGet as a secure environment for package distribution. This post describes an experience that will allow you to have better control of API keys that you use to push packages. Please note that this experience is currently only available on our staging environment and will be deployed to Nuget.org once we have incorporated your feedback, as described below.

Feature summary

This feature will give you better control on your APIs as you can now:

We would love for you to try this feature and give us feedback!

Go to https://int.nugettest.org to try the feature. Since this is a staging environment, you might have to create a new account and push new packages to try out the feature. Also, to set API key and then to push packages, you have to use -Source option as specified below:

nuget.exe setApiKey [your API key] -Source https://int.nugettest.org/api/v2/package
nuget.exe push MyPackage.1.0.nupkg -Source https://int.nugettest.org/api/v2/package

Share your feedback with us via comments in the blog, filing a Github issue or sending an email to our team.

Why introduce the concept of scoped API keys?

We made some changes to API keys last year. We want to further that experience with the introduction of the concept of scopes for API keys that will allow you to have more fine-grained permissions. Today, NuGet offers a single API key for an account, and that approach has several drawbacks:

  • One API key to control all packages: With a single API key that is used to manage all packages, it becomes really difficult to securely share the key when multiple developers are involved with different packages, and share a publisher account. An example of an account where we see a lot of pain on this front is our own Microsoft account that we use to push hundreds of packages across many teams.
  • All permissions or none: Anyone with access to the API key has all permissions (publish, push and un-list) on the packages. This is often not desirable in a multiple developer/team environment.
  • Single point of failure: A single API key also means a single point of failure. If the key is compromised, all packages associated with the account could potentially be compromised. Refreshing the API key is the only way to plug the leak which results in an interruption to your CI/CD workflow. In addition, there may be cases when you want to revoke access to the API key for an individual (for example, when an employee leaves the organization). There isn’t a clean way to handle this today.

With scoped API keys, we have tried to address the problems stated above and at the same time, we have made sure that none of the existing workflows will break.

Create scoped API keys

You can now create multiple API keys based on your requirements. An API key can apply to one or more packages, have varying scopes that grant specific privileges, and have an expiration date associated with it.

overview

In the screenshot above, you can have an API key named ‘Contoso service CI’ that can be used to push packages for certain ‘Contoso.Service’ packages, and is valid for 365 days. This is a typical scenario where different teams within the same organization work on different packages and the members of the team are provided the key which grants them privileges only on the package they are working on. The expiration serves as a mechanism to prevent stale or forgotten keys.

Using glob patterns

If you are working on multiple packages and have a large list of packages to manage, you may choose to use globbing patterns to select multiple packages together. For example, if you wish to grant some key certain scopes on all packages whose ID starts with Fabrikam.Service, you could do so by specifying “fabrikam.service.*” in the Glob pattern text box.

Glob patterns

Using glob patterns to determine API key permissions will also apply to new packages matching the glob pattern. For example, if you try to push a new package named ‘Fabrikam.Service.Framework’, you can do so with the key you would have created in the above step, since the package matches the glob pattern “fabrikam.service*”

Obtain API keys securely

For security, a newly created key is never shown on the screen and is only available with the copy button. Similarly, it will not be accessible again after the page is refreshed.

Obtain API keys

Edit existing API keys

Another use case is being able to update the key permissions and scopes without changing the key itself. If you have a key with specific scope(s) for a single package, you may choose to apply the same scope(s) on one or many other packages.

Edit API keys

Refresh or delete existing API keys

The account owner can choose to refresh the key, in which case the permission (on packages), scope and expiry remain the same but a new key is issued making the old key unusable. This is helpful in dealing with stale keys or where there is any potential of an API key leakage.

Refresh API keys

You can also choose to delete these keys if they are not needed anymore. Deletion will remove the key and make it unusable.

FAQs

What happens to my old (legacy) API key?

Your old API key (legacy) continues to work and can work as long as you want it to work. However, as was the case before, these keys will be retired if they have not been used for more than 365 days to push a package. Refer to the blog post changes expiring to API keys for more details. You can no longer refresh this key. You need to delete the legacy key and create a new scoped key, instead.

Note: This key has all permissions on all the packages and it never expires. You should consider deleting this key and creating new keys with scoped permissions and definite expiry.

How many API keys can I create?

There is no limit on the number of API keys you can create. However, we advise you to keep it to a manageable count so that you do not end up having many stale keys with no knowledge of where and who is using them.

Can I delete my legacy API key or discontinue using now?

Yes. You can, and you probably should. We recommend you delete the legacy API key and start using the new key(s) as soon as we move this feature into our production service (this feature is currently only present in our staging environment).

Can I get back my API key that I deleted by mistake?

No. Once deleted, you can only create new keys. There is no recovery possible for accidently deleted keys.

Does the old API key continue to work upon API key refresh?

No. Once you refresh a key, a new key gets generated that has the same scope, permission and expiry as the old one. The old key ceases to exist.

Can I give more permissions to an existing API key?

You cannot modify the scope but you can edit the package list it is applicable to.

How do I know if any of my keys expired or getting expired?

If any key expires, we will let you know through a warning message at the top of the page. We also send a warning e-mail to the account holder 10 days before the expiration of the key so that you can act on it well in advance.

Expired keys

Next steps

We would love to hear your feedback. Keep them flowing via comments in the blog, filing a Github issue or by sending an email to our team. Once we address the feedback, we would like to go live with this feature - preferably in a couple of weeks from today.

Published February 02, 2017 by Anand Gaurav

NuGet - Ending Windows XP support

At NuGet, we are constantly improving our security. One of the steps we are taking is to move our HTTPS end points to meet industry standards for algorithms and protocols. This means that connecting to nuget.org services from machines that don’t support modern cipher algorithms will no longer be supported (such as TLS 1.0 support in Windows XP). Windows XP reached end of OS support on April 8, 2014, and does not meet this minimum requirement. Therefore, we plan to end NuGet support for Windows XP on April 8, 2017.

After support is discontinued, you will no longer be able to connect to nuget.org services from any Windows XP machines. Examples of scenarios that will no longer work include browsing the nuget.org web site, pushing packages using Nuget.exe or using the NuGet package manager inside Visual Studio. To continue using nuget.org services, you need to move to an OS that supports more modern cipher algorithms (such as Windows 10).

We want to hear your feedback!

We want NuGet to meet the evolving needs of our community. If you would like to share your pain points, and your current or future needs, hit us up at feedback@nuget.org. You can also leave a comment below, and as always, if you run into any issues or have an idea, open an issue on GitHub.

Published January 19, 2017 by Karan Nandwani

Improving the NuGet documentation experience on docs.microsoft.com

In late 2016, we started on the journey of improving the docs experience for NuGet with the revamped docs experience. Continuing that journey, today we are announcing the move to docs.microsoft.com/nuget. Given how NuGet has grown to become an integral part of the Visual Studio and .NET ecosystems, this move furthers the integration by providing a seamless experience to navigate documentation across .NET, Visual Studio and NuGet.

This move also brings several improvements such as:

  • Responsive design supporting multiple form-factors such as mobile devices, tablets, and PCs.
  • Adding side-notes for articles
  • Adding comments as well as subscribing to them
  • Viewing estimated reading time and understanding the freshness of the content

Will my existing references to documentation break?

Existing references should continue to work. We have updated the old docs with permanent redirects which will redirect you to the new page. If you find a broken reference, please open an issue on our GitHub repo and we’ll work to get it fixed.

How can I contribute?

Every page that allows contribution has an “Edit” button at the top right which navigates to the md file. Feel free to make changes and submit a PR from your branch. The NuGet team will review the changes and work with you to get it merged.

If you would like to raise a request for new docs or changes to existing docs, feel free to open a new issue.

We want to hear your feedback!

We want NuGet to meet the evolving needs of our community. If you would like to share your pain points, and your current or future needs, hit us up at feedback@nuget.org. You can also leave a comment below, and as always, if you run into any issues or have an idea, open an issue on GitHub.

Published January 12, 2017 by Karan Nandwani

Older Posts

December 21, 2016 NuGet.Server 2.11.3 now available
November 21, 2016 Announcing NuGet 4.0 RC
October 27, 2016 Announcing NuGet 3.5 RTM
September 20, 2016 New experience for NuGet Documentation
August 25, 2016 Changes to Expiring API Keys
August 22, 2016 The path towards better documentation
August 11, 2016 Announcing NuGet 3.5 RC
June 27, 2016 Announcing NuGet 3.5 Beta 2 and 2.12 RTM
June 22, 2016 NuGet API key expiration
May 19, 2016 Consolidated REST API deployed