Bereichsbezogene API-SchlüsselScoped API keys

Sie können API-Schlüssel anhand von Bereichen einschränken, um NuGet eine sicherere Umgebung zur Verteilung von Paketen zu machen.To make NuGet a more secure environment for package distribution, you can take control of the API keys by adding scopes.

Wenn Sie Bereiche für Ihre API-Schlüssel festlegen können, können Sie Ihre APIs besser kontrollieren.The ability to provide scope to your API keys give you better control on your APIs. Sie haben folgende Möglichkeiten:You can:

  • Sie können API-Schlüssel mit mehreren Bereichen erstellen, die für unterschiedliche Pakete mit verschiedenen Ablauffristen erstellt werden können.Create multiple scoped API keys that can be used for different packages with varying expiration timeframes.
  • Sie können API-Schlüssel sicher erhalten.Obtain API keys securely.
  • Sie können vorhandene API-Schlüssel bearbeiten, um die Anwendbarkeit des Pakets anzupassen.Edit existing API keys to change package applicability.
  • Sie können vorhandene API-Schlüssel aktualisieren oder löschen, ohne Vorgänge mit anderen Schlüsseln zu beeinträchtigen.Refresh or delete existing API keys without hampering operations using other keys.

Warum werden bereichsbezogene API-Schlüssel unterstützt?Why do we support scoped API keys?

Bereiche für API-Schlüssel werden unterstützt, damit Sie genauere Berechtigungen festlegen können.We support scopes for API keys to allow you to have more fine-grained permissions. In der Vergangenheit hat NuGet einen API-Schlüssel für ein Konto zugelassen. Dieser Ansatz hatte mehrere Nachteile:Previously, NuGet offered a single API key for an account, and that approach had several drawbacks:

  • Ein API-Schlüssel für alle Pakete:One API key to control all packages. Mit einem API-Schlüssel zum Verwalten aller Pakete ist es schwer, den Schlüssel sicher zu teilen, wenn mehrere Entwickler mit verschiedenen Paketen involviert sind und ein Herausgeberkonto gemeinsam verwenden.With a single API key that is used to manage all packages, it is difficult to securely share the key when multiple developers are involved with different packages, and when they share a publisher account.
  • Entweder alle oder keine Berechtigungen:All permissions or none. Jeder Benutzer mit Zugriffsberechtigungen für den API-Schlüssel hat alle Berechtigungen (Veröffentlichen, Pushen und Aufheben der Auflistung).Anyone with access to the API key has all permissions (publish, push and un-list) on the packages. Das ist in Umgebungen mit mehreren Teams oft unerwünscht.This is often not desirable in environment with multiple teams.
  • Single Point of Failure:Single point of failure. Ein einziger API-Schlüssel bedeutet auch ein Single Point of Failure.A single API key also means a single point of failure. Wenn der Schlüssel kompromittiert wird, sind auch alle Pakete, die mit dem Konto verknüpft sind, potenziell kompromittiert.If the key is compromised, all packages associated with the account could potentially be compromised. Diese Bedrohung kann nur durch eine Änderung des API-Schlüssels behoben werden. Zudem kann nur so eine Unterbrechung Ihres CI/CD-Workflows vermieden werden.Refreshing the API key is the only way to plug the leak and avoid an interruption to your CI/CD workflow. Darüber hinaus kann es Fälle geben, in denen Sie den Zugriff auf den API-Schlüssel für eine Einzelperson widerrufen möchten (wenn z. B. ein Angestellter die Organisation verlässt).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). Das kann momentan noch nicht unkompliziert gelöst werden.There isn’t a clean way to handle this today.

Mit bereichsbezogenen API-Schlüsseln möchten wir diese Probleme beheben und gleichzeitig sicherstellen, dass keine der bestehenden Workflows beeinträchtigt werden.With scoped API keys, we try to address these problems while making sure that none of the existing workflows break.

Erhalten eines API-SchlüsselsAcquire an API key

  1. Melden Sie sich bei Ihrem nuget.org-Konto an, oder erstellen Sie ein Konto, wenn Sie noch keines besitzen.Sign into your nuget.org account or create an account if you don't have one already.

    Weitere Informationen zum Erstellen Ihres Kontos finden Sie unter Individuelle Konten.For more information on creating your account, see Individual accounts.

  2. Klicken Sie auf Ihren Benutzernamen (oben rechts) und anschließend auf API Keys (API-Schlüssel).Select your user name (on the upper right), then select API Keys.

  3. Wählen Sie Erstellen, geben Sie einen Namen für den Schlüssel ein, und wählen Sie Bereiche auswählen > Push.Select Create, provide a name for your key, select Select Scopes > Push. Geben Sie für Globmuster ein Sternchen (*) ein, und wählen Sie dann Erstellen aus.Enter * for Glob pattern, then select Create. (Weitere Informationen zu Bereichen finden Sie unten.)(See below for more about scopes.)

  4. Nachdem der Schlüssel erstellt wurde, klicken Sie auf Copy (Kopieren), um den Zugriffsschlüssel abzurufen, den Sie in der CLI benötigen:Once the key is created, select Copy to retrieve the access key you need in the CLI:

    Kopieren des API-Schlüssels in die Zwischenablage

  5. Wichtig: Speichern Sie den Schlüssel an einem sicheren Ort; Sie können den Schlüssel später nicht erneut kopieren.Important: Save your key in a secure location because you cannot copy the key again later on. Wenn Sie auf die Seite „API-Schlüssel“ zurückkehren, müssen Sie den Schlüssel erneut generieren, um ihn zu kopieren.If you return to the API key page, you need to regenerate the key to copy it. Sie können den API-Schlüssel auch entfernen, wenn sie keine Pakete mehr mithilfe von Push über die CLI übertragen möchten.You can also remove the API key if you no longer want to push packages via the CLI.

Mit der Bereichsauswahl können Sie separate API-Schlüssel für verschiedene Zwecke erstellen.Scoping allows you to create separate API keys for different purposes. Jeder Schlüssel hat seinen Ablaufzeitraum und kann auf bestimmte Pakete (oder Globmuster) festgelegt werden.Each key has its expiration timeframe and can be scoped to specific packages (or glob patterns). Jeder Schlüssel ist zudem auf bestimmte Vorgänge begrenzt: Push von neuen Paketen und Updates, Push von ausschließlich Updates oder Entfernen aus Listing.Each key is also scoped to specific operations: push of new packages and updates, push of updates only, or delisting. Durch das Festlegen des Gültigkeitsbereichs können Sie API-Schlüssel für verschiedene Personen erstellen, die Pakete für Ihre Organisation so verwalten, dass sie nur über die erforderlichen Berechtigungen verfügen.Through scoping, you can create API keys for different people who manage packages for your organization such that they have only the permissions they need. Weitere Informationen finden Sie unter bereichsbezogene API-Schlüssel.For more information, see scoped API keys.

Erstellen eines bereichsbezogenen API-SchlüsselsCreate scoped API keys

Sie können mehrere API-Schlüssel basierend auf Ihren Umgebungen erstellen.You can create multiple API keys based on your requirements. Ein API-Schlüssel kann für eines oder mehrere Pakete gelten, mehrere Bereiche mit bestimmten Berechtigungen aufweisen und ein Ablaufdatum haben.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.

Im folgenden Beispiel wird der API-Schlüssel Contoso service CI verwendet, mit dem Pakete für bestimmte Contoso.Service-Pakete gepusht werden können und der 365 Tage gültig ist.In the following example, you have an API key named Contoso service CI that can be used to push packages for specific Contoso.Service packages, and is valid for 365 days. Das ist ein typisches Beispiel, bei dem verschiedene Teams in derselben Organisation an verschiedenen Paketen arbeiten und die Teammitglieder den Schlüssel bereitstellen, durch den sie Berechtigungen für das Paket haben, an dem sie arbeiten.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 that grants them privileges only for the package they are working on. Durch die Ablauffrist werden alte oder vergessene Schlüssel vermieden.The expiration serves as a mechanism to prevent stale or forgotten keys.

Erstellen von API-Schlüsseln

Verwenden von GlobmusternUse glob patterns

Wenn Sie mit mehreren Paketen arbeiten und eine lange Liste mit Paketen verwalten müssen, können sie Globmuster verwenden, um mehrere Pakete auf einmal auszuwählen.If you are working on multiple packages and have a large list of packages to manage, you can choose to use globbing patterns to select multiple packages together. Wenn sie z. B. einem Schlüssel für alle Pakete, deren ID mit Fabrikam.Service beginnt, bestimmte Bereiche zuweisen möchten, können Sie dazu fabrikam.service.* im Textfeld Glob pattern (Globmuster) angeben.For example, if you wish to grant specific scopes to a key for all packages whose ID starts with Fabrikam.Service, you could do this by specifying fabrikam.service.* in the Glob pattern text box.

Erstellen von API-Schlüsseln

Das Verwenden von Globmustern zum Bestimmen von API-Schlüssel-Berechtigungen gilt auch für neue Pakete, die mit dem Globmuster übereinstimmen.Using glob patterns to determine API key permissions also applies to new packages matching the glob pattern. Wenn Sie z. B. versuchen, ein neues Paket mit dem Namen Fabrikam.Service.Framework zu pushen, können Sie dies mit dem vormals erstellten Schlüssel tun, da das Paket mit dem Globmuster fabrikam.service.* übereinstimmt.For example, if you try to push a new package named Fabrikam.Service.Framework, you can do that with the key created previously, since the package matches the glob pattern fabrikam.service.*.

Sicheren Abrufen von API-SchlüsselnObtain API keys securely

Aus Sicherheitsgründen wird ein neu erstellter Schlüssel niemals angezeigt und kann nur über die Schaltfläche Copy (Kopieren) verwendet werden.For security, a newly created key is never shown on the screen and is only available using the Copy button. Gleichfalls können Sie nicht mehr auf den Schlüssel zugreifen, nachdem die Seite aktualisiert wurde.Similarly, the key is not accessible after the page is refreshed.

Erstellen von API-Schlüsseln

Bearbeiten vorhandener API-SchlüsselEdit existing API keys

Sie sollten auch die Schlüsselberechtigungen und Bereiche aktualisieren, ohne den Schlüssel an sich zu ändern.You may also want to update the key permissions and scopes without changing the key itself. Wenn Sie einen Schlüssel mit einem bestimmten Bereich oder bestimmten Bereichen für ein einzelnes Paket haben, können Sie denselben Bereich oder dieselben Bereichen auf eines oder mehrere andere Pakete anwenden.If you have a key with specific scope(s) for a single package, you can choose to apply the same scope(s) on one or many other packages.

Erstellen von API-Schlüsseln

Aktualisieren oder Löschen vorhandener API-SchlüsselRefresh or delete existing API keys

Der Kontobesitzer kann den Schlüssel aktualisieren. In diesem Fall bleiben die Berechtigungen der Pakete, der Bereich und das Ablaufdatum dieselben, aber es wird ein neuer Schlüssel erstellt, sodass der alte nicht mehr verwendet werden kann.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. Das ist beim Verwalten veralteter Schlüssel oder bei einem potenziellen API-Schlüsselverlust nützlich.This is helpful in managing stale keys or where there is any potential for an API key leakage.

Erstellen von API-Schlüsseln

Sie können diese Schlüssel auch löschen, wenn Sie sie nicht mehr benötigen.You may also choose to delete these keys if they are not needed anymore. Wenn Sie den Schlüssel löschen, kann er nicht mehr verwendet werden.Deleting a key removes the key and makes it unusable.

Häufig gestellte Fragen (FAQs)FAQs

Was geschieht mit meinem alten (Legacy-)API-Schlüssel?What happens to my old (legacy) API key?

Ihr alter (Legacy-)API-Schlüssel funktioniert auch weiterhin, solange Sie Ihn benötigen.Your old API key (legacy) continues to work and can work as long as you want it to work. Diese Schlüssel werden entfernt, wenn sie mehr als 365 Tage nicht mehr zum Pushen von Paketen verwendet wurden.However, these keys will be retired if they have not been used for more than 365 days to push a package. Weitere Informationen finden Sie im Blogbeitrag Changes to expiring API keys (Änderungen an ablaufenden API-Schlüsseln).For more details, see the blog post Changes to expiring API keys. Sie können diesen Schlüssel nicht mehr aktualisieren.You can no longer refresh this key. Sie müssen den Legacyschlüssel löschen oder stattdessen einen bereichsbezogenen Schlüssel erstellen.You need to delete the legacy key and create a new scoped key instead.

Hinweis

Dieser Schlüssel hat alle Berechtigungen für alle Pakete, und er läuft nicht ab.This key has all permissions on all the packages and it never expires. Überlegen Sie sich, ob Sie diesen Schlüssel löschen und neue Schlüssel mit bereichsbezogenen Berechtigungen und Ablauffristen erstellen möchten.You should consider deleting this key and creating new keys with scoped permissions and definite expiry.

Wie viele API-Schlüssel kann ich erstellen?How many API keys can I create?

Sie können unendlich viele API-Schlüssel erstellen.There is no limit on the number of API keys you can create. Es wird jedoch empfohlen, es bei einer übersichtlichen Anzahl zu belassen, damit Sie sich nicht um zu viele veraltete Schlüssel kümmern müssen, ohne zu wissen, wo und von wem sie eingesetzt werden.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.

Kann ich meine Legacy-API-Schlüssel löschen oder aufhören, sie zu verwenden?Can I delete my legacy API key or discontinue using now?

Ja.Yes. Sie können – und sollten – ihre Legacy-API-Schlüssel löschen.You can--and you probably should--delete your legacy API key.

Kann ich API-Schlüssel wiederherstellen, die ich versehentlich gelöscht habe?Can I get back my API key that I deleted by mistake?

Nein.No. Wenn Sie einen Schlüssel gelöscht haben, können Sie nur neue Schlüssel erstellen.Once deleted, you can only create new keys. Es gibt keine Wiederherstellungsmöglichkeit für versehentlich gelöschte Schlüssel.There is no recovery possible for accidentally deleted keys.

Funktioniert der alte API-Schlüssel weiterhin, wenn ich den API-Schlüssel aktualisiere?Does the old API key continue to work upon API key refresh?

Nein.No. Wenn Sie einen Schlüssel aktualisieren, wird ein neuer Schlüssel mit demselben Bereich, denselben Berechtigungen und demselben Ablaufdatum wie der alte Schlüssel generiert.Once you refresh a key, a new key gets generated that has the same scope, permission, and expiry as the old one. Der alte Schlüssel existiert nicht mehr.The old key ceases to exist.

Kann ich einem vorhandenen API-Schlüssel mehr Berechtigungen zuweisen?Can I give more permissions to an existing API key?

Sie können den Bereich nicht anpassen, aber Sie können die Paketliste bearbeiten, für die er gilt.You cannot modify the scope, but you can edit the package list it is applicable to.

Wie kann ich bestimmen, ob einer meiner Schlüssel abgelaufen ist oder bald abläuft?How do I know if any of my keys expired or are getting expired?

Wenn ein Schlüssel abläuft, wird eine Warnmeldung am oberen Rand der Seite angezeigt.If any key expires, we will let you know through a warning message at the top of the page. Außerdem erhält der Kontobesitzer zehn Tage vor Ablauf des Schlüssels eine Warnung per E-Mail, sodass er entsprechende Maßnahmen einleiten kann.We also send a warning e-mail to the account holder ten days before the expiration of the key so that you can act on it well in advance.