OTOBO / Znuny Guide

Français

English
Deutsch
Español
Português
Italiano
Polski
Nederlands

Français

English
Deutsch
Español
Português
Italiano
Polski
Nederlands

Introduction ​

Kerberos SSO (Single Sign-On) permet une connexion transparente pour vos agents via Active Directory, sans transfert de mots de passe en clair. Dans une installation OTOBO basée sur Docker, NGINX est utilisé comme proxy web avec le module SPNEGO, compilé dans un conteneur "builder" séparé. Le module généré dynamiquement (ngx_http_auth_spnego_module.so) est ensuite transféré dans le conteneur NGINX réel, et la configuration par défaut est remplacée par une configuration compatible Kerberos :contentReference[oaicite:0]{index=0}. Nous suivons ainsi la meilleure pratique du projet Docker OTOBO officiel, qui réalise une séparation claire entre les étapes de build et d'exécution.

Dans cet article, vous trouverez :

  • Un aperçu complet des différences entre OTOBO et Znuny dans le contexte de Kerberos SSO.
  • Un guide étape par étape, de la préparation AD à la création de keytab en passant par la configuration Docker.
  • Des conseils pour le débogage, la configuration du navigateur et les meilleures pratiques pour différentes versions d'OTOBO.

Différences entre OTOBO et Znuny ​

Bien que OTOBO et Znuny soient fonctionnellement très similaires (tous deux dérivés du projet OTRS original), il existe les ajustements suivants dans le contexte Kerberos :

  • Chemins de configuration : OTOBO utilise par défaut /opt/otobo-docker/nginx-conf/krb5.conf, tandis que Znuny utilise généralement /opt/znuny/nginx-conf/krb5.conf.
  • Fichiers de template : Les templates NGINX diffèrent légèrement par leurs noms et leur syntaxe de placeholders ; OTOBO fournit un fichier otobo_nginx-kerberos.conf.template, et Znuny un fichier nommé de manière similaire znuny_nginx-kerberos.conf.template.
  • Versionnement : OTOBO 11.x apporte des paramètres SSO étendus ("KerberosAdminServer", "KerberosDefaultDomain"), qui sont encore absents dans Znuny 6.x.

Prérequis ​

  1. Active Directory avec Kerberos (Realm et KDC déjà configurés).
  2. Un setup Docker OTOBO conformément à Installation officielle avec Docker :contentReference[oaicite:2]{index=2}.
  3. Enregistrements DNS :
    • Un enregistrement A pour votre FQDN OTOBO (pas de CNAME !), par exemple otobo.example.com → 192.0.2.10.
    • Recherche inversée pour le nom d'hôte, afin que les résolutions SPN Kerberos fonctionnent.

1. Utilisateurs Active Directory et SPN ​

1.1 Créer un utilisateur ​

Créez un compte de service dédié dans votre AD, par exemple HTTP/otobo.example.com (UserPrincipalName). Notez :

  • La casse pour HTTP/ ; Kerberos attend exactement ce préfixe :contentReference[oaicite:3]{index=3}.
  • Pas de caractères spéciaux dans le mot de passe (par exemple &).

1.2 Générer le SPN et la Keytab ​

Connectez-vous à un DC avec des droits d'administrateur et utilisez ktpass.exe :

bash
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 avec le Realm en majuscules.
  • -mapUser : Nom de compte SAM (pre-W2K), par exemple otobo-svc (doc.otobo.de).
  • -out : Chemin vers la keytab sur le DC.

Déplacez ensuite la keytab sur l'hôte Docker :

bash
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 avec module SPNEGO ​

2.1 Étape de build dans Dockerfile ​

Le Dockerfile officiel utilise un builder séparé avec les paquets Dev nécessaires :

dockerfile
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/

Cela compile le module SPNEGO de manière compatible avec votre version NGINX (extras.getpagespeed.com).

2.2 Configuration dans le conteneur d'exécution ​

dockerfile
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
  • Chargement du module : load_module inséré à la ligne 4.
  • Scripts Envsubst génèrent /etc/krb5.conf à partir des données du template.

3. Volumes Docker et templates nginx ​

3.1 Créer un volume personnalisé ​

bash
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 ​

Créez docker-compose/otobo-nginx-custom-config.yml :

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

Activez dans le .env principal :

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

4. Ajustements .env ​

  1. Sauvegardez votre ancien /opt/otobo-docker/.env :

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

  2. Ajoutez les variables Kerberos :

    dotenv
    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. Reprenez les certificats SSL et les mots de passe DB de votre ancien .env.bak.

Démarrez ensuite avec :

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

## 5. Configuration OTOBO

### 5.1 Module d'authentification dans `Kernel/Config.pm`

Commentez l'authentification LDAP/DB et ajoutez dans votre `Kernel/Config.pm` :
```perl
$Self->{AuthModule} = 'Kernel::System::Auth::HTTPBasicAuth';
$Self->{'AuthModule::HTTPBasicAuth::ReplaceRegExp'} = '^(.+?)@.+?$';

Cela interprète correctement REMOTE_USER comme login (doc.otobo.de).

5.2 Activation dans l'interface Admin ​

  • Configuration système :

    • Définir Customer::AuthModule sur HTTPBasicAuth.
    • Reprendre AuthModule::HTTPBasicAuth::ReplaceRegExp.

  • Kernel/Config -> Exécuter Deploy.

6. Configuration du navigateur ​

Pour que SPNEGO fonctionne, votre navigateur doit accepter l'hôte comme fiable :

Chrome / Edge / IE ​

  • "Options Internet" → Sécurité → Sites intranet locaux → Sites
  • Ajoutez le domaine https://otobo.example.com et activez "Authentification Windows intégrée" (doc.otobo.de).

Firefox ​

  • Entrez about:config dans la barre d'adresse.
  • network.negotiate-auth.trusted-uris = https://otobo.example.com
  • network.negotiate-auth.delegation-uris = https://otobo.example.com

7. Débogage et dépannage ​

  1. Vérifier les logs NGINX

    bash
    docker logs otobo_nginx_1 -f

  2. Se connecter au conteneur

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

  3. Obtenir le token SPN

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

  4. Tester la Keytab

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

    Erreur KDC cannot fulfill request → DNS/SPN incorrect (plugins.miniorange.com).

8. Meilleures pratiques et sécurité ​

  • Keytab dédiée : Ne jamais réutiliser le compte de service de synchronisation LDAP, éviter les collisions de mots de passe.
  • Moindre privilège : Attribuer uniquement les droits AD minimaux nécessaires au compte SSO.
  • Rotation des Keytabs : Renouveler régulièrement la keytab tous les 90 jours.
  • TLS pour KDC : Si possible, activer ldaps:// ou GSSAPI sur TLS.
  • Surveillance : Surveiller les tickets Kerberos de manière automatisée avec des outils comme klist et kvno.

Avec ce guide complet, votre instance Docker OTOBO est parfaitement préparée pour Kerberos SSO – authentification sécurisée, maintenable et évolutive incluse !

Sources :