Abonnements in Azure API Management

  • Artikel

GILT FÜR: Alle API Management-Ebenen

In Azure API Management sind Abonnements die übliche Methode für die Erteilung von Zugriff auf APIs, die über eine API Management-Instanz veröffentlicht werden. Dieser Artikel bietet eine Übersicht über das Konzept.

Hinweis

Ein API-Verwaltungsabonnement wird speziell zum Aufrufen von APIs über das API Management unter Verwendung eines Abonnementschlüssels verwendet. Es ist nicht identisch mit einem Azure-Abonnement.

Was sind Abonnements?

Durch die Veröffentlichung von APIs über API Management können Sie den API-Zugriff ganz einfach mithilfe von Abonnementschlüsseln absichern. Entwickler, die die veröffentlichten APIs nutzen möchten, müssen einen gültigen Abonnementschlüssel in HTTP-Anforderungen einschließen, wenn sie diese APIs aufrufen. Ohne gültigen Abonnementschlüssel geschieht mit Aufrufen Folgendes:

  • Sie werden sofort vom API Management-Gateway abgelehnt.
  • Sie werden nicht an die Back-End-Dienste weitergeleitet.

Für den Zugriff auf APIs benötigen Entwickler ein Abonnement und einen Abonnementschlüssel. Ein Abonnement ist ein benannter Container für ein Abonnementschlüsselpaar.

Außerdem:

  • Entwickler können Abonnements ohne notwendige Genehmigung von API-Herausgebern abrufen.
  • API-Herausgeber können Abonnements für API-Nutzer direkt erstellen.

Tipp

API Management unterstützt auch andere Mechanismen zum Schützen des Zugriffs auf APIs, einschließlich der folgenden Beispiele:

Abonnementschlüssel verwalten

Das regelmäßige Neugenerieren von Schlüsseln ist eine gängige Sicherheitsvorkehrung. Wie die meisten Azure-Dienste, die einen Abonnementschlüssel erfordern, generiert API Management Schlüssel paarweise. Jede Anwendung, die den Dienst verwendet, kann von Schlüssel A zu Schlüssel B wechseln und Schlüssel A mit minimaler Unterbrechung neu generieren und umgekehrt.

Wenn Sie Schlüssel nicht erneut generieren, sondern bestimmte Schlüssel angeben möchten, rufen Sie die Azure API Management-REST-API für das Erstellen oder Aktualisieren von Abonnements auf. Insbesondere müssen im HTTP-Anforderungstext der properties.primaryKey und/oder der properties.secondaryKey angegeben werden.

Hinweis

  • API Management bietet keine integrierten Features zum Verwalten des Lebenszyklus von Abonnementschlüsseln, z. B. das Festlegen von Ablaufdaten oder die automatische Rotation von Schlüsseln. Sie können Workflows entwickeln, um diese Prozesse mithilfe von Tools wie Azure PowerShell oder den Azure SDKs zu automatisieren.
  • Um zeitlich begrenzten Zugriff auf APIs zu erzwingen, können API-Herausgeber Richtlinien mit Abonnementschlüsseln verwenden oder einen Mechanismus, der einen integrierten Ablauf bereitstellt, z. B. tokenbasierte Authentifizierung.

Bereich von Abonnements

Abonnements können verschiedenen Bereichen zugeordnet werden: einem Produkt, allen APIs oder einer bestimmten API.

Abonnements für ein Produkt

Üblicherweise wurden Abonnements in API Management einem einzelnen Produktbereich zugeordnet. Entwickler:

  • Fanden die Liste der Produkte im Entwicklerportal.
  • Sendeten Abonnementanforderungen für die Produkte, die sie verwenden wollten.
  • Verwendeten die Schlüssel in diesen Abonnements (entweder automatisch oder von API-Herausgebern genehmigt), um auf alle APIs im Produkt zuzugreifen.

Derzeit zeigt das Entwicklerportal nur die Abonnements auf Produktebene im Abschnitt Benutzerprofil an.

Produktabonnements

Abonnements für alle APIs oder eine einzelne API

Sie können auch Schlüssel erstellen, die Zugriff auf Folgendes gewähren:

  • Einzelne API
  • Alle APIs innerhalb einer API Management-Instanz

In diesen Fällen müssen Sie kein Produkt erstellen und ihm zuerst APIs hinzufügen.

All-Access-Abonnement

Jede API Management-Instanz verfügt über ein integriertes Abonnement mit uneingeschränktem Zugriff, das den Zugriff auf alle APIs ermöglicht. Dieses Abonnement für Dienste macht es für die Eigentümer von Diensten einfach, APIs innerhalb der Testkonsole zu testen und zu debuggen.

Warnung

Das All-Access-Abonnement ermöglicht den Zugriff auf jede API in der API Management-Instanz und sollte nur von autorisierten Benutzern verwendet werden. Verwenden Sie dieses Abonnement nie für den routinemäßigen API-Zugriff, und betten Sie den All-Access-Abonnementschlüssel nie in Client-Apps ein.

Hinweis

Wenn Sie ein API-bezogenes Abonnement, ein All-APIs-Abonnement oder das integrierte All-Access-Abonnement verwenden, werden Richtlinien, die im Produktbereich konfiguriert sind, nicht auf Anforderungen dieses Abonnements angewendet.

Eigenständige Abonnements

API Management ermöglicht auch eigenständige Abonnements, die nicht mit einem Entwicklerkonto verknüpft sind. Dieses Feature ist nützlich in Szenarien, in denen mehrere Entwickler oder Teams ein Abonnement gemeinsam nutzen.

Wenn Sie ein Abonnement erstellen, ohne einen Besitzer zuzuweisen, wird es zu einem eigenständigen Abonnement. Um Entwicklern und dem Rest Ihres Teams Zugriff auf den eigenständigen Abonnementschlüssel zu gewähren, führen Sie einen der folgenden Schritte aus:

  • Teilen Sie den Abonnementschlüssel manuell.
  • Verwenden Sie ein benutzerdefiniertes System, um den Abonnementschlüssel für Ihr Team verfügbar zu machen.

Erstellen und Verwalten von Abonnements im Azure-Portal

Für API-Herausgeber ist die Erstellung von Abonnements direkt im Azure-Portal möglich.

Bei der Erstellung im Portal befindet sich ein Abonnement im Status Aktiv, d. h., ein*e Abonnent*in kann eine zugeordnete API mit einem gültigen Abonnementschlüssel aufrufen. Sie können den Status des Abonnements nach Bedarf ändern. Sie können zum Beispiel jedes Abonnement (einschließlich des integrierten Abonnements mit uneingeschränktem Zugriff) aussetzen, kündigen oder löschen, um den API-Zugriff zu verhindern.

Verwenden eines Abonnementschlüssels

Ein Abonnent kann einen API Management Abonnementschlüssel auf zwei Arten verwenden:

  • Fügen Sie der Anforderung den HTTP-Header Ocp-Apim-Subscription-Key hinzu, und übergeben Sie dabei den Wert eines gültigen Abonnementschlüssels.

  • Schließen Sie den Abfrageparameter subscription-key und einen gültigen Wert in die URL ein. Der Abfrageparameter wird nur überprüft, wenn der Header nicht vorhanden ist.

Tipp

Ocp-Apim-Subscription-Key ist der Standardname des Abonnementschlüssel-Headers, und subscription-key ist der Standardname des Abfrageparameters. Bei Bedarf können Sie diese Namen in den Einstellungen für jede API ändern. Aktualisieren Sie beispielsweise im Portal diese Namen auf der Registerkarte Einstellungen einer API.

Hinweis

Wenn er in einen Anforderungsheader oder Abfrageparameter eingeschlossen ist, wird der Abonnementschlüssel standardmäßig an das Back-End übergeben und kann in Back-End-Überwachungsprotokollen oder anderen Systemen verfügbar gemacht werden. Wenn dies vertrauliche Daten sind, können Sie am Ende von Abschnitt inbound eine Richtlinie konfigurieren, um den Abonnementschlüsselheader (set-header) oder den Abfrageparameter (set-query-parameter) zu entfernen.

Aktivieren oder Deaktivieren der Abonnementanforderung für den API- oder Produktzugriff

Wenn Sie eine API erstellen, ist für den API-Zugriff standardmäßig ein Abonnementschlüssel erforderlich. Ebenso ist beim Erstellen eines Produkts standardmäßig ein Abonnementschlüssel erforderlich, um auf APIs zuzugreifen, die dem Produkt hinzugefügt werden. In bestimmten Szenarien möchten API-Herausgeber vielleicht ein Produkt oder eine bestimmte API veröffentlichen, ohne dass hierzu Abonnements erforderlich sind. Ein Herausgeber kann zwar den ungeschützten (anonymen) Zugriff auf bestimmte APIs aktivieren, es wird jedoch empfohlen, einen anderen Mechanismus zum Schützen des Clientzugriffs zu konfigurieren.

Achtung

Gehen Sie beim Konfigurieren eines Produkts oder einer API, das/die kein Abonnement erfordert, sorgfältig vor. Diese Konfiguration kann übermäßig freizügig sein und eine API anfälliger für bestimmte API-Sicherheitsbedrohungen machen.

Hinweis

Offene Produkte haben die Einstellung Abonnement erforderlich deaktiviert, was bedeutet, dass Benutzer sie nicht abonnieren müssen. Aus diesem Grund werden geöffnete Produkte nicht auf der Seite Produkte des Entwicklerportals angezeigt.

Sie können die Abonnementanforderung zum Zeitpunkt der Erstellung einer API oder eines Produkts oder zu einem späteren Zeitpunkt deaktivieren.

So deaktivieren Sie die Abonnementanforderung über das Portal:

  • Deaktivieren der Anforderung für ein Produkt: Deaktivieren Sie auf der Seite Einstellungen des Produkts die Option Abonnement erforderlich.
  • Deaktivieren der Anforderung für eine API: Deaktivieren Sie auf der Seite Einstellungen der API die Option Abonnement erforderlich.

Nach dem Deaktivieren der Abonnementanforderung kann ohne Abonnementschlüssel auf die ausgewählte API oder die ausgewählten APIs zugegriffen werden.

Verarbeitung von Anforderungen mit oder ohne Abonnementschlüssel durch API Management

API-Anforderung mit einem Abonnementschlüssel

Wenn API Management eine API-Anforderung von einem Client mit einem Abonnementschlüssel empfängt, wird die Anforderung gemäß den folgenden Regeln verarbeitet:

  1. Zuerst wird überprüft, ob es sich um einen gültigen Schlüssel handelt, der einem aktiven Abonnement zugeordnet ist:

    • Ein Abonnement, das auf die API ausgerichtet ist
    • Ein Abonnement, das auf ein Produkt ausgerichtet ist, das der API zugewiesen ist
    • Ein Abonnement, das auf alle APIs ausgerichtet ist
    • Das Abonnement im Dienstbereich (integriertes Abonnement für den gesamten Zugriff)

    Wenn ein gültiger Schlüssel für ein aktives Abonnement in einem geeigneten Bereich bereitgestellt wird, ist der Zugriff zulässig. Richtlinien werden abhängig von der Konfiguration der Richtliniendefinition in diesem Bereich angewandt.

  2. Wenn der Schlüssel nicht gültig ist, aber ein Produkt vorhanden ist, das die API enthält und kein Abonnement erfordert (ein offenes Produkt), den Schlüssel ignorieren und verfahren wie bei einer API-Anforderung ohne Abonnementschlüssel (siehe unten).

  3. Andernfalls wird der Zugriff verweigert (Fehler 401 – Zugriff verweigert).

API-Anforderung ohne Abonnementschlüssel

Wenn API Management eine API-Anforderung von einem Client ohne Abonnementschlüssel empfängt, wird die Anforderung gemäß den folgenden Regeln verarbeitet:

  1. Zunächst überprüfen, ob ein Produkt existiert, das die API enthält, aber kein Abonnement erfordert (ein offenes Produkt). Wenn das offene Produkt vorhanden ist, die Anforderung im Kontext der für das offene Produkt konfigurierten APIs, Richtlinien und Zugriffsregeln verarbeiten. Eine API kann höchstens einem offenen Produkt zugeordnet werden.
  2. Wenn kein offenes Produkt mit der API gefunden wird, überprüfen, ob die API ein Abonnement erfordert. Wenn ein Abonnement nicht erforderlich ist, die Anforderung im Kontext dieser API und des Vorgangs verarbeiten.
  3. Wenn kein konfiguriertes Produkt oder keine konfigurierte API gefunden wurde, wird der Zugriff verweigert (Fehler 401 – Verweigert).

Zusammenfassungstabelle

In der folgenden Tabelle wird zusammengefasst, wie das Gateway API-Anforderungen mit oder ohne Abonnementschlüssel in verschiedenen Szenarien verarbeitet. Konfigurationen, die möglicherweise unbeabsichtigten, anonymen API-Zugriff ermöglichen, werden gekennzeichnet.

Alle Produkte, die der API zugewiesen sind, erfordern ein Abonnement. API erfordert ein Abonnement. API-Aufruf mit Abonnementschlüssel API-Aufruf ohne Abonnementschlüssel Typische Szenarien
✔️ ✔️ Zugriff zulässig:

• Produktbezogener Schlüssel
• API-bezogener Schlüssel
• Schlüssel für alle APIs
• Dienstbezogener Schlüssel

Zugriff verweigert:

• Anderer Schlüssel, der nicht auf das jeweilige Produkt oder die API ausgerichtet ist		 Zugriff verweigert. Geschützter API-Zugriff mithilfe eines Abonnements im Produkt- oder API-Bereich
✔️ ❌ Zugriff zulässig:

• Produktbezogener Schlüssel
• API-bezogener Schlüssel
• Schlüssel für alle APIs
• Dienstbezogener Schlüssel
• Anderer Schlüssel, der nicht auf das jeweilige Produkt oder die API ausgerichtet ist		 Zugriff zulässig (API-Kontext) • Geschützter API-Zugriff mithilfe eines Abonnements im Produktbereich

• Anonymer Zugriff auf die API. Wenn der anonyme Zugriff nicht vorgesehen ist, konfigurieren Sie Richtlinien auf API-Ebene, um die Authentifizierung und Autorisierung zu erzwingen.
❌1 ✔️ Zugriff zulässig:

• Produktbezogener Schlüssel
• API-bezogener Schlüssel
• Schlüssel für alle APIs
• Dienstbezogener Schlüssel

Zugriff verweigert:

• Anderer Schlüssel, der nicht auf das jeweilige Produkt oder die API ausgerichtet ist		 Zugriff zulässig (offener Produktkontext) • Geschützter API-Zugriff mithilfe eines Abonnements im API-Bereich

• Anonymer Zugriff auf die API. Wenn der anonyme Zugriff nicht vorgesehen ist, konfigurieren Sie Produktrichtlinien, um die Authentifizierung und Autorisierung zu erzwingen.
❌1 ❌ Zugriff zulässig:

• Produktbezogener Schlüssel
• API-bezogener Schlüssel
• Schlüssel für alle APIs
• Dienstbezogener Schlüssel
• Anderer Schlüssel, der nicht auf das jeweilige Produkt oder die API ausgerichtet ist		 Zugriff zulässig (offener Produktkontext) Anonymer Zugriff auf die API. Wenn der anonyme Zugriff nicht vorgesehen ist, konfigurieren Sie Produktrichtlinien, um die Authentifizierung und Autorisierung zu erzwingen.

1 Es ist ein offenes Produkt vorhanden, das der API zugeordnet ist.

Weitere Überlegungen

  • Der API-Zugriff in einem Produktkontext ist identisch, unabhängig davon, ob das Produkt veröffentlicht wurde. Durch das Aufheben der Veröffentlichung des Produkts wird es im Entwicklerportal ausgeblendet, neue oder vorhandene Abonnementschlüssel werden jedoch nicht ungültig.
  • Wenn eine API keine Abonnementauthentifizierung erfordert, wird jede API-Anforderung, die einen Abonnementschlüssel enthält, genauso behandelt wie eine Anforderung ohne Abonnementschlüssel. Der Abonnementschlüssel wird ignoriert.
  • API-Zugriff in einem „Kontext“ bezeichnet die Richtlinien und Zugriffssteuerungen, die in einem bestimmten Bereich (z. B. API oder Produkt) angewandt werden.

Nächste Schritte

Weitere Informationen zu API Management:

  • Informationen dazu, wie API Management-Richtlinien in verschiedenen Bereichen angewendet werden
  • Informationen zu weiteren Konzepten in API Management
  • Tutorials zum weiteren Kennenlernen von API Management
  • FAQ-Seite für häufig gestellte Fragen