Anbinden eines Identity Providers

enaio® • 10.10 »

Über einen Reverse Proxy wie OpenResty kann mittels OpenID Connect/OAuth2 ein Identity Provider wie Keycloak zur Authentifizierung für enaio® webclient und enaio® webclient als Desktop-Anwendung an enaio® gateway angebunden werden.

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

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:

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 enaio® gateway. Alle eingehenden Aufrufe von OpenResty werden an diese Adresse weitergeleitet.
${header-name}

Header-Name, der der entsprechenden HTTP-Header-Konfiguration für enaio® gateway entsprechen muss.

 
${discovery-url} URL, über die OpenResty die Konfiguration des Identity Providers erreicht.
${client-id}

${client-secret}

Client ID und Secret aus der Client-Konfiguration des Identity Providers
${user-field}

Parameter der Benutzerbezeichnung, dessen Wert zur Anmeldung an enaio® gateway übermittelt wird.

In der enaio®-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 enaio® gateway

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

Zusätzlich muss die Konfigurationsdatei application-prod.yml von enaio® gateway erweitert werden, um das Ausloggen an das Logout von OpenResty umzuleiten:

proxy:
defaultLogoutRedirect: '/logout'

enaio® gateway wird als Standard mit dem Port 80 installiert. Wird OpenResty, wie empfohlen, auf dem gleichen Host installiert, dann muss für enaio® gateway ein freier Port konfiguriert werden. Läuft OpenResty auf einem anderen Host, dann müssen Anmeldungen, beispielsweise an enaio® webclient, über diesen Host erfolgen.

Anbinden an ein Azure Active Directory

Die Konfiguration von OpenResty muss individuell an jeden Identity Provider angepasst werden, da das OpenID Connect Protokoll Spielräume für Hersteller offenlässt.

Die Dateien openresty-azure-username.conf und openresty-azure-oid.conf enthalten für Azure AD vorkonfigurierte Beispiele, in denen wenige spezifische Parameter angepasst werden müssen. Sie sind für SSL eingestellt und binden Zertifikatsdateien ein. Mit der Datei openresty-azure-username.conf werden voll qualifizierte Benutzernamen wie mustermann@example.onmicrosoft.com an enaio® gateway übergeben, mit der Datei openresty-azure-oid.conf werden die Azure Objekt-IDs an enaio® gateway übergeben.

Folgende Parameter müssen angegeben werden:

set $tenant_id

set $client_id

set $client_secret

 Tenant ID, Client ID und Client Secret angeben
ssl_certificate Pfad und Dateiname der Zertifikatsdatei
ssl_certificate_key Pfad und Dateiname der Schlüsseldatei
proxy_pass Adresse von enaio® gateway mit Port.

Die Datei wird als Standard im Konfigurationsverzeichnis ...\etc\nginx\conf.d\ gespeichert.

Anbindung an Azure Active Directory mit curl testen

Die Systemkonfiguration kann, wie im Folgenden beschrieben, mit curl getestet werden. Dazu wird ein Zugriffs-Token angefordert, welches OpenResty für die Anmeldung benötigt. Die Token-Anfragen enthalten Einträge im JSON-Format, von denen der Wert zum 'access_token' in die Anfrage der enaio® Benutzerinformation eingefügt wird.

Als Standard verlieren Azure AD Zugriff-Token nach einer Stunde ihre Gültigkeit. Es können sowohl für Benutzerkonten als auch für Service-Konten Zugriffs-Tokens angefragt werden.

  • Zugriffs-Token für ein Benutzerkonto anfragen:

    curl -s -k \
    --url "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \
    -d "client_id=<client-id>" \
    -d "client_secret=<client-secret>" \
    -d "username=<user-name>@<tenant-name>.onmicrosoft.com" \
    -d "password=<user-password>" \
    -d "grant_type=password" \
    -d "scope=openid <client-id>/.default"
  • Zugriffs-Token für das Service-Konto des OpenResty Clients anfragen:

    • curl -s -k \
    --url "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \
    -d "client_id=<client-id>" \
    -d "client_secret=<client-secret>" \
    -d "grant_type=client_credentials" \
    -d "scope=openid <client-id>/.default"

  • mit einem Zugriffs-Token an OpenResty anmelden und die enaio® Benutzerinformationen anfragen:

    • curl -s -k \
    --url "https://openresty.example-ag.org/osrest/api/session" \
    -H "Authorization: Bearer <'access_token'-value>"