Verwenden von benannten Werten in Azure API Management-Richtlinien

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.

Named values in the 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 für die Key Vault-Integration

  1. Schritte zum Erstellen eines Schlüsseltresors finden Sie unter Schnellstart: Erstellen eines Schlüsseltresors über das Azure-Portal.
  2. Aktivieren Sie eine system- oder benutzerseitig zugewiesene verwaltete Identität in der API Management-Instanz.
  3. Weisen Sie der verwalteten Identität Key Vault-Zugriffsrichtlinien mit Berechtigungen zum Abrufen und Auflisten von Geheimnissen im Tresor zu. So fügen Sie die Richtlinie hinzu
    1. Navigieren Sie im Portal zu Ihrem Schlüsseltresor.
    2. Wählen Sie Einstellungen > Zugriffsrichtlinien > +Zugriffsrichtlinie hinzufügen aus.
    3. Wählen Sie Geheimnisberechtigungen und dann Abrufen und Auflisten aus.
    4. Wählen Sie unter Prinzipal auswählen den Ressourcennamen der verwalteten Identität aus. Wenn Sie eine systemseitig zugewiesene Identität verwenden, ist der Prinzipal der Name der API Management-Instanz.
  4. Erstellen Sie ein Geheimnis im Schlüsseltresor, oder importieren Sie es. Weitere Informationen finden Sie unter Schnellstart: Festlegen eines Geheimnisses und Abrufen des Geheimnisses aus Azure Key Vault mithilfe des Azure-Portals.

Um das Schlüsseltresorgeheimnis zu verwenden, müssen Sie einen benannten Wert hinzufügen oder bearbeiten und einen Typ von Schlüsseltresor angeben. Wählen Sie das Geheimnis im Schlüsseltresor 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? .

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 von Schlüsseltresorgeheimnissen

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

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.

    Add key vault secret value

Hinzufügen eines Plain- oder Geheimniswerts

  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

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.

Test API response

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.

API Inspector trace

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