Benutzerauthentifizierung für bestehende Anwendungen mit OpenID Connect und NGINX Plus

NGINX | 07. September 2016

Liam CrillySenior Director, Produktmanagement

JWT-Unterstützung zur Bereitstellung von SSO für bestehende Anwendungen verwenden

[Redaktion – Dieser Beitrag beschreibt, wie NGINX Plus mit OpenID-Connect-Anbietern verwendet wird, die den impliziten Flow für die Authentifizierung unterstützen. Die Informationen sind technisch korrekt, einige Schritte (wie die Verwendung von cron zum Abrufen öffentlicher Schlüssel) sind aufgrund von Aktualisierungen unserer Referenzimplementierung jedoch nicht mehr erforderlich. Die aktuelle Implementierung finden Sie in unserem GitHub-Repository.

Ab NGINX Plus R15 können Sie NGINX Plus auch als vertrauende Partei im OpenID-Connect-Authorization Code Flow verwenden.]

OAuth 2.0 hat wesentlich dazu beigetragen, die Flexibilität und Benutzerfreundlichkeit bei der Authentifizierung auf Websites und in Anwendungen zu verbessern. Doch trotz des Namens enthält die OAuth 2.0-Spezifikation nur sehr wenige Angaben zur Überprüfung der Identität von Endbenutzern und keinerlei Angaben zu Single Sign-on (SSO). Hier kommt OpenID Connect ins Spiel – es ist im Wesentlichen das fehlende Element, das Identitätsinformationen in OAuth 2.0-Zugriffstoken überträgt.

OpenID-Connect-Identitätstoken entsprechen der JSON-Web-Token-Spezifikation (JWT). JWTs (ausgesprochen „Jot“) sind kompakt, lassen sich einfach übertragen und bieten ein einheitliches Basisschema zur Beschreibung von Identitätsinformationen. Der große Vorteil von JWTs besteht darin, dass sie für nahezu jeden Anwendungsfall im Bereich Identitätsmanagement eingesetzt werden können – von der Authentifizierung von API-Clients bis hin zur Bereitstellung von SSO für Unternehmensanwendungen. Tatsächlich können viele Organisationen, die Google Apps verwenden, Google als Identitätsanbieter nutzen, um SSO für ihre Unternehmensanwendungen bereitzustellen. Die Verwendung von OpenID Connect und JWTs schließt jedoch nicht aus, dass sie auch zur Authentifizierung bei bestehenden Webanwendungen oder zur Bereitstellung von SSO für diese eingesetzt werden.

NGINX Plus R10 und höher bietet native JWT-Unterstützung. Dadurch kann NGINX Plus Tokens validieren und Upstream-Anfragen so mit der Identität des authentifizierten Benutzers versehen, dass die Anwendung sie problemlos verarbeiten kann. In diesem Blogbeitrag zeigen wir, wie sich mit der nativen JWT-Unterstützung in NGINX Plus SSO für bestehende Anwendungen aktivieren lässt, ohne dass Änderungen an den Anwendungen selbst erforderlich sind. Wir verwenden Google als Identitätsanbieter und eine einfache Website als Beispielanwendung. Der End-to-End-Ablauf sieht folgendermaßen aus:

NGINX Plus validiert die Benutzeridentität mithilfe von OAuth 2.0 und OpenID Connect für Google-basiertes SSO

OpenID Connect für Ihre Webanwendung aktivieren

Unser Beispiel besteht aus zwei Komponenten: der NGINX Plus-Konfiguration und der HTML-Anmeldeseite.

NGINX Plus-Konfiguration

Die NGINX Plus-Konfiguration zur Validierung von JWTs ist sehr einfach.

server {    listen 80;
    root /var/www/public_html;

    location /private/ {
        auth_jwt "Google account" token=$cookie_auth_token;
        auth_jwt_key_file /etc/nginx/google_certs.jwk;
    }
}

Der location-Block legt fest, dass alle Anfragen an URLs, die mit /private/ beginnen, authentifiziert werden müssen. Die auth_jwt-Direktive definiert den Authentifizierungsbereich, der bei fehlgeschlagener Authentifizierung (zusammen mit dem Statuscode 401) zurückgegeben wird, sowie die Stelle in der Anfrage, an der NGINX Plus das JWT finden kann. In diesem Fall wird erwartet, dass sich das Token in einem Cookie namens auth_token befindet. Standardmäßig erwartet NGINX Plus, dass Clients das JWT als Bearer Token über den Authorization-Header übermitteln, wie es bei AJAX-Anwendungen und API-Clients üblich ist. Das JWT kann jedoch auch aus anderen HTTP-Headern, Abfragezeichenfolgenargumenten oder – wie in diesem Beispiel – aus einem Cookie abgerufen werden.

Die Direktive „auth_jwt_key_file“ teilt NGINX mit, wie das Signaturelement des JWT validiert werden soll. Durch die Signaturvalidierung wird sichergestellt, dass das JWT von Google ausgestellt und seitdem nicht verändert wurde. Google veröffentlicht seine öffentlichen Schlüssel und aktualisiert sie regelmäßig. Um die Schlüssel stets auf dem neuesten Stand zu halten, verwenden Sie cron(8), um sie stündlich abzurufen, wie in diesem Beispiel für einen crontab-Eintrag.

0 * * * * wget https://www.googleapis.com/oauth2/v3/certs -O /etc/nginx/google_certs.jwk

HTML-basierte Anmeldeseite

Um dieses Beispiel einfach und übersichtlich zu halten, erstellen wir keine vollständige Anwendung. Stattdessen verwenden wir den folgenden einfachen HTML-Code, um eine Anmeldeseite zu erstellen. Die HTML-Datei heißt /var/www/public_html/index.html (dies entspricht dem in der NGINX Plus-Konfiguration definierten Pfad root).

<html>
<head>
    <meta http-equiv="cache-control" content="no-cache" />
    <meta http-equiv="expires" content="0" />
    <title>NGINX OpenID Connect demo</title>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-scope" content="profile email">
    <meta name="google-signin-client_id" content="client-ID.apps.googleusercontent.com"> <script src="/js.cookie.js"></script>
</head>
<body>
    <h2>NGINX OpenID Connect demo</h2>
    <hr/>
    <h3>Login with a Google account then visit the <a href="/private/">private area</a>.</h3>
    <table><tr><td>
    <div class="g-signin2" data-onsuccess="onSignIn" data-theme="dark"></div></td>
    <script>
      function onSignIn(googleUser) {
        var profile = googleUser.getBasicProfile();
        Cookies.set('auth_token', googleUser.getAuthResponse().id_token);
        document.getElementById('google_signout').innerHTML = '<a href="#" onclick="signOut();"><img src="' + profile.getImageUrl() + '" width=32 height=32>Sign out</a>';
      };
      function signOut() {
        var auth2 = gapi.auth2.getAuthInstance();
        auth2.signOut().then(function () {
          Cookies.remove('auth_token');
          document.getElementById('google_signout').innerHTML = '';
        });
      }
    </script>
    <td><div id="google_signout"></div></td>
    </tr></table>
    <hr/>
</body>
</html>

Wir haben zwei wichtige Abhängigkeiten im <head>-Block hervorgehoben.

<meta name="google‑signin‑client_id">-Tag – Wir verwenden die OAuth 2.0 JavaScript API von Google, um die Einwilligung und Authentifizierung von Endnutzern über OAuth 2.0 durchzuführen. Dadurch erhalten wir die Anmeldeschaltfläche und können erkennen, ob wir angemeldet sind oder nicht. Damit unsere Website von Google authentifiziert werden kann, müssen wir eine OAuth 2.0-Client-ID erstellen und diese als content-Attribut für diesen Tag angeben, wobei der Platzhalter client-ID ersetzt wird. Eine Anleitung zum Erstellen einer neuen OAuth 2.0-Client-ID finden Sie im Anhang am Ende dieses Artikels.
<script src="/js.cookie.js">-Tag – Wir benötigen einen Cookie-Parser, der das Identitätstoken aus dem OAuth-2.0-Zugriffstoken extrahieren und ein Cookie erstellen kann, das an die Website gesendet wird. Die Zeile Cookies.set erledigt dies mithilfe der Bibliothek JavaScript Cookie, die über diesen Tag eingebunden wird.

Nachdem diese Komponenten eingerichtet sind, verfügen wir nun über eine öffentliche Startseite mit dem Anmeldemechanismus von Google und einen durch NGINX Plus geschützten privaten Bereich. Beachten Sie, dass wir keine Inhalte für unseren privaten Bereich erstellt haben. Daher ist beim Zugriff darauf ein Fehler vom Typ 404 zu erwarten.

Weiterführende Literatur

Weitere Informationen zu erweiterten JWT-Funktionen finden Sie unter „Authentifizieren von API-Clients mit JWT und NGINX Plus“. Dort wird erläutert, wie authentifizierte Anfragen mit aus dem JWT abgerufenen Benutzeridentitätsinformationen über einen Proxy weitergeleitet, JWT-Claims protokolliert und mehrere Identitätsanbieter unterstützt werden können.

Um die native JWT-Unterstützung in NGINX Plus kennenzulernen, starten Sie noch heute Ihre kostenlose 30‑Tage-Testversion oder kontaktieren Sie uns.

Anhang – Erstellen einer Google OAuth 2.0-Client-ID

[Redaktion – Wir haben uns nach Kräften bemüht, die Benutzeroberfläche der Google APIs zum Zeitpunkt der Veröffentlichung korrekt darzustellen. Da sie jedoch häufig geändert wird, können sich Menüoptionen und deren Positionen jederzeit ändern. Verwenden Sie diese Anleitung als Referenz und passen Sie sie bei Bedarf an die aktuelle Benutzeroberfläche an.]

Rufen Sie das Google APIs-Dashboard unter https://console.developers.google.com/apis/dashboard auf. Welche Seite geöffnet wird, hängt davon ab, ob Sie Google APIs bereits verwendet haben. Möglicherweise müssen Sie ein Konto erstellen, die Nutzungsbedingungen akzeptieren und weitere Schritte ausführen, die in dieser Anleitung nicht beschrieben werden. Der folgende Screenshot zeigt die obere linke Ecke des Dashboards. Klicken Sie auf das Wort rechts neben dem Google APIs-Logo (wenn Sie bereits ein Projekt erstellt haben, wird möglicherweise dessen Name anstelle des Wortes Projekt angezeigt). Wählen Sie Projekt erstellen aus.
Erstellen Sie ein neues Projekt. In diesem Beispiel heißt das neue Projekt „NGINX OpenID“. Nachdem Sie auf die Schaltfläche „Erstellen“ geklickt haben, kann es einige Sekunden dauern, bis eine Benachrichtigung angezeigt wird, dass Ihr Projekt erstellt wurde.
Aktivieren Sie die Google+ API für Ihr Projekt. Sie stellt OAuth 2.0-Authentifizierungs- und Identitätsdienste bereit. (Wenn das API Manager-Dashboard nicht bereits im Hauptbereich des Fensters angezeigt wird, klicken Sie im Navigationsbereich links auf dem Bildschirm auf „Dashboard“.) Um die Google+ API zu aktivieren, klicken Sie zunächst auf die Schaltfläche „ENABLE API“.
Klicken Sie auf „Google+ API“ (im Abschnitt „Social APIs“).
Klicken Sie auf die Schaltfläche „AKTIVIEREN“.
Um Anmeldedaten für Ihr Projekt zu erstellen, klicken Sie links im Navigationsbereich auf Anmeldedaten und anschließend auf die Schaltfläche Anmeldedaten erstellen. Wählen Sie im Drop-down-Menü OAuth-Client-ID aus.
Wählen Sie das Optionsfeld „Webanwendung“ aus. Geben Sie im Feld „Autorisierte JavaScript-Ursprünge“ die URL des Hosts, auf dem NGINX Plus installiert ist, sowie die Portnummer an, die Sie als Parameter für die Direktive „listen“ unter „OpenID Connect für Ihre Webanwendung aktivieren“ angegeben haben (zum Beispiel mydomain.example.com:80). In diesem Beispiel wird localhost verwendet. Sie müssen jedoch den Hostnamen und den Port der tatsächlichen NGINX Plus-Instanz eingeben. Klicken Sie auf die Schaltfläche „Erstellen“ (möglicherweise müssen Sie mehrmals darauf klicken, damit der Erstellungsvorgang gestartet wird).
Das Fenster „OAuth-Client“ wird eingeblendet und zeigt Ihre Client-ID und Ihren Clientschlüssel an. Kopieren Sie die Client-ID in das Attribut content des Tags <meta name="google-signin-client_id"> in Ihrer App (und ersetzen Sie damit den oben hervorgehobenen Platzhalter client-ID). Den Clientschlüssel benötigen Sie nicht.
Klicken Sie auf dem Hauptbildschirm Anmeldedaten auf OAuth-Zustimmungsbildschirm. Geben Sie Ihre E-Mail-Adresse und einen Produktnamen an (alle anderen Felder sind optional).