Anbinden eines Identity Providers

Über einen Reverse Proxy wie OpenResty kann mittels OpenID Connect/OAuth2 ein Identity Provider wie Keycloak zur Authentifizierung an yuuvis® RAD gateway angebunden werden.

Installation und Konfiguration von OpenResty für ein solches Szenario mit Keycloak sind hier in Grundzügen beschreiben.

Installation von OpenResty

OpenResty kann in eine Docker-Umgebung als Service integriert werden oder direkt unter Windows installiert werden.

OpenResty als Docker Service

Die Installation erfolgt mit folgenden Schritten:

• Ein Verzeichnis für die Konfigurationsdatei von OpenResty anlegen.

  Der Pfad darf keine Leerzeichen enthalten. Beispiel: C:\openresty

• Folgende Docker-Befehle über die Eingabeaufforderung ausführen:

  • OpenResty-Container erstellen:

    docker create --name openresty -p 80:80
    -v C:\openresty:/etc/nginx/conf.d docker.yuuvis.org/library/openresty

    Beide Portangaben müssen identisch sein und dem Port für OpenResty aus der Datei openresty.conf entsprechen.

    In den Container kopieren Sie für die Konfiguration die angepasste Datei openresty.conf.

  • OpenResty-Container starten:

    docker start openresty

  • Container prüfen:

    docker container list -a

    Der Container muss mit dem Status Up angezeigt werden.

OpenResty unter Windows

Die Installation erfolgt mit folgenden Schritten:

• Download von OpenResty für Windows und entpacken des Archivs auf der C-Partition.

  Empfehlung: Installieren Sie OpenResty auf dem Host von yuuvis® RAD gateway.

• Download der folgenden lua-Pakete und Speichern im OpenResty-Verzeichnis \lualib\resty\:

  • https://github.com/cdbattags/lua-resty-jwt/tree/master/lib/resty

  • https://github.com/ledgetech/lua-resty-http/tree/master/lib/resty

  • https://github.com/bungle/lua-resty-session/tree/master/lib/resty

  • https://github.com/jkeys089/lua-resty-hmac/tree/master/lib/resty

  • https://github.com/zmartzone/lua-resty-openidc/tree/master/lib/resty

• Anpassen der Konfigurationsdatei nginx.conf aus dem OpenResty-Verzeichnis \conf\:

  • Löschen des Abschnitts <server> und ersetzen durch folgenden Eintrag:

    include C:\<OpenResty-Installation>\conf\openresty.conf;

    Die Konfigurationsdatei openresty.conf wird nach der Anpassung in dieses Verzeichnis kopiert.

• Starten von OpenResty aus dem Installationsverzeichnis über die Kommandozeile:
  start nginx

• Prüfen ob OpenResty läuft: über den Taskmanager oder über die Kommandozeile:
  tasklist -fi "imagename eq nginx.exe"

Konfiguration von OpenResty

Die Konfiguration erfolgt über die Datei openresty.conf, die zum Download bereit steht. Die Datei muss angepasst und danach in die entsprechenden Verzeichnisse kopiert werden: in den Container für OpenResty als Docker Service oder in das Verzeichnis \conf\ der Windows-Installation.

Neben Platzhaltern, die ersetzt werden müssen, enthält die Datei weitere Parameter, die optional angepasst oder erweitert werden können. Informationen dazu finden Sie in den Dokumentationen von Nginx und OpenResty.

Platzhalter und Parameter in der Konfigurationsdatei

Platzhalter	Funktion
listen ${port};	Port, über den OpenResty Aufrufe übernimmt. OpenResty erwartet als Standard auch bei Änderung, dass der Ports 80 frei ist.
proxy_pass ${gateway‑url};	Root-URL von yuuvis® RAD gateway. Alle eingehenden Aufrufe von OpenResty werden an diese Adresse weitergeleitet.
${header-name}	Header-Name entsprechend der HTTP-Header-Konfiguration für yuuvis® RAD gateway.
${discovery-url}	URL, über die OpenResty die Konfiguration des Identity Providers erreicht.
${client-id} ${client-secret}	Client ID und Secret aus der Client-Konfigration des Identity Providers
${user-field}	Parameter der Benutzerbezeichnung, dessen Wert zur Anmeldung an yuuvis® RAD gateway übermittelt wird. In der yuuvis® RAD-Benutzerverwaltung muss ein Benutzerkonto mit entsprechendem Namen angelegt sein. Beispiel: preferred_username Der Platzhalter muss an zwei Stellen in der Konfigurationsdatei ersetzt werden.
lua_shared_dict introspection 10m;	Optional: Zeitraum in Minuten, über den Bearer-Tokens für die Authentifizierung im Cache verbleiben.

Konfiguration von yuuvis® RAD gateway

yuuvis® RAD gateway muss für die Authentifizierung per HTTP-Header konfiguriert werden.

Dazu muss die Konfigurationsdatei gateway-prod.yml um folgende Zeile erweitert werden:

authentication.filter.header.name: 'X-User'

Zusätzlich notwendig sind folgende Einträge in der Konfigurationsdatei gateway-prod.yml:

  routing.logoutSuccessRedirect: '/restylogout'
  authentication.filter.oauth2: true

Ebenfalls notwendig ist folgender Eintrag in der Konfigurationsdatei gateway-prod.yml:

  server.forward-headers-strategy: NATIVE

Ist ein Reverse Proxy vor yuuvis® RAD gateway eingerichtet, dann fügt er seine eigenen Adress-Bestandteile als 'X-FORWARDED-***' Header ein. Diese Angaben ignoriert yuuvis® RAD gateway in der Standardeinstellung, weil davon ausgegangen wird, dass yuuvis® RAD gateway selber direkt aufgerufen wird.
Wenn yuuvis® RAD gateway in der Standardeinstellung diese Angaben zu 'X-FORWARDED-***' verarbeiten würde, könnte das eine Angriffsmöglichkeit durch einen entsprechend manipulierten Request bieten, da eigene Redirects um die aus den Forwarded-Parametern ermittelten Angaben erweitert oder ersetzt werden.
Wenn kein Reverse-Proxy eingesetzt wird und yuuvis® RAD gateway nur direkt angesprochen wird, sollte dieser Eintrag nicht konfiguriert werden.

 

Weiter notwendig sind folgende Einstellungen in der Konfigurationsdatei application-prod.yml aus dem Verzeichnis \config von yuuvis® RAD service-manager:

  server.max-http-header-size: 1MB
  server.tomcat.max-http-header-size: 1048576

Konfiguration für yuuvis® RAD agent

Falls yuuvis® RAD agent in Umgebungen mit Identity Provider und OpenID Connect/OAuth2 eingesetzt wird, benötigen Sie zur Installation einen entsprechenden Eintrag in der Konfigurationsdatei connections.json und eine zusätzliche Konfigurationsdatei mit den Verbindungsdaten zum Identity Provider.