Verwenden von benannten Werten in Azure API Management-Richtlinien

  • Artikel

GILT FÜR: Alle API Management-Ebenen

API Management-Richtlinien sind eine leistungsfähige Funktion des Systems, mit der Herausgeber das Verhalten der API über eine Konfiguration ändern können. Richtlinien sind eine Sammlung von Anweisungen, die sequenziell bei Anfragen oder Antworten einer API ausgeführt werden. Richtlinienanweisungen können mithilfe von literalen Textwerten, Richtlinienausdrücken und benannten Werten erstellt werden.

Benannte Werte sind eine globale Sammlung von Name-Wert-Paaren in jeder API Management-Instanz. Es gibt keine Beschränkung für die Anzahl der Elemente in der Sammlung. Benannte Werte können zum Verwalten konstanter Zeichenfolgenwerte und Geheimnisse für alle API-Konfigurationen und -Richtlinien verwendet werden.

Benannte Werte im Azure-Portal

Werttypen

type BESCHREIBUNG
Plain Literalzeichenfolge oder Richtlinienausdruck
`Secret` Literalzeichenfolge oder Richtlinienausdruck (durch API Management verschlüsselt)
Key vault Bezeichner eines Geheimnisses, das in Azure Key Vault gespeichert ist.

Plain-Werte oder -Geheimnisse können Richtlinienausdrücke enthalten. Der Ausdruck @(DateTime.Now.ToString()) gibt z. B. eine Zeichenfolge zurück, die das aktuelle Datum und die Uhrzeit enthält.

Ausführliche Informationen zu den Attributen benannter Werte finden Sie in der REST-API-Referenz von API Management.

Key Vault-Geheimnisse

Geheimniswerte können entweder als verschlüsselte Zeichenfolgen in API Management (benutzerdefinierte Geheimnisse) oder durch Verweisen auf Geheimnisse in Azure Key Vault gespeichert werden.

Die Verwendung von Schlüsseltresorgeheimnissen wird empfohlen, da dadurch die Sicherheit von API Management verbessert wird:

  • In Schlüsseltresoren gespeicherte Geheimnisse können für mehrere Dienste verwendet werden.
  • Auf die Geheimnisse können präzise Zugriffsrichtlinien angewandt werden.
  • Wenn Geheimnisse im Schlüsseltresor aktualisiert werden, erfolgt in API Management automatisch eine Schlüsselrotation. Nach der Aktualisierung im Schlüsseltresor wird ein benannter Wert innerhalb von 4 Stunden in API Management aktualisiert. Sie können das Geheimnis auch manuell im Azure-Portal oder über die Verwaltungs-REST-API aktualisieren.

Voraussetzungen

Voraussetzungen für die Key Vault-Integration

Konfigurieren des Zugriffs auf den Schlüsseltresor

  1. Navigieren Sie im Portal zu Ihrem Schlüsseltresor.

  2. Wählen Sie im Menü auf der linken Seite Zugriffskonfiguration aus, und beachten Sie das konfigurierte Berechtigungsmodell.

  3. Konfigurieren Sie je nach Berechtigungsmodell entweder eine Schlüsseltresor-Zugriffsrichtlinie oder den Azure RBAC-Zugriff für eine verwaltete API Management-Identität.

    So fügen Sie eine Schlüsseltresor-Zugriffsrichtlinie hinzu

    1. Wählen Sie im Menü auf der linken Seite Zugriffsrichtlinien aus.
    2. Wählen Sie auf der Seite Zugriffsrichtlinien die Option + Erstellen aus.
    3. Wählen Sie auf der Registerkarte Berechtigungen unter Berechtigungen für Geheimnis die Optionen Abrufen und Auflisten und dann Weiter aus.
    4. Klicken Sie auf der Registerkarte Prinzipal auf Prinzipal auswählen, suchen Sie nach dem Ressourcennamen Ihrer verwalteten Identität, und wählen Sie dann Weiter aus. Wenn Sie eine systemseitig zugewiesene Identität verwenden, ist der Prinzipal der Name der API Management-Instanz.
    5. Wählen Sie erneut Weiter aus. Wählen Sie auf der Registerkarte Überprüfen + erstellen die Option Erstellen aus.

    So konfigurieren Sie Azure RBAC-Zugriff

    1. Wählen Sie im linken Menü Zugriffssteuerung (IAM) aus.
    2. Wählen Sie auf der Seite Zugriffssteuerung (IAM) die Option Rollenzuweisung hinzufügen aus.
    3. Wählen Sie auf der Registerkarte Rolle die Option Key Vault-Geheimnisbenutzer aus.
    4. Wählen Sie auf der Registerkarte Mitglieder die Option Verwaltete Identität>+ Mitglieder auswählen aus.
    5. Wählen Sie auf der Seite Verwaltete Identität auswählen die systemseitig zugewiesene verwaltete Identität oder eine benutzerseitig zugewiesene verwaltete Identität aus, die Ihrer API Management-Instanz zugeordnet ist, und wählen Sie dann Auswählen aus.
    6. Wählen Sie Überprüfen und zuweisen aus.

Anforderungen an Key Vault-Firewall

Wenn die Key Vault-Firewall in Ihrem Schlüsseltresor aktiviert ist, gelten die folgenden zusätzlichen Anforderungen:

  • Sie müssen die systemseitig zugewiesene verwaltete Identität der API Management-Instanz verwenden, um auf den Schlüsseltresor zuzugreifen.

  • Aktivieren Sie in der Key Vault-Firewall die Option Vertrauenswürdigen Microsoft-Diensten die Umgehung dieser Firewall erlauben? .

  • Stellen Sie sicher, dass Ihre lokale Client-IP-Adresse vorübergehend auf den Schlüsseltresor zugreifen darf, während Sie ein Zertifikat oder Geheimnis auswählen, das Sie der Azure API Management-Instanz hinzufügen möchten. Weitere Informationen finden Sie unter Konfigurieren von Azure Key Vault-Netzwerkeinstellungen.

    Nach Abschluss der Konfiguration können Sie Ihre Clientadresse in der Firewall des Schlüsseltresors blockieren.

Anforderungen für virtuelle Netzwerke

Wenn die API Management-Instanz in einem virtuellen Netzwerk bereitgestellt wird, müssen Sie darüber hinaus die folgenden Netzwerkeinstellungen konfigurieren:

  • Aktivieren Sie im API Management-Subnetz einen Dienstendpunkt für Azure Key Vault.
  • Konfigurieren Sie eine Netzwerksicherheitsgruppen-Regel (NSG), um ausgehenden Datenverkehr an die Diensttags AzureKeyVault und AzureActiveDirectory zuzulassen.

Einzelheiten finden Sie unter Netzwerkkonfiguration beim Einrichten von Azure API Management in einem VNet.

Hinzufügen oder Bearbeiten benannter Werte

Hinzufügen eines Schlüsseltresorgeheimnisses zu API Management

Weitere Informationen finden Sie unter Voraussetzungen für die Key Vault-Integration.

Wichtig

Wenn Sie Ihrer API Management-Instanz ein Schlüsseltresorgeheimins hinzufügen, müssen Sie über die Berechtigung verfügen, Geheimnisse aus dem Schlüsseltresor aufzulisten.

Achtung

Wenn Sie in API Management ein Geheimnis aus einem Schlüsseltresor verwenden, dürfen Sie auf keinen Fall das Geheimnis, den Schlüsseltresor oder die verwaltete Identität löschen, die für den Zugriff auf den Schlüsseltresor verwendet wird.

  1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.

  2. Wählen Sie unter APIs die Optionen Benannte Werte>+ Hinzufügen aus.

  3. Geben Sie als Bezeichner einen Namen sowie einen Anzeigenamen ein, der zum Verweisen auf die Eigenschaft in Richtlinien verwendet wird.

  4. Wählen Sie unter Werttyp die Option Key Vault aus.

  5. Geben Sie den Bezeichner eines Schlüsseltresorgeheimnisses (ohne Version) ein, oder wählen Sie Auswählen aus, um ein Geheimnis aus einem Schlüsseltresor auszuwählen.

    Wichtig

    Wenn Sie selbst einen Bezeichner für ein Schlüsseltresorgeheimnis eingeben, stellen Sie sicher, dass dieser keine Versionsinformationen enthält. Andernfalls wird das Geheimnis nach einer Aktualisierung im Schlüsseltresor nicht automatisch in API Management rotiert.

  6. Wählen Sie unter Clientidentität eine systemseitig zugewiesene oder eine vorhandene benutzerseitig zugewiesene verwaltete Identität aus. Erfahren Sie, wie Sie verwaltete Identitäten in Ihrem API Management-Dienst hinzufügen oder bearbeiten.

    Hinweis

    Die Identität benötigt Berechtigungen zum Abrufen und Auflisten von Geheimnissen im Schlüsseltresor. Wenn Sie den Zugriff auf den Schlüsseltresor noch nicht konfiguriert haben, werden Sie von API Management dazu aufgefordert. Der Dienst kann die Identität dann automatisch mit den erforderlichen Berechtigungen konfigurieren.

  7. Fügen Sie ein (oder mehrere) optionales Tag hinzu, um die benannten Werte zu organisieren, und wählen Sie dann Speichern aus.

  8. Klicken Sie auf Erstellen.

    Hinzufügen eines Schlüsseltresorgeheimnisses

Hinzufügen eines einfachen oder geheimen Werts zu API Management

  1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
  2. Wählen Sie unter APIs die Optionen Benannte Werte>+ Hinzufügen aus.
  3. Geben Sie als Bezeichner einen Namen sowie einen Anzeigenamen ein, der zum Verweisen auf die Eigenschaft in Richtlinien verwendet wird.
  4. Wählen Sie unter Werttyp entweder Plain oder Geheimnis aus.
  5. Geben Sie unter Wert eine Zeichenfolge oder einen Richtlinienausdruck ein.
  6. Fügen Sie ein (oder mehrere) optionales Tag hinzu, um die benannten Werte zu organisieren, und wählen Sie dann Speichern aus.
  7. Klicken Sie auf Erstellen.

Nachdem der benannte Wert erstellt wurde, können Sie ihn bearbeiten, indem Sie den Namen auswählen. Wenn Sie den Anzeigenamen ändern, werden alle Richtlinien, die auf diesen benannten Wert verweisen, automatisch aktualisiert, sodass sie den neuen Anzeigenamen verwenden.

Verwenden benannter Werte

In den Beispielen in diesem Abschnitt werden benannte Werte aus der folgenden Tabelle verwendet.

Name Wert `Secret`
ContosoHeader TrackingId Falsch
ContosoHeaderValue •••••••••••••••••••••• True
ExpressionProperty @(DateTime.Now.ToString()) Falsch
ContosoHeaderValue2 This is a header value. Falsch

Um einen benannten Wert in einer Richtlinie zu verwenden, setzen Sie seinen Anzeigenamen in ein doppeltes Paar geschweifter Klammern (z. B. {{ContosoHeader}}), wie im folgenden Beispiel gezeigt:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

In diesem Beispiel dient ContosoHeader als Name eines Headers in einer set-header-Richtlinie und ContosoHeaderValue als Wert dieses Headers. Wenn diese Richtlinie in einer Anforderung oder Antwort an das API Management-Gateway ausgewertet wird, werden {{ContosoHeader}} und {{ContosoHeaderValue}} durch ihre jeweiligen Werte ersetzt.

Benannte Werte können als vollständige Attribut- oder Elementwerte verwendet werden, wie im vorherigen Beispiel gezeigt, sie können aber auch in einen literalen Textausdruck eingefügt oder mit einem Teil davon kombiniert werden, wie im folgenden Beispiel gezeigt wird:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Benannte Werte können auch Richtlinienausdrücke enthalten. Im folgenden Beispiel wird der Ausdruck ExpressionProperty verwendet.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Beim Auswerten dieser Richtlinie wird {{ExpressionProperty}} durch ihren Wert ersetzt: @(DateTime.Now.ToString()). Da der Wert ein Richtlinienausdruck ist, wird der Ausdruck ausgewertet, und die Ausführung der Richtlinie wird fortgesetzt.

Sie können dies im Azure-Portal oder im Entwicklerportal durch Aufrufen eines Vorgangs testen, der eine Richtlinie mit entsprechenden benannten Werten aufweist. Im folgenden Beispiel wird ein Vorgang mit den beiden vorherigen set-header-Beispielrichtlinien mit benannten Werten aufgerufen. Beachten Sie, dass die Antwort zwei benutzerdefinierte Header enthält, die mithilfe von Richtlinien mit benannten Werten konfiguriert wurden.

API-Antwort auf den Test

Beim Anzeigen der API-Ablaufverfolgung für einen Aufruf, der die beiden vorherigen Beispielrichtlinien mit benannten Werten enthält, sehen Sie beide set-header-Richtlinien mit den eingefügten benannten Werten und die Auswertung des Richtlinienausdrucks für den benannten Wert, der den Richtlinienausdruck enthält.

Verfolgung mit dem API-Inspektor

Die Zeichenfolgeninterpolation kann auch mit benannten Werten verwendet werden.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

Der Wert für CustomHeader wird zu The URL encoded value is This+is+a+header+value..

Achtung

Wenn eine Richtlinie auf ein Geheimnis in Azure Key Vault verweist, wird der Wert aus dem Schlüsseltresor Benutzern angezeigt, die Zugriff auf Abonnements haben, in denen die API-Ablaufverfolgung für Anforderungen aktiviert ist.

Benannte Werte können zwar Richtlinienausdrücke, aber keine anderen benannten Werte enthalten. Wenn für einen Wert, z. B. Text: {{MyProperty}}, Text verwendet wird, der einen Verweis auf einen benannten Wert enthält, wird dieser Verweis nicht aufgelöst und ersetzt.

Löschen benannter Werte

Wenn Sie einen benannten Wert löschen möchten, wählen Sie den Namen und dann im Kontextmenü ( ... ) die Option Löschen aus.

Wichtig

Wenn Richtlinien in API Management auf den benannten Wert verweisen, können Sie ihn erst löschen, nachdem Sie den benannten Wert aus allen Richtlinien entfernt haben, die ihn verwenden.

Nächste Schritte