NGINX als API-Gateway bereitstellen, Teil 1

Liam CrillySenior Director, Produktmanagement

Dies ist der erste Blogbeitrag in unserer Reihe über den Einsatz von NGINX Open Source und NGINX Plus als API-Gateway:

• Dieser Beitrag enthält detaillierte Konfigurationsanweisungen für verschiedene Anwendungsfälle. Er wurde ursprünglich 2018 veröffentlicht und aktualisiert, um die aktuellen Best Practices für die API-Konfiguration widerzuspiegeln. Dabei werden verschachtelte location-Blöcke anstelle von Rewrite-Regeln zum Weiterleiten von Anfragen verwendet.
• Teil 2 erweitert diese Anwendungsfälle und befasst sich mit einer Reihe von Schutzmaßnahmen, die zum Schutz und zur Absicherung von Backend-API-Diensten in Produktionsumgebungen eingesetzt werden können.
• Teil 3 erläutert, wie NGINX Open Source und NGINX Plus als API-Gateway für gRPC-Dienste bereitgestellt werden.

Hinweis: Sofern nicht anders angegeben, gelten alle Informationen in diesem Beitrag sowohl für NGINX Open Source als auch für NGINX Plus. Zur besseren Lesbarkeit wird im weiteren Verlauf des Blogbeitrags lediglich von „NGINX“ gesprochen.

Das Herzstück moderner Anwendungsarchitekturen ist die HTTP-API. HTTP ermöglicht es, Anwendungen schnell zu entwickeln und einfach zu warten. Die HTTP-API bietet unabhängig von der Größe der Anwendung eine einheitliche Schnittstelle – vom spezialisierten Microservice bis hin zum allumfassenden Monolithen. Durch den Einsatz von HTTP lassen sich die Fortschritte bei der Bereitstellung von Webanwendungen, die Internetangebote in Hyperscale-Größenordnung unterstützen, auch für eine zuverlässige und leistungsstarke Bereitstellung von APIs nutzen.

Eine hervorragende Einführung in die Bedeutung von API-Gateways für Microservices-Anwendungen finden Sie im Beitrag „Microservices entwickeln: Einsatz eines API-Gateways“ in unserem Blog.

Als führender hochperformanter, schlanker Reverse-Proxy und Load Balancer verfügt NGINX über die fortschrittlichen HTTP-Verarbeitungsfunktionen, die für die Verarbeitung von API-Datenverkehr erforderlich sind. Damit ist NGINX die ideale Plattform für den Aufbau eines API-Gateways. In diesem Blogbeitrag beschreiben wir einige gängige Anwendungsfälle für API-Gateways und zeigen, wie NGINX konfiguriert werden kann, um diese effizient, skalierbar und wartungsfreundlich abzudecken. Wir stellen eine vollständige Konfiguration vor, die als Grundlage für eine Produktivbereitstellung dienen kann.

Einführung in die Warehouse-API

Die Hauptfunktion des API-Gateways besteht darin, einen zentralen, einheitlichen Zugangspunkt für mehrere APIs bereitzustellen – unabhängig davon, wie diese im Backend implementiert oder bereitgestellt werden. Nicht alle APIs sind Microservices-Anwendungen. Unser API-Gateway muss bestehende APIs, monolithische Anwendungen und Anwendungen verwalten, die teilweise auf Microservices umgestellt werden.

In diesem Blogbeitrag beziehen wir uns auf eine hypothetische API für die Bestandsverwaltung, die „Warehouse API“. Anhand von Beispielkonfigurationscode veranschaulichen wir verschiedene Anwendungsfälle. Die Warehouse API ist eine RESTful API, die JSON-Anfragen verarbeitet und JSON-Antworten erzeugt. Die Verwendung von JSON stellt jedoch weder eine Einschränkung noch eine Voraussetzung für NGINX beim Einsatz als API-Gateway dar. NGINX ist unabhängig vom Architekturstil und den Datenformaten der APIs selbst.

Die Warehouse API ist als Sammlung eigenständiger Microservices implementiert und wird als eine einzige API veröffentlicht. Die Ressourcen für Bestand und Preisgestaltung sind als separate Dienste implementiert und auf unterschiedlichen Backends bereitgestellt. Die Pfadstruktur der API sieht daher wie folgt aus:

api
└── warehouse
    ├── inventory
    └── pricing

Um beispielsweise den aktuellen Lagerbestand abzufragen, sendet eine Clientanwendung eine HTTP-GET-Anfrage an /api/warehouse/inventory.

Organisation der NGINX-Konfiguration

Ein Vorteil der Verwendung von NGINX als API-Gateway besteht darin, dass es diese Rolle übernehmen und gleichzeitig als Reverse-Proxy, Load-Balancer und Webserver für bestehenden HTTP-Datenverkehr fungieren kann. Wenn NGINX bereits Teil Ihres Application-Delivery-Stacks ist, ist die Bereitstellung eines separaten API-Gateways in der Regel nicht erforderlich. Einige der von einem API-Gateway erwarteten Standardverhaltensweisen unterscheiden sich jedoch von denen für browserbasierten Datenverkehr. Aus diesem Grund trennen wir die API-Gateway-Konfiguration von allen bestehenden (oder zukünftigen) Konfigurationen für browserbasierten Datenverkehr.

Um diese Trennung zu erreichen, erstellen wir eine Konfigurationsstruktur, die eine vielseitig einsetzbare NGINX-Instanz unterstützt und eine praktische Grundlage für die automatisierte Bereitstellung von Konfigurationen über CI/CD-Pipelines bietet. Die daraus resultierende Verzeichnisstruktur unter /etc/nginx sieht wie folgt aus.

etc/
└── nginx/
    ├── api_conf.d/ ………………………………… Subdirectory for per-API configuration
    │   └── warehouse_api.conf …… Definition and policy of the Warehouse API
    ├── api_backends.conf ………………… The backend services (upstreams)
    ├── api_gateway.conf …………………… Top-level configuration for the API gateway server
    ├── api_json_errors.conf ………… HTTP error responses in JSON format
    ├── conf.d/
    │   ├── ...
    │   └── existing_apps.conf
    └── nginx.conf

Die Verzeichnisse und Dateinamen der gesamten API-Gateway-Konfiguration beginnen mit dem Präfix api_. Jede dieser Dateien und jedes dieser Verzeichnisse aktiviert eine andere Funktion oder Fähigkeit des API-Gateways, wie im Folgenden ausführlich erläutert. Die Datei warehouse_api.conf dient als allgemeiner Platzhalter für die nachfolgend beschriebenen Konfigurationsdateien, in denen die Warehouse-API auf unterschiedliche Weise definiert wird.

Definieren des API-Gateways auf oberster Ebene

Die gesamte NGINX-Konfiguration beginnt mit der Hauptkonfigurationsdatei nginx.conf. Um die API-Gateway-Konfiguration einzulesen, fügen wir im include-Block http in nginx.conf eine Direktive hinzu, die auf die Datei mit der Gateway-Konfiguration verweist: api_gateway.conf (Zeile 28 direkt darunter). Beachten Sie, dass die standardmäßige Datei nginx.conf eine include-Direktive verwendet, um die browserbasierte HTTP-Konfiguration aus dem Unterverzeichnis conf.d einzubinden (Zeile 29). In diesem Blogbeitrag wird die include-Direktive häufig verwendet, um die Lesbarkeit zu verbessern und die Automatisierung einiger Teile der Konfiguration zu ermöglichen.

Codebeispiel wird geladen…

Die Datei api_gateway.conf definiert den virtuellen Server, über den NGINX den Clients als API-Gateway bereitgestellt wird. Diese Konfiguration stellt alle vom API-Gateway veröffentlichten APIs über einen einzigen Einstiegspunkt bereit: https://api.example.com/ (Zeile 9). Dieser ist durch TLS geschützt, wie in den Zeilen 12 bis 17 konfiguriert. Beachten Sie, dass diese Konfiguration ausschließlich HTTPS verwendet – es gibt keinen Listener für unverschlüsseltes HTTP. Wir gehen davon aus, dass API-Clients den richtigen Einstiegspunkt kennen und standardmäßig HTTPS-Verbindungen herstellen.

Diese Konfiguration ist als statisch vorgesehen – die Details der einzelnen APIs und ihrer Backend-Dienste werden in den Dateien angegeben, auf die die include-Direktive in Zeile 20 verweist. Die Zeilen 23 bis 26 befassen sich mit der Fehlerbehandlung und werden weiter unten unter „Reagieren auf Fehler“ erläutert.

Codebeispiel wird geladen…

Single-Service- vs. Microservice-API-Backends

Einige APIs können mit einem einzigen Backend implementiert werden. Aus Gründen der Ausfallsicherheit oder Lastverteilung gehen wir jedoch normalerweise davon aus, dass mehrere Backends vorhanden sind. Bei Microservices-APIs definieren wir für jeden Service eigene Backends, die zusammen die vollständige API bilden. In diesem Fall wird unsere Warehouse API als zwei separate Services bereitgestellt, die jeweils über mehrere Backends verfügen.

Codebeispiel wird geladen…

Alle Backend-API-Dienste für sämtliche vom API-Gateway veröffentlichten APIs sind in api_backends.conf definiert. Hier verwenden wir in jedem upstream-Block mehrere Paare aus IP-Adresse und Port, um anzugeben, wo der API-Code bereitgestellt ist. Es können jedoch auch Hostnamen verwendet werden. Abonnenten von NGINX Plus können außerdem den dynamischen DNS-Lastenausgleich nutzen, damit neue Backends automatisch zur Laufzeitkonfiguration hinzugefügt werden.

Definieren der Warehouse-API

Die Warehouse-API wird durch mehrere location-Blöcke in einer verschachtelten Konfiguration definiert, wie das folgende Beispiel zeigt. Der äußere location-Block (/api/warehouse) legt den Basispfad fest, unter dem verschachtelte Locations die gültigen URIs angeben, die an die Backend-API-Dienste weitergeleitet werden. Mithilfe eines äußeren Blocks können wir gemeinsame Richtlinien definieren, die für die gesamte API gelten (in diesem Beispiel die Logging-Konfiguration in Zeile 6).

Codebeispiel wird geladen…

NGINX verfügt über ein hocheffizientes und flexibles System, um den Anfrage-URI einem Abschnitt der Konfiguration zuzuordnen. Die Reihenfolge der location-Direktiven ist nicht wichtig – es wird die spezifischste Übereinstimmung ausgewählt. Hier definieren die verschachtelten Locations in den Zeilen 10 und 14 zwei URIs, die spezifischer sind als der äußere location-Block. Die proxy_pass-Direktive in jedem verschachtelten Block leitet Anfragen an die entsprechende Upstream-Gruppe weiter. Die Richtlinienkonfiguration wird von der äußeren Location übernommen, sofern für bestimmte URIs keine spezifischere Richtlinie erforderlich ist.

Alle URIs, die mit keiner der verschachtelten Locations übereinstimmen, werden von der äußeren Location verarbeitet. Diese enthält eine Catch-all-Direktive (Zeile 18), die für alle ungültigen URIs die Antwort „404 (Nicht gefunden)“ zurückgibt.

Auswahl zwischen einer allgemeinen und einer präzisen Definition für APIs

Für die Definition von APIs gibt es zwei Ansätze: eine weit gefasste und eine präzise Definition. Welcher Ansatz für die jeweilige API am besten geeignet ist, hängt von ihren Sicherheitsanforderungen und davon ab, ob die Backend-Dienste ungültige URIs verarbeiten sollen.

In der oben gezeigten Datei „warehouse_api_simple.conf“ verwenden wir für die Warehouse-API den allgemeinen Ansatz und definieren in den Zeilen 10 und 14 URI-Präfixe, sodass eine URI, die mit einem dieser Präfixe beginnt, an den entsprechenden Backend-Dienst weitergeleitet wird. Bei diesem allgemeinen, präfixbasierten Location-Abgleich sind API-Anfragen an die folgenden URIs gültig:

/api/warehouse/inventory
/api/warehouse/inventory/
/api/warehouse/inventory/foo
/api/warehouse/inventoryfoo
/api/warehouse/inventoryfoo/bar/

Wenn es lediglich darum geht, jede Anfrage per Proxy an den richtigen Backend-Dienst weiterzuleiten, bietet der allgemeine Ansatz die schnellste Verarbeitung und die kompakteste Konfiguration. Ein präziserer Ansatz hingegen ermöglicht es dem API-Gateway, den gesamten URI-Raum der API zu erfassen, indem der URI-Pfad für jede verfügbare API-Ressource explizit definiert wird. Bei diesem präzisen Ansatz verwendet die folgende Konfiguration für das URI-Routing in der Warehouse API eine Kombination aus exakten Übereinstimmungen (=) und regulären Ausdrücken (~) zur Definition jeder einzelnen gültigen URI.

Codebeispiel wird geladen…

Diese Konfiguration ist ausführlicher, beschreibt jedoch die von den Backend-Diensten implementierten Ressourcen genauer. Dies bietet den Vorteil, dass die Backend-Dienste vor fehlerhaften Clientanfragen geschützt werden, verursacht jedoch einen geringfügigen zusätzlichen Aufwand für den Abgleich regulärer Ausdrücke. Mit dieser Konfiguration akzeptiert NGINX einige URIs und weist andere als ungültig zurück:

Gültige URIs Ungültige URIs/api/warehouse/inventory /api/warehouse/inventory//api/warehouse/inventory/shelf/foo /api/warehouse/inventoryfoo/api/warehouse/inventory/shelf/foo/box/bar /api/warehouse/inventory/shelf/api/warehouse/inventory/shelf/-/box/- /api/warehouse/inventory/shelf/foo/bar/api/warehouse/pricing/baz /api/warehouse/pricing /api/warehouse/pricing/baz/pub

Durch die Verwendung einer präzisen API-Definition können vorhandene Formate für die API-Dokumentation zur Konfiguration des API-Gateways herangezogen werden. Die NGINX-API-Definitionen lassen sich anhand der OpenAPI-Spezifikation (früher Swagger genannt) automatisieren. Ein Beispielskript hierfür ist in den Gists zu diesem Blogbeitrag verfügbar.

Umschreiben von Clientanfragen zur Handhabung inkompatibler Änderungen

Im Zuge der Weiterentwicklung von APIs sind manchmal Änderungen erforderlich, die die strikte Abwärtskompatibilität aufheben und eine Aktualisierung der Clients notwendig machen. Ein Beispiel hierfür ist die Umbenennung oder Verschiebung einer API-Ressource. Anders als ein Webbrowser kann ein API-Gateway seinen Clients keine Weiterleitung (Code 301 (Dauerhaft verschoben)) mit Angabe des neuen Speicherorts senden. Wenn eine Anpassung der API-Clients nicht praktikabel ist, können wir Clientanfragen glücklicherweise dynamisch umschreiben.

Im folgenden Beispiel verwenden wir denselben allgemeinen Ansatz wie oben in „warehouse_api_simple.conf“. In diesem Fall ersetzt die Konfiguration jedoch eine frühere Version der Warehouse API, in der der Preisfindungsdienst als Teil des Bestandsdienstes implementiert war. Die Direktive „rewrite“ in Zeile 3 wandelt Anfragen an die alte Preisressource in Anfragen an den neuen Preisfindungsdienst um.

Codebeispiel wird geladen…

Auf Fehler reagieren

Einer der wesentlichen Unterschiede zwischen HTTP-APIs und browserbasiertem Datenverkehr besteht darin, wie Fehler an den Client übermittelt werden. Wenn NGINX als API-Gateway eingesetzt wird, konfigurieren wir es so, dass Fehler auf eine für die API-Clients optimale Weise zurückgegeben werden.

Die übergeordnete Konfiguration des API-Gateways enthält einen Abschnitt, in dem festgelegt wird, wie Fehlerantworten behandelt werden.

Codebeispiel wird geladen…

Die error_page-Direktive in Zeile 23 legt fest, dass NGINX den Fehler 400 (Ungültige Anfrage) anstelle des standardmäßigen Fehlers 404 (Nicht gefunden) zurückgibt, wenn eine Anfrage keiner der API-Definitionen entspricht. Dieses (optionale) Verhalten setzt voraus, dass API-Clients ausschließlich Anfragen an die gültigen, in der API-Dokumentation aufgeführten URIs senden, und verhindert, dass unbefugte Clients die URI-Struktur der über das API-Gateway veröffentlichten APIs ermitteln können.

Zeile 24 bezieht sich auf Fehler, die von den Backend-Diensten selbst erzeugt werden. Unbehandelte Ausnahmen können Stacktraces oder andere vertrauliche Daten enthalten, die nicht an den Client gesendet werden sollen. Diese Konfiguration bietet zusätzlichen Schutz, indem sie eine standardisierte Fehlerantwort an den Client sendet.

Die vollständige Liste der standardisierten Fehlerantworten ist in einer separaten Konfigurationsdatei definiert, auf die durch die include-Direktive in Zeile 25 verwiesen wird. Die ersten Zeilen dieser Datei sind unten dargestellt. Wenn ein anderes Fehlerformat als JSON bevorzugt wird, kann diese Datei entsprechend angepasst werden. Dabei muss auch der Wert default_type in Zeile 26 der Datei api_gateway.conf entsprechend geändert werden. Sie können außerdem im Richtlinienabschnitt jeder API eine separate include-Direktive verwenden, um auf eine andere Datei mit Fehlerantworten zu verweisen, die die globalen Antworten überschreiben.

Codebeispiel wird geladen…

Authentifizierung implementieren

Es ist unüblich, APIs ohne eine Form der Authentifizierung zu veröffentlichen, die sie schützt. NGINX bietet verschiedene Ansätze zum Schutz von APIs und zur Authentifizierung von API-Clients. Informationen zu Ansätzen, die auch für reguläre HTTP-Anfragen gelten, finden Sie in der Dokumentation zu IP-adressbasierten Zugriffssteuerungslisten (ACLs), zur Authentifizierung mit digitalen Zertifikaten und zur HTTP-Basisauthentifizierung. Hier konzentrieren wir uns auf API-spezifische Authentifizierungsmethoden.

API-Schlüssel-Authentifizierung

API-Schlüssel sind ein gemeinsames Geheimnis, das dem Client und dem API-Gateway bekannt ist. Ein API-Schlüssel ist im Wesentlichen ein langes und komplexes Passwort, das dem API-Client als langfristiger Berechtigungsnachweis ausgestellt wird. API-Schlüssel lassen sich ganz einfach erstellen: Codieren Sie dazu wie in diesem Beispiel eine Zufallszahl.

$ openssl rand -base64 187B5zIqmRGXmrJTFmKa99vcit

In Zeile 2 der übergeordneten API-Gateway-Konfigurationsdatei api_gateway.conf binden wir eine Datei namens api_keys.conf ein, die für jeden API-Client einen API-Schlüssel enthält. Die Clients werden anhand ihres Namens oder einer anderen Beschreibung identifiziert. Dies ist der Inhalt der Datei:

Codebeispiel wird geladen…

Die API-Schlüssel werden in einem map-Block definiert. Die map-Direktive akzeptiert zwei Parameter. Der erste gibt an, wo der API-Schlüssel zu finden ist, in diesem Fall im HTTP-Header apikey der Clientanfrage, der in der Variablen $http_apikey erfasst wird. Der zweite Parameter erstellt eine neue Variable ($api_client_name) und weist ihr den Wert des zweiten Parameters in der Zeile zu, in der der erste Parameter mit dem Schlüssel übereinstimmt.

Wenn ein Client beispielsweise den API-Schlüssel 7B5zIqmRGXmrJTFmKa99vcit übermittelt, wird die Variable $api_client_name auf client_one gesetzt. Mit dieser Variable kann geprüft werden, ob Clients authentifiziert sind. Außerdem kann sie für eine detailliertere Überwachung in Protokolleinträge aufgenommen werden. Das Format des map-Blocks ist einfach und lässt sich problemlos in automatisierte Workflows integrieren, die die Datei api_keys.conf aus einem vorhandenen Anmeldedatenspeicher generieren.

Hier aktivieren wir die API-Schlüsselauthentifizierung, indem wir die „allgemeine“ Konfiguration (warehouse_api_simple.conf) um eine auth_request-Direktive im Richtlinienabschnitt ergänzen, die die Authentifizierungsentscheidung an einen bestimmten Speicherort delegiert.

Codebeispiel wird geladen…

Mit der Direktive „auth_request“ (Zeile 7) können wir die Authentifizierung beispielsweise von einem externen Authentifizierungsserver durchführen lassen, etwa mittels OAuth 2.0-Token-Introspektion. In diesem Beispiel fügen wir die Logik zur Validierung von API-Schlüsseln stattdessen der übergeordneten Konfigurationsdatei des API-Gateways hinzu, und zwar in Form des folgenden location-Blocks namens /_validate_apikey.

Codebeispiel wird geladen…

Die Direktive internal in Zeile 30 bedeutet, dass externe Clients nicht direkt auf diese Location zugreifen können (sondern nur über auth_request). Clients müssen ihren API-Schlüssel im HTTP-Header apikey übermitteln. Fehlt dieser Header oder ist er leer (Zeile 32), senden wir eine 401-Antwort (Unauthorized), um dem Client mitzuteilen, dass eine Authentifizierung erforderlich ist. Zeile 35 behandelt den Fall, dass der API-Schlüssel mit keinem der Schlüssel im map-Block übereinstimmt. In diesem Fall setzt der Parameter default in Zeile 2 von api_keys.conf die Variable $api_client_name auf eine leere Zeichenfolge, und wir senden eine 403-Antwort (Forbidden), um dem Client mitzuteilen, dass die Authentifizierung fehlgeschlagen ist. Trifft keine dieser Bedingungen zu, ist der API-Schlüssel gültig und die Location gibt eine 204-Antwort (No Content) zurück.

Mit dieser Konfiguration verwendet die Warehouse API nun eine API-Schlüssel-Authentifizierung.

$ curl https://api.example.com/api/warehouse/pricing/item001{"status":401,"message":"Unauthorized"}
$ curl -H "apikey: thisIsInvalid" https://api.example.com/api/warehouse/pricing/item001
{"status":403,"message":"Forbidden"}
$ curl -H "apikey: 7B5zIqmRGXmrJTFmKa99vcit" https://api.example.com/api/warehouse/pricing/item001
{"sku":"item001","price":179.99}

JWT-Authentifizierung

JSON Web Tokens (JWTs) werden zunehmend für die API-Authentifizierung eingesetzt. Die native Unterstützung von JWT ist ausschließlich in NGINX Plus verfügbar und ermöglicht die Validierung von JWTs, wie in unserem Blogbeitrag Authentifizierung von API-Clients mit JWT und NGINX Plus beschrieben. Eine Beispielimplementierung finden Sie unter Steuern des Zugriffs auf bestimmte Methoden in Teil 2.

Zusammenfassung

Dieser erste Beitrag einer Blogreihe beschreibt ausführlich eine Komplettlösung für die Bereitstellung von NGINX Open Source und NGINX Plus als API-Gateway. Alle in diesem Blogbeitrag behandelten Dateien können in unserem GitHub-Gist-Repository eingesehen und heruntergeladen werden.

Lesen Sie auch die anderen Beiträge dieser Reihe:

• Teil 2 befasst sich mit fortgeschritteneren Anwendungsfällen zum Schutz von Backend-Diensten vor böswilligen oder sich fehlerhaft verhaltenden Clients.
• Teil 3 erläutert, wie NGINX als API-Gateway für gRPC-Dienste bereitgestellt wird.

Wenn Sie NGINX Plus ausprobieren möchten, starten Sie noch heute Ihre kostenlose 30-tägige Testversion oder kontaktieren Sie uns, um Ihre Anwendungsfälle zu besprechen.

Über den Autor

Liam CrillySenior Director, Produktmanagement

Weitere Blogbeiträge von Liam Crilly