Kerberos Single Sign On in der OTOBO Docker-Installation

Bitte lesen Sie das Kapitel Installation mit Docker und Docker Compose für grundlegende Informationen über die Installation und Konfiguration von OTOBO. Dieses Tutorial geht davon aus, dass OTOBO mit Docker installiert und konfiguriert wurde.

Bemerkung

Im Folgenden sprechen wir von AD (Active Directory). Natürlich funktioniert die Konfiguration von Kerberos auch mit LDAP.

Active Directory User erstellen

Bitte erstellen Sie einen neuen Active Directory Benutzer mit den folgenden Einstellungen und speichern Sie die markierten Einstellungen:

Bemerkung

Please use as Username only this syntax: HTTP/fqdn.from.your.otobo.de. fqdn.from.your.otobo.de needs to be a A-Record DNS entry, not a CNAME! In the next step, it is also possible to use other URLs for OTOBO, they must then point as CNAME to our A-record defined above.

The username part „HTTP/“ should be written in capital letters, as Kerberos expects it that way.

Das Passwort funktioniert nicht zuverlässig mit einigen Sonderzeichen (z.B. ‚&‘).

Sie müssen einen separaten AD-Benutzer anlegen. Sie können nicht jenen benutzen, den Sie bereits für Ihre LDAP/AD-Synchronisation verwenden.

Active Directory User configuration

Active Directory Keytab-Datei erstellen

In the next step, we connect to a domain controller of the Active Directory and open a console (cmd) there with administrator privileges. Now we use the tool `ktpass.exe`to generate the needed keytab file:

ktpass.exe -princ HTTP/otrs32-centos6.otrs.local@OTRS.LOCAL -mapuser OTRS\otrs32-centos6 -crypto All -pass Password -ptype KRB5_NT_PRINCIPAL -out c:\krb5.keytab
  • -princ = HTTP/otrs32-centos6.otrs.local@OTRS.LOCAL -> Picture Number 1+@+Picture Number 2
  • -mapuser = OTRSotrs32-centos6 (Username prä Win 2000) -> -> Picture Number 3++Picture Number
  • -pass = Password from user otrs32-centos6 (Active Directory User)
  • -out = c:/krb5.keytab

Bemerkung

Bitte schreiben Sie die Benutzernamen (@OTRS.LOCAL) immer in Großbuchstaben. Das Passwort darf einige Sonderzeichen nicht enthalten.

Im nächsten Schritt verschieben Sie bitte die Datei krb5.keytab auf den OTOBO-Server:

# Create new directory
docker_admin> mkdir /opt/otobo-docker/nginx-conf

# Move the file krb5.keytab to the new directory (Attention, depending on where you have placed the krb5.conf file, the command below will change.)
docker_admin> mv ?/krb5.keytab /opt/otobo-docker/nginx-conf/krb5.keytab

Create a new volume for your custom nginx configuration

docker volume create otobo_nginx_custom_config
otobo_nginx_custom_config_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_custom_config)
docker create --name tmp-nginx-container rotheross/otobo-nginx-webproxy:latest-10_1 (achtung: Versionsnummer)
docker cp tmp-nginx-container:/etc/nginx/templates /tmp
docker cp tmp-nginx-container:/etc/nginx/templates/otobo_nginx-kerberos.conf.template.hidden $otobo_nginx_custom_config_mp/otobo_nginx.conf.template
docker rm tmp-nginx-container
vim docker-compose/otobo-nginx-custom-config.yml

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

Neue OTOBO .env*-Datei anlegen

First of all we need to move the old file /opt/otobo-docker/.env to .env.tmp and create a new .env file including the kerberos settings.

# Stop OTOBO Container if running
docker_admin>cd /opt/otobo-docker
docker_admin>docker-compose down

# create a backup of the old .env file
docker_admin>mv /opt/otobo-docker/.env /opt/otobo-docker/.env.tmp

# create a new backupfile including kerberos settings
docker_admin>cp /opt/otobo-docker/.docker_compose_env_https_kerberos /opt/otobo-docker/.env

Now copy your existing configuration options to the new .env file (at least OTOBO_DB_ROOT_PASSWORD, OTOBO_NGINX_SSL_CERTIFICATE, OTOBO_NGINX_SSL_CERTIFICATE_KEY) and insert the following Kerberos settings:

# Kerberos keytab OTOBO_NGINX_KERBEROS_KEYTAB=/opt/otobo-docker/nginx-conf/krb5.keytab

# Kerberos config (Important, please comment out this option like here!) # In default configuration the krb5.conf file is generated automatically # OTOBO_NGINX_KERBEROS_CONFIG=/opt/otobo-docker/nginx-conf/krb5.conf

# Kerberos Service Name OTOBO_NGINX_KERBEROS_SERVICE_NAME=HTTP/otrs32-centos6.otrs.local # -> Bild Nummer 1

# Kerberos REALM OTOBO_NGINX_KERBEROS_REALM=ROTHER-OSS.COM -> OTRS.LOCAL # -> Bild Nummer 2

# Active Directory Domain Controller / Kerberos kdc OTOBO_NGINX_KERBEROS_KDC=

# Active Directory Domain Controller / Kerberos Admin Server OTOBO_NGINX_KERBEROS_ADMIN_SERVER=rother-oss.com

# Kerberos Default Domain OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN=otrs.local

OTOBO starten

Nach der initialen Konfiguration von Kerberos starten wir OTOBO erneut:

# Start OTOBO using docker-compose
docker_admin> docker-compose up -d

In OTOBO angeben, dass die Kerberos-Authentifizierung verwendet werden soll

In case you have configured AD-Authentication, de-activate it (e.g. by commenting out the respective lines from your Kernel/Config.pm). The authentication will not take place via LDAP anymore.

To use Kerberos-Authentication take the Kerberos-lines from Kernel/Config/Defaults.pm and put it into you Kernel/Config.pm E.g. these lines could work:

$Self->{AuthModule} = 'Kernel::System::Auth::HTTPBasicAuth';

# In case you need to replace some part of the REMOTE_USER, you can
# use the following RegExp ($1 will be new login).
$Self->{'AuthModule::HTTPBasicAuth::ReplaceRegExp'} = '^(.+?)@.+?$';

Den Browser so konfigurieren, dass er Kerberos SSO versteht

Damit SSO funktioniert, muss der Browser entsprechend konfiguriert werden.

Chrome, Edge, Internet Explorer, etc.

Fügen Sie eine Seite unter „Lokale oder vertrauenswürdige Seiten“ hinzu und aktivieren Sie „Integrierte Windows-Authentifizierung“ (Internetoptionen).

Firefox

„about:config“ in die Adresszeile von Firefox eingeben

und folgende Einstellungen anpassen:

Fehlererkennung und Problembehebung

Sollte das Kerberos SSO nicht funktionieren, überprüfen Sie bitte zunächst, ob der NGINX-Container gestartet ist:

# Check Container
docker_admin> docker ps

Im nächsten Schritt überprüfen Sie bitte die NGINX-Logs auf mehr Informationen:

# Check NGINX logs
docker_admin> docker logs otobo_nginx_1 -f

Sollte NGINX laufen, loggen Sie sich bitte in den NGINX-Container ein und überprüfen Sie alle benötigten Dateien:

# Login to the NGINX Container
docker_admin> docker exec -it otobo_nginx_1 bash

# Now please check if the krb5.conf file exists with your needed values
nginx_root> cat /etc/krb5.conf

# Now please check if the krb5.keytab file exists
nginx_root> cat /etc/krb5.keytab

# If not, please quit from the container and copy the file again using docker
docker_admin> docker cp /opt/otobo-docker/nginx-conf/krb5.keytab otobo_nginx_1:/etc/krb5.keytab

Kerberos Fehlerbehebung

 # Login to the NGINX Container
docker_admin> docker exec -it otobo_nginx_1 bash

Nun sind Sie in der Lage, die Kerberos-Einstellungen auf Fehler zu überprüfen. Beispiele:

env KRB5_TRACE=/dev/stdout kvno HTTP/otrs32-centos6.otrs.local@OTRS.LOCAL
klist -e

kinit -VV -k -t /etc/krb5.keytab HTTP/otrs32-centos6.otrs.local@OTRS.LOCAL

Falls Sie auf das Problem stoßen, dass die Authentifizierung scheinbar funktioniert, der Agent aber noch nicht in der Datenbank ist, funktioniert Ihre Synchronisierung (falls implementiert) möglicherweise nicht. Ein Fehler 52e (Erste Bindung fehlgeschlagen) weist darauf hin, dass mit Ihrem Suchbenutzer etwas nicht stimmt. Dies passiert, wenn Sie denselben Benutzer für die AD-Synchronisierung und als SSO-Benutzer verwenden. Bitte verwenden Sie hierfür separate AD-Benutzer. Um nicht eine neue Schlüsseltabelle erstellen und die oben genannten Schritte wiederholen zu müssen, könnte es einfacher sein, einen neuen Benutzer zur Verwendung in Ihrer AD-Synchronisierung zu erstellen (wahrscheinlich in Ihrer Kernel/Config.pm).

In case SSO is not working properly, make sure: * the user for which it is not working is in Active Directory * the system has to be in the domain * it is properly stated as a trusted page (see ‚Configure Browser to understand Kerberos SSO‘)