OTOBO Kerberos SSO – Single Sign-On mit Active Directory

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 OTOBO-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 OTOBO Docker-Projekt, das eine klare Trennung zwischen Build- und Laufzeit-Stages realisiert .

In diesem Artikel erhalten Sie:

• Einen umfassenden Überblick über Unterschiede zwischen OTOBO 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 OTOBO-Versionen.

Unterschiede zu anderen Systemen

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

• Konfigurationspfade: OTOBO 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; OTOBO liefert eine Datei otobo_nginx-kerberos.conf.template, Znuny eine ähnlich benannte znuny_nginx-kerberos.conf.template.
• Versionierung: OTOBO 11.x bringt erweiterte SSO-Parameter („KerberosAdminServer“, „KerberosDefaultDomain“), die in Znuny 6.x noch fehlen.

Voraussetzungen

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

1. Active Directory Benutzer und SPN

1.1 Benutzer anlegen

Legen Sie in Ihrem AD einen dedizierten Service-Account an, bspw. HTTP/otobo.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

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

ktpass.exe \
 -princ HTTP/otobo.example.com@EXAMPLE.COM \
 -mapUser EXAMPLE\\otobo-svc \
 -crypto All \
 -pass SvcUserPassword \
 -ptype KRB5_NT_PRINCIPAL \
 -out C:\krb5.keytab

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

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

docker_admin> mkdir -p /opt/otobo-docker/nginx-conf
docker_admin> mv /path/to/krb5.keytab /opt/otobo-docker/nginx-conf/krb5.keytab

2. NGINX mit SPNEGO-Modul

2.1 Build-Stage in Dockerfile

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

FROM nginx:mainline AS builder-for-kerberos
...
RUN apt-get update && apt-get install -y gcc libc-dev make libpcre3-dev zlib1g-dev libkrb5-dev wget
WORKDIR /usr/src
RUN wget http://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz \
 && wget https://github.com/stnoonan/spnego-http-auth-nginx-module/archive/${SPNEGO_AUTH_COMMIT_ID}.tar.gz
RUN tar -xzf nginx.tar.gz \
 && tar -xzf spnego-http-auth.tar.gz \
 && cd nginx-${NGINX_VERSION} \
 && ./configure --with-compat ${NGINX_CONFIG} --add-dynamic-module=../spnego-http-auth-nginx-module-${SPNEGO_AUTH_COMMIT_ID_FILE} \
 && make modules \
 && cp objs/ngx_http_auth_spnego_module.so /usr/lib/nginx/modules/

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

2.2 Konfiguration im Laufzeit-Container

FROM nginx:mainline AS otobo-nginx-kerberos-webproxy

COPY --from=builder-for-kerberos /usr/lib/nginx/modules/ngx_http_auth_spnego_module.so /usr/lib/nginx/modules

RUN apt-get update && apt-get install -y krb5-user libpam-krb5 libpam-ccreds krb5-multidev libkrb5-dev

COPY templates/ kerberos/templates
COPY docker-entrypoint.d/21-envsubst-on-krb5-conf.sh /docker-entrypoint.d/
RUN sed -i '4i load_module modules/ngx_http_auth_spnego_module.so;' /etc/nginx/nginx.conf

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

3. Docker-Volumes & nginx-Templates

3.1 Custom-Volume anlegen

docker volume create otobo_nginx_custom_config
mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_custom_config)
docker create --name tmp-nginx rotheross/otobo-nginx-webproxy:latest-11_0
docker cp tmp-nginx:/etc/nginx/templates/otobo_nginx-kerberos.conf.template.hidden $mp/otobo_nginx.conf.template
docker rm tmp-nginx

3.2 docker-compose-Override

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

version: '3.7'
services:
  nginx:
    volumes:
      - otobo_nginx_custom_config:/etc/nginx/config/template-custom

Aktivieren Sie im Haupt-.env:

COMPOSE_FILE=docker-compose.yml:docker-compose/otobo-nginx-custom-config.yml
NGINX_ENVSUBST_TEMPLATE_DIR=/etc/nginx/config/template-custom

4. .env-Anpassungen

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

   mv .env .env.bak
   cp .docker_compose_env_https_kerberos .env

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

   OTOBO_NGINX_KERBEROS_KEYTAB=/opt/otobo-docker/nginx-conf/krb5.keytab
   OTOBO_NGINX_KERBEROS_CONFIG=/opt/otobo-docker/nginx-conf/krb5.conf
   OTOBO_NGINX_KERBEROS_SERVICE_NAME=HTTP/otobo.example.com
   OTOBO_NGINX_KERBEROS_REALM=EXAMPLE.COM
   OTOBO_NGINX_KERBEROS_KDC=dc1.example.com
   OTOBO_NGINX_KERBEROS_ADMIN_SERVER=dc1.example.com
   OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN=example.com

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

Starten Sie dann mit:

docker-compose down && docker-compose up -d
``` :contentReference[oaicite:6]{index=6}.

## 5. OTOBO-Konfiguration

### 5.1 Auth-Modul in `Kernel/Config.pm`

Kommentieren Sie LDAP/DB-Auth aus und fügen Sie in Ihrer `Kernel/Config.pm` hinzu:
```perl
$Self->{AuthModule} = 'Kernel::System::Auth::HTTPBasicAuth';
$Self->{'AuthModule::HTTPBasicAuth::ReplaceRegExp'} = '^(.+?)@.+?$';

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

5.2 Aktivierung im Admin-Interface

• Systemkonfiguration:

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

• Kernel/Config -> Deploy ausführen.

6. Browser-Setup

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

Chrome / Edge / IE

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

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

1. NGINX-Logs prüfen

   docker logs otobo_nginx_1 -f

2. In den Container einsteigen

   docker exec -it otobo_nginx_1 bash
   cat /etc/krb5.conf
   klist -e

3. SPN-Token holen

   env KRB5_TRACE=/dev/stdout kvno HTTP/otobo.example.com@EXAMPLE.COM

4. Keytab testen

   kinit -VV -k -t /etc/krb5.keytab HTTP/otobo.example.com@EXAMPLE.COM

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

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 OTOBO Docker-Instanz optimal für Kerberos SSO vorbereitet – sichere, wartbare und skalierbare Authentifizierung inklusive!

---

Quellen:

• rotheross/otobo-nginx-kerberos-webproxy auf Docker Hub (hub.docker.com)
• SPNEGO HTTP Auth NGINX Module (stnoonan) (extras.getpagespeed.com)
• Offizielle OTOBO Installations-Doku (11.0 SSO Kerberos) (doc.otobo.de)
• GitHub Issue #81: NGINX Kerberos broken (github.com)
• miniOrange Kerberos SSO Guide (plugins.miniorange.com)
• OTOBO Docker Override HTTPS-Kerberos (github.com)
• OTOBO Entwickler- und Administrator-Manuals
• Microsoft Docs: ktpass.exe (community.znuny.org)
• Mozilla MDN: SPNEGO in Firefox (doc.otobo.de)
• NGINX Docs: dynamic modules (extras.getpagespeed.com)

Häufig gestellte Fragen

Was ist Kerberos SSO und wie funktioniert es in einer OTOBO Docker-Umgebung?

Kerberos SSO (Single Sign-On) ermöglicht OTOBO-Agenten eine nahtlose Anmeldung über Active Directory, ohne dass Passwörter im Klartext übertragen werden. In einer Docker-basierten OTOBO-Installation wird hierfür NGINX als Webproxy mit dem SPNEGO-Modul eingesetzt. Das SPNEGO-Modul wird in einem separaten „builder“-Container kompiliert, um die notwendigen Entwicklungs-Pakete zu isolieren. Anschließend wird das dynamisch erzeugte Modul (ngx_http_auth_spnego_module.so) in den eigentlichen NGINX-Laufzeit-Container übernommen. Dort ersetzt es die Standard-Konfiguration durch eine Kerberos-fähige Version, die die Authentifizierung über das Active Directory abwickelt. Dieses Vorgehen folgt dem bewährten Prinzip des offiziellen OTOBO Docker-Projekts, das eine klare Trennung zwischen Build- und Laufzeit-Stages vorsieht, um die Container schlank und sicher zu halten.

Quellen:

• OTOBO Kerberos SSO – Single Sign-On mit Active Directory
• Kerberos Single Sign On in der OTOBO Docker-Installation

Welche spezifischen Unterschiede gibt es bei der Kerberos-SSO-Konfiguration zwischen OTOBO und Znuny?

Obwohl OTOBO und Znuny beide aus dem ursprünglichen OTRS-Projekt stammen und funktional sehr ähnlich sind, gibt es im Kerberos-Kontext einige wichtige Feinanpassungen. Erstens unterscheiden sich die Konfigurationspfade: OTOBO nutzt standardmäßig /opt/otobo-docker/nginx-conf/krb5.conf, während Znuny in der Regel /opt/znuny/nginx-conf/krb5.conf verwendet. Zweitens variieren die Template-Dateien für NGINX leicht in Namen und Platzhalter-Syntax; OTOBO liefert eine Datei namens otobo_nginx-kerberos.conf.template, während Znuny eine ähnlich benannte znuny_nginx-kerberos.conf.template verwendet. Drittens gibt es versionsspezifische Parameter: OTOBO 11.x führt erweiterte SSO-Parameter wie KerberosAdminServer und KerberosDefaultDomain ein, die in älteren Znuny 6.x Versionen noch nicht vorhanden sind. Diese Unterschiede sind bei der Migration oder parallelen Nutzung beider Systeme zu beachten.

Quellen:

• OTOBO Kerberos SSO – Single Sign-On mit Active Directory

Welche Voraussetzungen müssen für die Implementierung von Kerberos SSO in OTOBO erfüllt sein?

Für eine erfolgreiche Implementierung von Kerberos SSO in OTOBO müssen mehrere wichtige Voraussetzungen erfüllt sein. Zunächst benötigen Sie ein funktionierendes Active Directory mit einem bereits eingerichteten Kerberos Realm und Key Distribution Center (KDC). Des Weiteren ist ein OTOBO-Docker-Setup erforderlich, das gemäß der offiziellen Installationsanleitung mit Docker konfiguriert wurde. Ein kritischer Punkt sind die DNS-Einträge: Es muss ein A-Record für Ihre OTOBO-FQDN (Fully Qualified Domain Name) existieren, z. B. otobo.example.com muss auf die IP-Adresse des OTOBO-Hosts zeigen (kein CNAME!). Zusätzlich ist ein Reverse-Lookup für den Hostnamen notwendig, damit die Kerberos Service Principal Name (SPN)-Auflösungen korrekt funktionieren. Ohne diese grundlegenden Komponenten kann die Kerberos-Authentifizierung nicht erfolgreich etabliert werden.

Quellen:

• OTOBO Kerberos SSO – Single Sign-On mit Active Directory
• Kerberos Single Sign On in der OTOBO Docker-Installation

Wie werden der Active Directory Service-Account und die Keytab-Datei für OTOBO Kerberos SSO erstellt?

Für die Einrichtung des Kerberos SSO müssen Sie zunächst einen dedizierten Service-Account in Ihrem Active Directory anlegen. Dieser Account sollte einen UserPrincipalName (UPN) wie HTTP/otobo.example.com haben. Achten Sie darauf, dass der Präfix HTTP/ großgeschrieben ist, da Kerberos dies exakt so erwartet. Zudem sollten Sie im Passwort des Service-Accounts keine Sonderzeichen wie & verwenden, um Probleme zu vermeiden. Nachdem der Benutzer angelegt ist, melden Sie sich auf einem Domain Controller (DC) mit Administratorrechten an und nutzen das Tool ktpass.exe, um den Service Principal Name (SPN) und die Keytab-Datei zu generieren. Das Kommando sieht typischerweise so aus:

ktpass.exe -princ HTTP/otobo.example.com@EXAMPLE.COM -mapUser EXAMPLE\otobo-svc -crypto All -pass SvcUserPassword -ptype KRB5_NT_PRINCIPAL -out C:\krb5.keytab

Hierbei ist -princ der SPN mit dem Realm in Großbuchstaben, -mapUser der SAM-Account-Name (z.B. otobo-svc) und -out der Pfad zur Keytab-Datei auf dem DC. Nach der Erstellung muss die krb5.keytab-Datei in das Verzeichnis /opt/otobo-docker/nginx-conf/ auf dem Docker-Host verschoben werden, damit der NGINX-Container darauf zugreifen kann.

Quellen:

• OTOBO Kerberos SSO – Single Sign-On mit Active Directory
• Kerberos Single Sign On in der OTOBO Docker-Installation

Welche Schritte sind notwendig, um das SPNEGO-Modul in den NGINX-Container zu integrieren und zu konfigurieren?

Die Integration des SPNEGO-Moduls in den NGINX-Container erfolgt in zwei Hauptschritten innerhalb des Dockerfile. Zuerst wird in einer Build-Stage (z.B. FROM nginx:mainline AS builder-for-kerberos) das ngx_http_auth_spnego_module.so Modul kompiliert. Hierfür werden Entwicklungspakete wie gcc, libc-dev, libkrb5-dev und wget installiert, um NGINX mit dem SPNEGO-Modul als dynamisches Modul zu bauen. Das kompilierte Modul wird dann in ein temporäres Verzeichnis kopiert.

In der Laufzeit-Container-Stage (z.B. FROM nginx:mainline AS otobo-nginx-kerberos-webproxy) wird das zuvor kompilierte ngx_http_auth_spnego_module.so Modul aus der Build-Stage in den NGINX-Modulpfad kopiert. Zusätzlich werden Laufzeitabhängigkeiten wie krb5-user installiert. Das Modul wird dann durch Einfügen von load_module modules/ngx_http_auth_spnego_module.so; in die nginx.conf geladen. Für die NGINX-Konfiguration selbst wird ein Custom-Volume (otobo_nginx_custom_config) erstellt. In dieses Volume wird die Kerberos-spezifische NGINX-Template-Datei (otobo_nginx-kerberos.conf.template) kopiert. Abschließend wird in der docker-compose-Override-Datei (docker-compose/otobo-nginx-custom-config.yml) das Volume dem NGINX-Dienst zugewiesen und im Haupt-.env die Variable NGINX_ENVSUBST_TEMPLATE_DIR auf den Pfad des Custom-Volumes gesetzt, damit NGINX die Kerberos-Konfiguration verwendet.

Quellen:

• OTOBO Kerberos SSO – Single Sign-On mit Active Directory
• rotheross/otobo-nginx-kerberos-webproxy - Docker Image

Wie konfiguriere ich die `.env`-Datei und OTOBO selbst für Kerberos SSO?

Nachdem die Keytab-Datei erstellt und NGINX mit dem SPNEGO-Modul vorbereitet wurde, müssen die .env-Datei und die OTOBO-Konfiguration angepasst werden. Zuerst sollten Sie Ihre bestehende /opt/otobo-docker/.env-Datei sichern und dann die Kerberos-spezifische .env-Vorlage (.docker_compose_env_https_kerberos) kopieren. Anschließend fügen Sie die notwendigen Kerberos-Variablen in die .env-Datei ein. Dazu gehören unter anderem:

• OTOBO_NGINX_KERBEROS_KEYTAB=/opt/otobo-docker/nginx-conf/krb5.keytab
• OTOBO_NGINX_KERBEROS_CONFIG=/opt/otobo-docker/nginx-conf/krb5.conf
• OTOBO_NGINX_KERBEROS_SERVICE_NAME=HTTP/otobo.example.com
• OTOBO_NGINX_KERBEROS_REALM=EXAMPLE.COM
• OTOBO_NGINX_KERBEROS_KDC=dc1.example.com
• OTOBO_NGINX_KERBEROS_ADMIN_SERVER=dc1.example.com
• OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN=example.com

Vergessen Sie nicht, SSL-Zertifikats- und Datenbankpasswort-Einstellungen aus Ihrer gesicherten .env.bak zu übernehmen. Nach diesen Anpassungen starten Sie die Docker-Container neu (docker-compose down && docker-compose up -d).

Für die OTOBO-interne Konfiguration müssen Sie in Ihrer Kernel/Config.pm die LDAP/DB-Authentifizierung auskommentieren und das HTTPBasicAuth-Modul aktivieren:

$Self->{AuthModule} = 'Kernel::System::Auth::HTTPBasicAuth';
$Self->{'AuthModule::HTTPBasicAuth::ReplaceRegExp'} = '^(.+?)@.+?$';

Dies stellt sicher, dass OTOBO die vom NGINX-Proxy bereitgestellten Authentifizierungsinformationen korrekt verarbeitet und den Benutzernamen extrahiert.

Quellen:

• OTOBO Kerberos SSO – Single Sign-On mit Active Directory
• Kerberos Single Sign On in der OTOBO Docker-Installation