Validierung von OAuth-2.0-Zugriffstokens mit NGINX und NGINX Plus

Liam CrillySenior Director, Produktmanagement

Für die Authentifizierung von API-Aufrufen gibt es viele Möglichkeiten, von X.509-Clientzertifikaten bis hin zur HTTP-Basisauthentifizierung. In den letzten Jahren hat sich jedoch mit OAuth-2.0-Zugriffstoken ein De-facto-Standard etabliert. Dabei handelt es sich um Authentifizierungsdaten, die vom Client an den API-Server übermittelt und üblicherweise in einem HTTP-Header übertragen werden.

OAuth 2.0 ist jedoch ein Labyrinth miteinander verknüpfter Standards. Die Prozesse zum Ausstellen, Übermitteln und Validieren im Rahmen eines OAuth-2.0-Authentifizierungsablaufs stützen sich häufig auf mehrere verwandte Standards. Zum Zeitpunkt der Erstellung dieses Textes gibt es acht OAuth-2.0-Standards, und Zugriffstoken sind ein gutes Beispiel dafür, da die OAuth-2.0-Kernspezifikation (RFC 6749) kein Format für Zugriffstoken vorgibt. In der Praxis sind zwei Formate weitverbreitet:

• JSON Web Token (JWT) gemäß RFC 7519
• Opake Token, die kaum mehr als eine eindeutige Kennung für einen authentifizierten Client darstellen

Nach der Authentifizierung übermittelt ein Client bei jeder HTTP-Anfrage sein Zugriffstoken, um auf geschützte Ressourcen zuzugreifen. Das Zugriffstoken muss validiert werden, um sicherzustellen, dass es tatsächlich von einem vertrauenswürdigen Identitätsanbieter (IdP) ausgestellt wurde und noch nicht abgelaufen ist. Da IdPs die von ihnen ausgestellten JWTs kryptografisch signieren, können JWTs „offline“ validiert werden, ohne dass zur Laufzeit eine Abhängigkeit vom IdP besteht. In der Regel enthält ein JWT außerdem ein Ablaufdatum, das ebenfalls überprüft werden kann. Das NGINX Plus auth_jwt-Modul führt die Offline-Validierung von JWTs durch.

Opaque Tokens hingegen müssen validiert werden, indem sie an den IdP zurückgesendet werden, der sie ausgestellt hat. Dies hat jedoch den Vorteil, dass solche Tokens vom IdP widerrufen werden können, beispielsweise im Rahmen einer globalen Abmeldung, ohne dass zuvor angemeldete Sitzungen weiterhin aktiv bleiben. Eine globale Abmeldung kann es außerdem erforderlich machen, JWTs beim IdP zu validieren.

In diesem Blog beschreiben wir, wie NGINX und NGINX Plus als OAuth-2.0-Relying Party fungieren können, indem sie Zugriffstoken zur Validierung an den IdP senden und nur Anfragen weiterleiten, die den Validierungsprozess erfolgreich durchlaufen. Wir erläutern die verschiedenen Vorteile, die der Einsatz von NGINX und NGINX Plus für diese Aufgabe bietet, und wie sich die Benutzererfahrung verbessern lässt, indem Validierungsantworten für kurze Zeit zwischengespeichert werden. Für NGINX Plus zeigen wir außerdem, wie der Cache über einen Cluster von NGINX Plus-Instanzen verteilt werden kann, indem der Schlüssel-Wert-Speicher mit dem JavaScript-Modul aktualisiert wird, das mit NGINX Plus R18 eingeführt wurde.

Sofern nicht anders angegeben, gelten die Informationen in diesem Blog sowohl für NGINX Open Source als auch für NGINX Plus. Verweise auf NGINX Plus beziehen sich ausschließlich auf dieses Produkt.

Token-Introspektion

Die Standardmethode zur Validierung von Zugriffstoken bei einem IdP wird als Token-Introspektion bezeichnet. RFC 7662, OAuth 2.0 Token Introspection, ist mittlerweile ein weithin unterstützter Standard, der eine JSON/REST-Schnittstelle beschreibt, über die eine vertrauende Partei dem IdP ein Token vorlegt, sowie die Struktur der Antwort definiert. Er wird von vielen führenden IdP-Anbietern und Cloud-Providern unterstützt.

Unabhängig vom verwendeten Tokenformat führt die Validierung in jedem Backend-Dienst bzw. jeder Anwendung zu zahlreichen Codeduplikaten und unnötigem Verarbeitungsaufwand. Dabei müssen verschiedene Fehlerbedingungen und Grenzfälle berücksichtigt werden. Geschieht dies in jedem Backend-Dienst separat, sind eine uneinheitliche Implementierung und damit ein unvorhersehbares Benutzererlebnis praktisch vorprogrammiert. Überlegen Sie, wie die einzelnen Backend-Dienste mit den folgenden Fehlerbedingungen umgehen könnten:

• Fehlendes Zugriffstoken
• Extrem großer Zugriffstoken
• Ungültige oder unerwartete Zeichen im Zugriffstoken
• Mehrere Zugriffstoken angegeben
• Zeitabweichung zwischen Backend-Diensten

Verwendung des NGINX-auth_request-Moduls zur Validierung von Tokens

Um die Duplizierung von Code und die daraus resultierenden Probleme zu vermeiden, können wir NGINX verwenden, um Zugriffstoken im Namen von Backend-Diensten zu validieren. Dies bietet eine Reihe von Vorteilen:

• Anfragen erreichen die Backend-Dienste nur, wenn der Client ein gültiges Token vorgelegt hat
• Bestehende Backend-Dienste können ohne Codeänderungen durch Zugriffstoken geschützt werden.
• Nur die NGINX-Instanz (nicht jede einzelne App) muss beim IdP registriert werden
• Das Verhalten ist bei jeder Fehlerbedingung konsistent, auch bei fehlenden oder ungültigen Tokens.

Wenn NGINX als Reverse-Proxy für eine oder mehrere Anwendungen fungiert, können wir das Modul auth_request module verwenden, um einen API-Aufruf an einen IdP auszulösen, bevor eine Anfrage an das Backend weitergeleitet wird. Wie wir gleich sehen werden, weist die folgende Lösung einen grundlegenden Fehler auf. Sie veranschaulicht jedoch die grundlegende Funktionsweise des Moduls auth_request, auf die wir in späteren Abschnitten näher eingehen werden.

Codebeispiel wird geladen…

Die auth_request-Direktive (Zeile 5) gibt den Ort für die Verarbeitung von API-Aufrufen an. Die Weiterleitung an das Backend (Zeile 6) erfolgt nur, wenn die auth_request-Antwort erfolgreich ist. Der auth_request-Ort wird in Zeile 9 definiert. Er ist als internal gekennzeichnet, um zu verhindern, dass externe Clients direkt darauf zugreifen.

In den Zeilen 11–14 werden verschiedene Attribute der Anfrage definiert, damit sie dem Format einer Token-Introspektionsanfrage entspricht. Beachten Sie, dass das in der Introspektionsanfrage gesendete Zugriffstoken Bestandteil des in Zeile 14 definierten Anfragekörpers ist. Hier gibt token=$http_apikey an, dass der Client das Zugriffstoken im Anfrage-Header apikey bereitstellen muss. Das Zugriffstoken kann natürlich in einem beliebigen Attribut der Anfrage bereitgestellt werden; in diesem Fall verwenden wir eine andere NGINX-Variable.

Erweiterung von auth_request mit dem NGINX-JavaScript-Modul

Wie bereits erwähnt, ist die Verwendung des auth_request-Moduls auf diese Weise keine vollständige Lösung. Das auth_request-Modul ermittelt den Erfolg anhand von HTTP-Statuscodes (2xx = erfolgreich, 4xx = fehlgeschlagen). Antworten auf die OAuth-2.0-Token-Introspektion geben Erfolg oder Fehlschlag jedoch in einem JSON-Objekt an und liefern in beiden Fällen den HTTP-Statuscode 200 (OK).

Wir benötigen einen JSON-Parser, der die Introspektionsantwort des IdP in den passenden HTTP-Statuscode umwandelt, damit das Modul auth_request diese Antwort korrekt interpretieren kann.

Glücklicherweise ist das Parsen von JSON für das NGINX-JavaScript-Modul (njs) eine triviale Aufgabe. Anstatt also einen location-Block für die Token-Introspektionsanfrage zu definieren, weisen wir das auth_request-Modul an, eine JavaScript-Funktion aufzurufen.

[Redaktion – Dieser Beitrag ist einer von mehreren, die sich mit Anwendungsfällen für das NGINX-JavaScript-Modul befassen. Eine vollständige Liste finden Sie unter „Anwendungsfälle für das NGINX-JavaScript-Modul“.

Der Code in diesem Abschnitt wurde aktualisiert und verwendet nun die Direktive „js_import“, welche die Direktive „js_include“ ab NGINX Plus R23 ersetzt. Weitere Informationen finden Sie in der Referenzdokumentation zum NGINX JavaScript-Modul – der Abschnitt „Beispielkonfiguration“ zeigt die korrekte Syntax für NGINX-Konfigurations- und JavaScript-Dateien.]

Hinweis: Für diese Lösung muss das JavaScript-Modul mit der Direktive load_module in nginx.conf als dynamisches Modul geladen werden. Eine Anleitung finden Sie im NGINX Plus-Administratorhandbuch.

Codebeispiel wird geladen…

Die js_content-Direktive in Zeile 13 legt die JavaScript-Funktion introspectAccessToken als Handler für auth_request fest. Die Handler-Funktion ist in oauth2.js definiert:

Codebeispiel wird geladen…

Beachten Sie, dass die introspectAccessToken-Funktion eine HTTP-Unteranfrage (Zeile 2) an einen anderen Speicherort (/oauth2_send_request) sendet, der im nachfolgenden Konfigurationsausschnitt definiert ist. Der JavaScript-Code analysiert anschließend die Antwort (Zeile 5) und sendet basierend auf dem Wert des Feldes auth_request den entsprechenden Statuscode an das active-Modul zurück. Gültige (aktive) Token geben den HTTP-Statuscode 204 (No Content) (erfolgreich, jedoch ohne Inhalt) zurück, ungültige Token hingegen den HTTP-Statuscode 403 (Forbidden). Bei Fehlern wird der HTTP-Statuscode 401 (Unauthorized) zurückgegeben, damit Fehler von ungültigen Token unterschieden werden können.

Hinweis: Dieser Code dient lediglich als Machbarkeitsnachweis und ist nicht für den produktiven Einsatz geeignet. Eine vollständige Lösung mit umfassender Fehlerbehandlung und Protokollierung finden Sie weiter unten.

Der in Zeile 2 definierte Zielpfad der Unteranfrage ähnelt stark unserer ursprünglichen auth_request-Konfiguration.

Codebeispiel wird geladen…

Die gesamte Konfiguration zum Erstellen der Token-Introspektionsanfrage befindet sich im Speicherort /_oauth2_send_request. Authentifizierung (Zeile 19), das Zugriffstoken selbst (Zeile 21) und die URL des Token-Introspektionsendpunkts (Zeile 22) sind in der Regel die einzigen erforderlichen Konfigurationselemente. Die Authentifizierung ist erforderlich, damit der IdP Token-Introspektionsanfragen von dieser NGINX-Instanz akzeptiert. Die Spezifikation OAuth 2.0 Token Introspection schreibt eine Authentifizierung vor, legt jedoch keine Methode fest. In diesem Beispiel verwenden wir ein Bearer-Token im Authorization-Header.

Wenn diese Konfiguration eingerichtet ist und NGINX eine Anfrage empfängt, leitet es diese an das JavaScript-Modul weiter, das eine Token-Introspektionsanfrage an den IdP sendet. Die Antwort des IdP wird geprüft, und die Authentifizierung gilt als erfolgreich, wenn das Feld active den Wert true aufweist. Diese Lösung bietet eine kompakte und effiziente Möglichkeit, die OAuth-2.0-Token-Introspektion mit NGINX durchzuführen, und lässt sich problemlos an andere Authentifizierungs-APIs anpassen.

Aber wir sind noch nicht ganz fertig. Die größte Herausforderung bei der Token-Introspektion besteht generell darin, dass sie die Latenz jeder einzelnen HTTP-Anfrage erhöht. Dies kann zu einem erheblichen Problem werden, wenn es sich bei dem betreffenden IdP um eine gehostete Lösung oder einen Cloud-Anbieter handelt. NGINX und NGINX Plus können diesen Nachteil durch das Zwischenspeichern der Introspektionsantworten abmildern.

Optimierung 1: Caching durch NGINX

Die Introspektion von OAuth-2.0-Token wird vom IdP über einen JSON/REST-Endpunkt bereitgestellt. Daher besteht die Standardantwort aus einem JSON-Body mit dem HTTP-Status 200. Wird diese Antwort anhand des Zugriffstokens indiziert, lässt sie sich sehr gut zwischenspeichern.

NGINX kann so konfiguriert werden, dass für jedes Zugriffstoken eine Kopie der Introspektionsantwort zwischengespeichert wird. Wird dasselbe Zugriffstoken erneut übermittelt, stellt NGINX die zwischengespeicherte Introspektionsantwort bereit, anstatt einen API-Aufruf an den IdP zu senden. Dadurch wird die Gesamtlatenz nachfolgender Anfragen erheblich reduziert. Um das Risiko zu minimieren, ein abgelaufenes oder kürzlich widerrufenes Zugriffstoken zu akzeptieren, lässt sich festlegen, wie lange zwischengespeicherte Antworten verwendet werden. Wenn ein API-Client beispielsweise üblicherweise innerhalb kurzer Zeit mehrere API-Aufrufe sendet, kann eine Cache-Gültigkeitsdauer von 10 Sekunden ausreichen, um die Benutzerfreundlichkeit spürbar zu verbessern.

Das Caching wird aktiviert, indem der Speicherort angegeben wird: ein Verzeichnis auf dem Datenträger für den Cache (Introspektionsantworten) und ein gemeinsam genutzter Speicherbereich für die Schlüssel (Zugriffstoken).

Codebeispiel wird geladen…

Die proxy_cache_path-Direktive weist den erforderlichen Speicher zu: /var/cache/nginx/oauth für die Introspektionsantworten und eine Speicherzone namens token_responses für die Schlüssel. Sie wird im http-Kontext konfiguriert und befindet sich daher außerhalb der server- und location-Blöcke. Das Caching selbst wird dann innerhalb des location-Blocks aktiviert, in dem die Token-Introspektionsantworten verarbeitet werden:

Codebeispiel wird geladen…

Für diesen Speicherort wird das Caching mit der Direktive „proxy_cache“ aktiviert (Zeile 26). Standardmäßig speichert NGINX anhand des URI zwischen. In unserem Fall soll die Antwort jedoch anhand des Zugriffstokens zwischengespeichert werden, das im Anfrage-Header „apikey“ übermittelt wird (Zeile 27).

In Zeile 28 verwenden wir die proxy_cache_lock-Direktive, um NGINX anzuweisen, bei gleichzeitig eingehenden Anfragen mit demselben Cache-Schlüssel zu warten, bis die erste Anfrage den Cache gefüllt hat, bevor die übrigen beantwortet werden. Die proxy_cache_valid-Direktive (Zeile 29) legt fest, wie lange NGINX die Introspektionsantwort zwischenspeichert. Ohne diese Direktive bestimmt NGINX die Cache-Dauer anhand der vom IdP gesendeten Cache-Control-Header. Diese sind jedoch nicht immer zuverlässig, weshalb wir NGINX außerdem anweisen, Header zu ignorieren, die andernfalls beeinflussen würden, wie Antworten zwischengespeichert werden (Zeile 30).

Da das Caching nun aktiviert ist, fällt für einen Client, der ein Zugriffstoken vorlegt, die durch die Token-Introspektionsanfrage verursachte Latenz nur noch einmal alle 10 Sekunden an.

Optimierung 2: Verteiltes Caching mit NGINX Plus

Die Kombination von Inhalts-Caching und Token-Introspektion ist eine äußerst effektive Möglichkeit, die Gesamtleistung der Anwendung zu verbessern, ohne die Sicherheit nennenswert zu beeinträchtigen. Wird NGINX jedoch verteilt bereitgestellt – beispielsweise über mehrere Rechenzentren, Cloud-Plattformen oder einen Aktiv-Aktiv-Cluster hinweg –, stehen zwischengespeicherte Antworten auf Token-Introspektionsanfragen nur der NGINX-Instanz zur Verfügung, die die Introspektionsanfrage ausgeführt hat.

Mit NGINX Plus können wir das keyval-Modul – einen In-Memory-Schlüssel-Wert-Speicher – verwenden, um Antworten auf Token-Introspektionsanfragen zwischenzuspeichern. Darüber hinaus können wir diese Antworten mithilfe des zone_sync-Moduls auch über einen Cluster von NGINX Plus-Instanzen hinweg synchronisieren. Das bedeutet: Unabhängig davon, welche NGINX Plus-Instanz die Token-Introspektionsanfrage ausgeführt hat, steht die Antwort allen NGINX Plus-Instanzen im Cluster zur Verfügung.

Hinweis: Die Konfiguration des zone_sync-Moduls für die gemeinsame Nutzung des Laufzeitstatus wird in diesem Blog nicht behandelt. Weitere Informationen zur gemeinsamen Nutzung des Status in einem NGINX Plus-Cluster finden Sie im NGINX Plus-Administratorhandbuch.

Ab NGINX Plus R18 kann der Schlüssel-Wert-Speicher aktualisiert werden, indem die Variable geändert wird, die in der keyval-Direktive deklariert ist. Da das JavaScript-Modul Zugriff auf alle NGINX-Variablen hat, können Introspektionsantworten während der Verarbeitung der Antwort in den Schlüssel-Wert-Speicher eingetragen werden.

Wie beim NGINX-Dateisystem-Cache wird der Schlüssel-Wert-Speicher aktiviert, indem sein Speicher angegeben wird – in diesem Fall eine Speicherzone, in der der Schlüssel (Zugriffstoken) und der Wert (Introspektionsantwort) gespeichert werden.

Codebeispiel wird geladen…

Beachten Sie, dass wir mit dem Parameter „timeout“ der Direktive „keyval_zone“ für zwischengespeicherte Antworten dieselbe Gültigkeitsdauer von 10 Sekunden wie in Zeile 29 von auth_request_cache.conf festlegen, sodass jedes Mitglied des NGINX Plus-Clusters die Antwort nach Ablauf dieser Dauer selbstständig entfernt. Zeile 2 gibt das Schlüssel-Wert-Paar für jeden Eintrag an: Der Schlüssel ist das im Anfrage-Header „apikey“ übermittelte Zugriffstoken, und der Wert ist die Introspektionsantwort, die anhand der Variablen „$token_data“ ausgewertet wird.

Nun wird bei jeder Anfrage, die einen apikey-Anfrageheader enthält, die Variable $token_data mit der vorherigen Antwort der Token-Introspektion befüllt, sofern eine solche vorhanden ist. Daher aktualisieren wir den JavaScript-Code, um zu prüfen, ob bereits eine Antwort der Token-Introspektion vorliegt.

Codebeispiel wird geladen…

In Zeile 2 wird geprüft, ob für dieses Zugriffstoken bereits ein Eintrag im Schlüssel-Wert-Speicher vorhanden ist. Da eine Introspektionsantwort auf zwei Wegen abgerufen werden kann (aus dem Schlüssel-Wert-Speicher oder über eine Introspektionsanfrage), lagern wir die Validierungslogik in die folgende separate Funktion aus: tokenResult:

Codebeispiel wird geladen…

Nun wird jede Antwort der Token-Introspektion im Schlüssel-Wert-Speicher gespeichert und mit allen anderen Mitgliedern des NGINX Plus-Clusters synchronisiert. Das folgende Beispiel zeigt eine einfache HTTP-Anfrage mit einem gültigen Zugriffstoken, gefolgt von einer Abfrage der NGINX Plus-API, um den Inhalt des Schlüssel-Wert-Speichers anzuzeigen.

$ curl -IH "apikey: tQ7AfuEFvI1yI-XNPNhjT38vg_reGkpDFA" http://localhost/HTTP/1.1 200 OK
Date: Wed, 24 Apr 2019 17:41:34 GMT
Content-Type: application/json
Content-Length: 612

$ curl http://localhost/api/4/http/keyvals/access_tokens
{"tQ7AfuEFvI1yI-XNPNhjT38vg_reGkpDFA":"{\"active\":true}"}

Beachten Sie, dass der Schlüssel-Wert-Speicher selbst das JSON-Format verwendet. Daher werden Anführungszeichen in der Antwort der Token-Introspektion automatisch maskiert.

Optimierung 3: Extrahieren von Attributen aus der Introspektionsantwort

Eine nützliche Funktion der OAuth-2.0-Token-Introspektion besteht darin, dass die Antwort neben dem Aktivitätsstatus auch Informationen über das Token enthalten kann. Dazu gehören das Ablaufdatum des Tokens und Attribute des zugehörigen Benutzers, etwa Benutzername, E-Mail-Adresse usw.

Diese zusätzlichen Informationen können sehr nützlich sein. Sie können protokolliert, zur Implementierung differenzierter Zugriffssteuerungsrichtlinien verwendet oder Backend-Anwendungen zur Verfügung gestellt werden. Wir können jedes dieser Attribute an das Modul auth_request exportieren, indem wir es bei einer erfolgreichen Antwort (HTTP 204) als zusätzlichen Antwort-Header senden.

Codebeispiel wird geladen…

Wir durchlaufen jedes Attribut der Introspektionsantwort (Zeile 23) und senden es an das Modul „auth_request“ als Antwort-Header zurück. Jedem Header-Namen wird das Präfix „Token-“ vorangestellt, um Konflikte mit Standard-Antwort-Headern zu vermeiden (Zeile 26). Diese Antwort-Header können nun in NGINX-Variablen umgewandelt und in der regulären Konfiguration verwendet werden.

Codebeispiel wird geladen…

In diesem Beispiel wandeln wir das Attribut username in eine neue Variable namens $username um (Zeile 11). Mit der Direktive auth_request_set können wir den Kontext der Antwort auf die Token-Introspektion in den Kontext der aktuellen Anfrage exportieren. Der Antwort-Header für jedes Attribut (vom JavaScript-Code hinzugefügt) ist als $sent_http_token_attribute verfügbar. In Zeile 12 wird dann der Wert von $username als Anfrage-Header eingefügt, der an das Backend weitergeleitet wird. Diese Konfiguration kann für jedes der in der Antwort auf die Token-Introspektion zurückgegebenen Attribute wiederholt werden.

Produktionskonfiguration

Die obigen Code- und Konfigurationsbeispiele sind funktionsfähig und eignen sich für Proof-of-Concept-Tests oder zur Anpassung an einen bestimmten Anwendungsfall. Für den Produktiveinsatz empfehlen wir dringend eine zusätzliche Fehlerbehandlung, Protokollierung und flexible Konfiguration. Eine robustere und ausführlichere Implementierung für NGINX und NGINX Plus finden Sie in unserem GitHub-Repository:

• OAuth-2.0-Token-Introspektion mit NGINX (Festplatten-Caching)
• OAuth-2.0-Token-Introspektion mit NGINX Plus (Schlüssel-Wert-Caching)

Zusammenfassung

In diesem Blogbeitrag haben wir gezeigt, wie das NGINX-Modul „auth_request“ in Verbindung mit dem JavaScript-Modul verwendet wird, um bei Clientanfragen eine OAuth-2.0-Token-Introspektion durchzuführen. Darüber hinaus haben wir diese Lösung um Caching erweitert und Attribute aus der Introspektionsantwort zur Verwendung in der NGINX-Konfiguration extrahiert.

Wir haben außerdem beschrieben, wie der Schlüssel-Wert-Speicher von NGINX Plus als verteilter Cache für Introspektionsantworten verwendet werden kann, der sich für Produktionsbereitstellungen in einem Cluster aus NGINX Plus-Instanzen eignet.

Testen Sie die OAuth-2.0-Token-Introspektion mit NGINX Plus selbst – starten Sie noch heute Ihre kostenlose 30-Tage-Testversion oder kontaktieren Sie uns, um Ihre Anwendungsfälle zu besprechen.

Über den Autor

Liam CrillySenior Director, Produktmanagement

Weitere Blogbeiträge von Liam Crilly