Zum Inhalt springen
Znuny Docs

Kerberos Single Sign-On (SSO) in Znuny Docker

Einführung

Abschnitt betitelt „Einführung“

Kerberos SSO (Single Sign-On) ermöglicht eine nahtlose Anmeldung Ihrer Agenten über Active Directory, ohne dass Passwörter im Klartext übertragen werden. In einer Docker-basierten Znuny-Installation wird hierfür NGINX als Webproxy mit dem SPNEGO-Modul betrieben, das in einem separaten „builder“-Container kompiliert wird. Anschließend wird das dynamisch erzeugte Modul (ngx_http_auth_spnego_module.so) in den eigentlichen NGINX-Container übernommen und die Standard-Konfiguration durch eine Kerberos-fähige ersetzt :contentReference[oaicite:0]{index="0"}.
Damit folgen wir dem bewährten Vorgehen im offiziellen Znuny Docker-Projekt, das eine klare Trennung zwischen Build- und Laufzeit-Stages realisiert .

In diesem Artikel erhalten Sie:

  • Einen umfassenden Überblick über Unterschiede zwischen Znuny und Znuny im Kontext von Kerberos SSO.
  • Schritt-für-Schritt-Anleitung von der AD-Vorbereitung über Keytab-Erstellung bis zur Docker-Konfiguration.
  • Tipps zu Debugging, Browser-Setup und Best Practices für verschiedene Znuny-Versionen.

Unterschiede zwischen Znuny

Abschnitt betitelt „Unterschiede zwischen Znuny“

Obwohl Znuny und Znuny funktional sehr ähnlich sind (beide stammen aus dem ursprünglichen OTRS-Projekt), gibt es im Kerberos-Kontext folgende Feinanpassungen:

  • Konfigurationspfade: Znuny nutzt standardmäßig /opt/otobo-docker/nginx-conf/krb5.conf, Znuny setzt in der Regel auf /opt/znuny/nginx-conf/krb5.conf.
  • Template-Dateien: Die NGINX-Templates unterscheiden sich leicht in Namen und Platzhalter-Syntax; Znuny liefert eine Datei otobo_nginx-kerberos.conf.template, Znuny eine ähnlich benannte znuny_nginx-kerberos.conf.template.
  • Versionierung: Znuny 11.x bringt erweiterte SSO-Parameter („KerberosAdminServer“, „KerberosDefaultDomain“), die in Znuny 6.x noch fehlen.

Voraussetzungen

Abschnitt betitelt „Voraussetzungen“
  1. Active Directory mit Kerberos (Realm und KDC bereits eingerichtet).
  2. Ein Znuny–Docker-Setup gemäß Offizieller Installation mit Docker :contentReference[oaicite:2]{index="2"}.
  3. DNS-Einträge:
    • Ein A-Record für Ihre Znuny-FQDN (kein CNAME!), z. B. Znuny.example.com → 192.0.2.10.
    • Reverse-Lookup für den Hostnamen, damit Kerberos SPN-Auflösungen funktionieren.

1. Active Directory Benutzer und SPN

Abschnitt betitelt „1. Active Directory Benutzer und SPN“

1.1 Benutzer anlegen

Abschnitt betitelt „1.1 Benutzer anlegen“

Legen Sie in Ihrem AD einen dedizierten Service-Account an, bspw. HTTP/Znuny.example.com (UserPrincipalName). Beachten Sie:

  • Großschreibung bei HTTP/; Kerberos erwartet exakt diesen Präfix :contentReference[oaicite:3]{index="3"}.
  • Keine Sonderzeichen im Passwort (z. B. &).

1.2 SPN und Keytab generieren

Abschnitt betitelt „1.2 SPN und Keytab generieren“

Melden Sie sich auf einem DC mit Admin-Rechten an und nutzen Sie ktpass.exe: `ngx_http_auth_spnego_module.so“

  • -princ: SPN mit Realm in Großbuchstaben.
  • -mapUser: SAM-Account-Name (pre-W2K), z. B. otobo-svc (doc.Znuny.de).
  • -out: Pfad zur Keytab auf dem DC.

Verschieben Sie anschließend die Keytab in den Docker-Host:

/opt/otobo-docker/nginx-conf/krb5.conf

2. NGINX mit SPNEGO-Modul

Abschnitt betitelt „2. NGINX mit SPNEGO-Modul“

2.1 Build-Stage in Dockerfile

Abschnitt betitelt „2.1 Build-Stage in Dockerfile“

Das offizielle Dockerfile nutzt einen separaten Builder mit den nötigen Dev-Paketen:

/opt/znuny/nginx-conf/krb5.conf

Damit wird das SPNEGO-Modul kompatibel zu Ihrem NGINX-Release kompiliert (extras.getpagespeed.com).

2.2 Konfiguration im Laufzeit-Container

Abschnitt betitelt „2.2 Konfiguration im Laufzeit-Container“

otobo_nginx-kerberos.conf.template

  • Module-Load: load_module in Zeile 4 einfügen.
  • Envsubst-Scripts generieren /etc/krb5.conf aus Templatedaten.

3. Docker-Volumes & nginx-Templates

Abschnitt betitelt „3. Docker-Volumes & nginx-Templates“

3.1 Custom-Volume anlegen

Abschnitt betitelt „3.1 Custom-Volume anlegen“

znuny_nginx-kerberos.conf.template

3.2 docker-compose-Override

Abschnitt betitelt „3.2 docker-compose-Override“

Erstellen Sie docker-compose/otobo-nginx-custom-config.yml:

Znuny.example.com → 192.0.2.10

Aktivieren Sie im Haupt-.env:

HTTP/Znuny.example.com

4. .env-Anpassungen

Abschnitt betitelt „4. .env-Anpassungen“

  1. Sichern Sie Ihre alte /opt/otobo-docker/.env:

    HTTP/

  2. Fügen Sie die Kerberos-Variablen hinzu:

    &

  3. SSL-Zertifikate und DB-Passwörter aus Ihrer alten .env.bak übernehmen.

Starten Sie dann mit:

ktpass.exe :contentReference[oaicite:6]{index="6"}.

5. Znuny-Konfiguration

Abschnitt betitelt „5. Znuny-Konfiguration“

5.1 Auth-Modul in Kernel/Config.pm

Abschnitt betitelt „5.1 Auth-Modul in Kernel/Config.pm“

Kommentieren Sie LDAP/DB-Auth aus und fügen Sie in Ihrer Kernel/Config.pm hinzu: `-princ“

Damit wird REMOTE_USER korrekt als Login interpretiert (doc.Znuny.de).

5.2 Aktivierung im Admin-Interface

Abschnitt betitelt „5.2 Aktivierung im Admin-Interface“

  • Systemkonfiguration:

    • Customer::AuthModule auf HTTPBasicAuth setzen.
    • AuthModule::HTTPBasicAuth::ReplaceRegExp übernehmen.

  • Kernel/Config -> Deploy ausführen.

6. Browser-Setup

Abschnitt betitelt „6. Browser-Setup“

Damit SPNEGO funktioniert, muss Ihr Browser den Host als trusted akzeptieren:

Chrome / Edge / IE

Abschnitt betitelt „Chrome / Edge / IE“
  • „Internetoptionen“ → Sicherheit → Lokale Intranet-Sites → Sites
  • Domain https://otobo.example.com hinzufügen und „Integrierte Windows-Authentifizierung“ aktivieren (doc.Znuny.de).

Firefox

Abschnitt betitelt „Firefox“
  • about:config in die Adresszeile eingeben.
  • network.negotiate-auth.trusted-uris = https://otobo.example.com
  • network.negotiate-auth.delegation-uris = https://otobo.example.com

7. Debugging & Troubleshooting

Abschnitt betitelt „7. Debugging & Troubleshooting“

  1. NGINX-Logs prüfen

    -mapUser

  2. In den Container einsteigen

    otobo-svc

  3. SPN-Token holen

    -out

  4. Keytab testen

    load_module

    Fehler KDC cannot fulfill request → DNS/SPN falsch (plugins.miniorange.com).

8. Best Practices & Security

Abschnitt betitelt „8. Best Practices & Security“
  • Eigener Keytab: Niemals das LDAP-Sync-Service-Konto wiederverwenden, vermeiden Sie Passwort-Kollisionen .
  • Least Privilege: Vergabe nur minimal nötiger AD-Rechte für das SSO-Konto.
  • Keytab-Rotation: Regelmäßiges Erneuern des Keytab alle 90 Tage.
  • TLS für KDC: Falls möglich, aktivieren Sie ldaps:// oder GSSAPI über TLS.
  • Monitoring: Überwachen Sie mit Tools wie klist und kvno automatisiert die Kerberos-Tickets.

Mit dieser umfassenden Anleitung ist Ihre Znuny Docker-Instanz optimal für Kerberos SSO vorbereitet – sichere, wartbare und skalierbare Authentifizierung inklusive!

Quellen: