Freigeben über

Veröffentlichen von Microsoft Azure Data Manager for Energie-APIs in einem gesicherten API-Gateway

  • Artikel

Azure API Management dient als entscheidender Vermittler zwischen Clientanwendungen und Back-End-APIs. Es erleichtert Clients den Zugriff auf Dienste, indem die technischen Details ausgeblendet werden und Organisationen die Kontrolle über die API-Sicherheit erhalten.

Durch die Veröffentlichung von Azure Data Manager for Energy-APIs über Azure API Management können Sie Azure Data Manager for Energy Private Link-Funktion für privaten Datenverkehr verwenden und den direkten öffentlichen Zugriff auf Ihre Instanz vollständig entfernen.

In diesem Artikel wird beschrieben, wie Sie Azure API Management zum Sichern von Azure Data Manager for Energy-APIs einrichten.

Voraussetzungen

Zum Abschließen dieser exemplarischen Vorgehensweise benötigen Sie die folgenden Komponenten, Tools und Informationen:

  • Ein virtuelles Netzwerk mit zwei verfügbaren Subnetzen, eines für den privaten Azure Data Manager for Energy-Endpunkt und das andere für die Azure API Management Virtual Network-Injektion.

  • Azure Data Manager for Energy, konfiguriert mit privater Verbindung und im Subnetz bereitgestellt.

  • Azure API Management wird mithilfe der Virtual Network-Injektion im virtuellen Netzwerk bereitgestellt. Wählen Sie den Modus Extern aus, oder lesen Sie den Abschnitt „Weitere Optionen“ für den Modus Intern.

  • Ein Code-Editor wie Visual Studio Code zum Ändern der Azure Data Manager for Energy OpenAPI-Spezifikationen für jede der veröffentlichten APIs.

  • Laden Sie die Azure Data Manager for Energy OpenAPI-Spezifikationen aus dem adme-samples GitHub-Repository herunter. Navigieren Sie zum Verzeichnis rest-apis, und wählen Sie die entsprechende Version für Ihre Anwendung aus.

  • Beachten Sie aus der App-Registrierung für die Azure Data Manager for Energy-App, die zur Bereitstellungszeit verwendet wurde, die Mandanten-ID und Client-ID:

    Screenshot der App-Registrierungsdetails.

Vorbereiten der Azure API Management-Instanz

Führen Sie die folgenden Schritte aus, um Konfigurationsänderungen an Ihrer Azure API Management-Instanz vorzunehmen:

  1. Wählen Sie im Bereich Alle Ressourcen die Azure API Management-Instanz aus, die für diese exemplarische Vorgehensweise verwendet wird.

  2. Navigieren Sie zur Seite „Produkteeinstellungen“, indem Sie sie in der API-Einstellungsgruppierung auswählen:

    Screenshot der Registerkarte „Produkte“ in der API Management-Instanz.

  3. Wählen Sie auf der Seite "Produkte" die Schaltfläche "Hinzufügen" aus, um ein neues Produkt zu erstellen. Azure API Management-Produkte ermöglichen es Ihnen, eine lose gekoppelte Gruppierung von APIs zu erstellen, die gemeinsam gesteuert und verwaltet werden können. Wir erstellen ein Produkt für unsere Azure Data Manager for Energy-APIs.

  4. Geben Sie im Bereich Produkt hinzufügen Werte ein, die in der folgenden Tabelle beschrieben sind, um das Produkt zu erstellen.

    Screenshot der Seite „Produkte hinzufügen“ in der API Management-Instanz.

    Einstellung Wert
    Anzeigenname „Azure Data Manager for Energy-Produkt“
    Kennung „adme-product“
    Beschreibung Geben Sie eine Beschreibung ein, die Entwicklern angibt, welche APIs wir gruppieren.
    Veröffentlicht Aktivieren Sie dieses Kontrollkästchen, um das von uns erstellte Produkt zu veröffentlichen.
    Abonnement erforderlich Aktivieren Sie dieses Kontrollkästchen, um eine grundlegende Autorisierung für unsere APIs bereitzustellen.
    Genehmigung erforderlich Wählen Sie optional aus, ob Sie möchten, dass ein Administrator Abonnements für dieses Produkt prüfen und ablehnen oder akzeptieren muss. Andernfalls werden Abonnements automatisch genehmigt.
    Grenzwert für Abonnementanzahl Beschränken Sie optional die Anzahl mehrerer gleichzeitiger Abonnements.
    Rechtliche Bedingungen Definieren Sie optional die Nutzungsbedingungen für das Produkt, denen Abonnenten zustimmen müssen, um das Produkt verwenden zu können.
    APIs Wir können dieses Feature ignorieren. Wir ordnen APIs weiter unten in diesem Artikel zu.

  5. Wählen Sie Erstellen aus, um das neue Produkt zu erstellen.

  6. Sobald die Produkterstellung abgeschlossen ist, werden Sie vom Portal zur Seite „Produkte“ zurückgeleitet. Wählen Sie unser neu erstelltes Produkt Azure Data Manager for Energy-Produkt aus, um zur Seite "Produktressourcen" zu wechseln. Wählen Sie im Menü "Einstellungen" das Einstellungsmenüelement Richtlinien aus.

    Screenshot der Konfigurationsseite „Produktrichtlinien“ in der API Management-Instanz.

  7. Wählen Sie im Bereich „Eingehende Verarbeitung“ das Symbol </> aus, mit dem Sie Richtlinien für das Produkt ändern können. Sie fügen drei Gruppen von Richtlinien hinzu, um die Sicherheit der Lösung zu verbessern:

    • Überprüfen des Entra ID-Tokens, um sicherzustellen, dass nicht authentifizierte Anforderungen im API-Gateway abgefangen werden
    • Kontingent und Übertragungsratenlimit, um die Übertragungsrate der Anforderungen und Gesamtzahl der übertragenen Anforderungen/Daten zu steuern
    • Header festlegen, um Header zu entfernen, die von Back-End-APIs zurückgegeben werden, wodurch möglicherweise vertrauliche Details für potenzielle fehlerhafte Akteure offengelegt werden.

  8. Fügen Sie die folgende validate-azure-ad-token-Richtlinie zu unserer Konfiguration innerhalb der eingehenden Tags und unterhalb des Basis-Tags hinzu. Achten Sie darauf, die Vorlage mit den Details der Microsoft Entra ID-App zu aktualisieren, die in den Voraussetzungen angegeben sind.

    <validate-azure-ad-token tenant-id="INSERT_TENANT_ID">
    <client-application-ids>
        <application-id>INSERT_APP_ID</application-id>
    </client-application-ids>
</validate-azure-ad-token>

  9. Fügen Sie unter der Richtlinie validate-azure-ad-token die folgenden Richtlinien für Kontingent und rate-limit hinzu. Aktualisieren Sie die Richtlinienkonfigurationswerte entsprechend Ihren Verbrauchern.

    <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
<quota calls="10000" bandwidth="40000" renewal-period="3600" />

  10. Fügen Sie zum Abschnitt Ausgehend des Richtlinien-Editors und unter dem Basis-Tag die folgenden set-header-Richtlinien hinzu.

    <set-header name="x-envoy-upstream-service-time" exists-action="delete" />
<set-header name="x-internal-uri-pattern" exists-action="delete" />

  11. Wählen Sie Speichern aus, um Ihre Änderungen zu übernehmen.

    Screenshot des vollständigen Richtliniendokuments.

  12. Navigieren Sie zurück zur API Management-Ressource im Azure-Portal. Wählen Sie das Menüelement Back-Ends aus und dann die Schaltfläche + Hinzufügen.

    Screenshot der Seite „Back-Ends“.

  13. Geben Sie im Modal Back-End Werte ein, die in der folgenden Tabelle beschrieben sind, um das Back-End zu erstellen.

    Einstellung Wert
    Name „adme-backend“
    Beschreibung Geben Sie eine Beschreibung ein, die Entwicklern angibt, dass dieses Back-End mit Azure Data Manager for Energy-APIs verknüpft ist.
    type Benutzerdefinierte URL
    URL der Runtime Geben Sie Ihren Azure Data Manager for Energy-URI –ex ein. https://INSERT_ADME_NAME.energy.azure.com/
    Zertifikatkette überprüfen Überprüft
    Zertifikatnamen überprüfen Überprüft

    Screenshot des Modals „Back-Ends“.

  14. Klicken Sie auf Erstellen, um das Back-End zu erstellen. Dieses neu erstellte Back-End wird im nächsten Abschnitt verwendet, wenn APIs veröffentlicht werden.

Importieren von Azure Data Manager for Energy-APIs

Führen Sie die folgenden Schritte aus, um Azure Data Manager for Energy-APIs im Azure API Management-Gateway zu importieren, zu konfigurieren und zu veröffentlichen:

  1. Navigieren Sie zurück zur Azure API Management-Instanz, die im letzten Abschnitt verwendet wird.

  2. Wählen Sie das Menüelement APIs im Menü aus, und wählen Sie dann die Schaltfläche + API hinzufügen aus.

  3. Wählen Sie OpenAPI unter der Überschrift Aus Definition erstellen aus.

    Screenshot des OpenAPI-Importbildschirms.

  4. Aktivieren Sie im Modal-Fenster Aus OpenAPI-Spezifikation erstellen die Option Vollständig.

  5. Suchen Sie die OpenAPI-Spezifikationen, die Sie als Teil der Voraussetzungen heruntergeladen haben, und öffnen Sie die Schema-Spezifikation mithilfe des Code-Editors Ihrer Wahl. Suchen Sie nach dem Wort "server" und notieren Sie sich die Server-URL in der Datei z. B. /api/schema-service/v1/.

  6. Wählen Sie Datei auswählen und dann die API-Spezifikation Schema aus. Nach Abschluss des Uploads lädt das Modal-Fenster einige Werte aus der Spezifikation.

  7. Geben Sie für die anderen Felder Werte ein, die in der folgenden Tabelle beschrieben werden:

    Einstellung Wert
    Einschließen der erforderlichen Abfrageparameter in Vorgangsvorlagen Überprüft
    Anzeigename Geben Sie einen Anzeigenamen ein, der für App-Entwickler sinnvoll ist, Bsp. Azure Data Manager for Energy-Schemadienst
    Name Die API-Verwaltung schlägt einen Namen in Form eines Kebab vor. Optional kann der Name geändert werden, muss aber für die Instanz eindeutig sein.
    Beschreibung In der OpenAPI-Spezifikation kann eine Beschreibung definiert sein. Wenn dies der Fall ist, wird die Beschreibung automatisch ausgefüllt. Aktualisieren Sie optional die Beschreibung pro Anwendungsfall.
    URL-Schema Wählen Sie „Beide“ aus.
    API-URL-Suffix Geben Sie ein Suffix für alle Azure Data Manager for Energy-APIs ein (z. B. adme). Geben Sie dann die Server-URL aus Schritt 5 ein. Der endgültige Wert sollte wie /adme/api/schema-service/v1/ aussehen. Ein Suffix ermöglicht es uns, mit vorhandenen Clients und Softwareentwicklungskits kompatibel zu sein, die normalerweise direkt mit Azure Data Manager for Energy-APIs verbunden sind.
    Tags Optional können Sie Tags
    Produkte Wählen Sie das im vorherigen Abschnitt erstellte Produkt „Azure Data Manager for Energy“ aus.

    Wichtig

    Überprüfen des API-URL-Suffix. Dies ist eine häufige Ursache für Fehler beim Veröffentlichen der Azure Data Manager for Energy-APIs.

  8. Wählen Sie Erstellen aus, um die API-Fassade zu erstellen.

    Screenshot des Spezifikationsbildschirms „Aus OpenAPI erstellen“.

  9. Wählen Sie die neu erstellte Schema-API-Fassade aus der Liste der APIs aus, und wählen Sie in der Vorgangsliste Alle Vorgänge aus. Wählen Sie im Bereich Eingehende Verarbeitung das Symbol </> aus, um das Richtliniendokument zu bearbeiten.

    Screenshot des API-Richtlinienbildschirms.

  10. Um die API zu konfigurieren, fügen Sie zwei Richtliniengruppen hinzu:

    • Festlegen des Back-End-Diensts, um Anforderungen an die Azure Data Manager for Energy-Instanz weiterzuleiten
    • Neuschreiben des URI, um das Präfix adme zu entfernen und die Anforderung an die Back-End-API zu erstellen. Diese Richtlinienausweisung verwendet Richtlinienausdrücke, um den Wert der URL-Vorlage des aktuellen Vorgangs dynamisch zu unserer Server-URL hinzuzufügen.

  11. Notieren Sie die Server-URL aus Schritt 5. Fügen Sie unter dem Basis-Tag im Abschnitt Eingehend die folgenden beiden Richtlinienanweisungen ein.

    <set-backend-service backend-id="adme-backend" />

    <!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 -->
<rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />

  12. Wählen Sie Speichern aus, um Ihre Änderungen zu übernehmen.

  13. Testen Sie die API, indem Sie den Vorgang GET Version info aus der Vorgangsliste auswählen. Wählen Sie dann die Registerkarte Test aus, um zur Azure API Management Test Console zu navigieren.

  14. Geben Sie die in der Tabelle beschriebenen Werte ein. Generieren Sie ein Authentifizierungstoken für Azure Data Manager for Energy. Wählen Sie Senden aus, um die API zu testen.

    Einstellung Wert
    data-partition-id Die Datenpartitions-ID für Ihre Instanz von Azure Data Manager for Energy
    Produkt Wählen Sie das zuvor erstellte Produkt „Azure Data Manager for Energy“ aus.
    Autorisierung „Bearer“ und das von Ihnen generierte Authentifizierungstoken

    Screenshot: „Von API Test Console erstellen“.

  15. Wenn die API ordnungsgemäß konfiguriert ist, sollte eine Antwort HTTP 200 – OK angezeigt werden, die dem Screenshot ähnelt. Falls nicht, sehen Sie sich den Abschnitt zur Problembehandlung an.

  16. Wiederholen Sie die vorstehenden Schritte für jede Azure Data Manager for Energy-API und die zugehörige Spezifikation.

Problembehandlung

Wenn beim Testen von APIs über Azure API Management Fehler auftreten, deuten sie in der Regel auf Konfigurationsprobleme hin. Überprüfen Sie basierend auf dem Fehler die möglichen Lösungsschritte.

Code Fehlermeldung Details
HTTP 401 Unauthorized Invalid Azure AD JWT Überprüfen Sie, ob Sie über einen gültigen Authentifizierungsheader für den Microsoft Entra ID-Mandanten und die Client-App für Ihre Azure Data Manager for Energy-Instanz verfügen.
HTTP 401 Unauthorized Azure AD JWT not present Überprüfen Sie, ob der Authentifizierungsheader zu Ihrer Testanforderung hinzugefügt wurde.
HTTP 404 Not Found Dieser Fehler bedeutet in der Regel, dass die Anforderung an die Back-End-API an die falsche URL gesendet wird. Führen Sie eine Ablaufverfolgung Ihrer API-Anforderung in API Management durch, um zu verstehen, welche URL für die Back-End-Anforderung generiert wird, und stellen Sie sicher, dass sie gültig ist. Falls nicht, überprüfen Sie die url-rewrite-Richtlinie oder das Back-End.
HTTP 500 Internal Server Error Internal server error Dieser Fehler weist in der Regel auf ein Problem hin, das Anforderungen an die Back-End-API sendet. In diesem Szenario sind in der Regel DNS-bezogene Domänennamendienste (Domain Name Services) das Problem. Stellen Sie sicher, dass eine private DNS-Zone in Ihrem virtuellen Netzwerk konfiguriert ist oder dass ihre benutzerdefinierte DNS-Auflösung über die entsprechenden Weiterleitungen verfügt. Führen Sie eine Ablaufverfolgung Ihrer API-Anforderung in API Management durch, um zu verstehen, welche Back-End-Anforderung vorgenommen wurde und welche Fehler API Management meldet, wenn versucht wird, die Anforderung auszuführen.

Weitere Überlegungen

Virtuelles Netzwerk im internen Modus mit API Management

Der interne Modus isoliert Azure API Management vollständig, anstatt die Endpunkte über eine öffentliche IP-Adresse verfügbar zu machen. In dieser Konfiguration können Organisationen sicherstellen, dass Azure Data Manager for Energy ausschließlich intern ist. Da Azure Data Manager for Energy eine Lösung für die Zusammenarbeit mit Partnern und Kunden ist, ist dieses Szenario jedoch möglicherweise nicht von Vorteil.

App Gateway mit Web Application Firewall

Anstatt nur den internen virtuellen Netzwerkmodus zu verwenden, entscheiden sich viele Unternehmen für einen sicheren Reverseproxy-Mechanismus, um die Azure API Management-Instanz im internen Modus für externe Partner zugänglich zu machen. Die Instanz des internen Modus bleibt vollständig isoliert mit einem streng kontrollierten Eingang, der den Proxy durchlaufen muss.

Azure App Gateway ist ein allgemeiner Dienst, der als Reverseproxy dient. Azure App Gateway verfügt außerdem über eine Webanwendungsfirewall (WAF), die potenzielle Angriffe auf Sicherheitsrisiken in Ihren Anwendungen und APIs aktiv erkennt.

Konfigurieren von Azure API Management mit einer benutzerdefinierten Domäne

Ein weiteres gängiges Feature dieser Architektur besteht darin, eine benutzerdefinierte Domäne auf die APIs anzuwenden. Obwohl Azure Data Manager for Energy dieses Feature nicht unterstützt, können Sie stattdessen eine benutzerdefinierte Domäne in Azure API Management konfigurieren.

Ein Zertifikat für die Domäne ist eine Voraussetzung. Azure API Management unterstützt jedoch das Erstellen kostenloser verwalteter Zertifikate für Ihre benutzerdefinierte Domäne.

Zugehöriger Inhalt