OTOBO / Znuny Guide

Italiano

English
Deutsch
Français
Español
Português
Polski
Nederlands

Italiano

English
Deutsch
Français
Español
Português
Polski
Nederlands

Introduction ​

Kerberos SSO (Single Sign-On) allows your agents to log in seamlessly via Active Directory without transmitting passwords in plain text. In a Docker-based OTOBO installation, NGINX is used as a web proxy with the SPNEGO module, which is compiled in a separate "builder" container. Subsequently, the dynamically generated module (ngx_http_auth_spnego_module.so) is transferred to the actual NGINX container, and the default configuration is replaced with a Kerberos-enabled one :contentReference[oaicite:0]{index=0}. This follows the best practice in the official OTOBO Docker project, which implements a clear separation between build and runtime stages.

In this article, you will receive:

  • A comprehensive overview of the differences between OTOBO and Znuny in the context of Kerberos SSO.
  • A step-by-step guide from AD preparation and keytab creation to Docker configuration.
  • Tips on debugging, browser setup, and best practices for different OTOBO versions.

Differences Between OTOBO and Znuny ​

Although OTOBO and Znuny are functionally very similar (both originate from the original OTRS project), there are the following fine-tuning adjustments in the Kerberos context:

  • Configuration Paths: OTOBO uses /opt/otobo-docker/nginx-conf/krb5.conf by default, while Znuny typically relies on /opt/znuny/nginx-conf/krb5.conf.
  • Template Files: The NGINX templates differ slightly in names and placeholder syntax; OTOBO provides a file otobo_nginx-kerberos.conf.template, and Znuny provides a similarly named znuny_nginx-kerberos.conf.template.
  • Versioning: OTOBO 11.x includes extended SSO parameters ("KerberosAdminServer", "KerberosDefaultDomain"), which are still missing in Znuny 6.x.

Prerequisites ​

  1. Active Directory with Kerberos (Realm and KDC already set up).
  2. An OTOBO Docker Setup according to Official Installation with Docker :contentReference[oaicite:2]{index=2}.
  3. DNS entries:
    • An A Record for your OTOBO FQDN (no CNAME!), e.g., otobo.example.com → 192.0.2.10.
    • Reverse lookup for the hostname to ensure Kerberos SPN resolutions work.

1. Active Directory User and SPN ​

1.1 Create User ​

In your AD, create a dedicated service account, e.g., HTTP/otobo.example.com (UserPrincipalName). Note:

  • Case sensitivity for HTTP/; Kerberos expects exactly this prefix :contentReference[oaicite:3]{index=3}.
  • No special characters in the password (e.g., &).

1.2 Generate SPN and Keytab ​

Log in to a DC with admin rights and use 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 with Realm in uppercase.
  • -mapUser: SAM account name (pre-W2K), e.g., otobo-svc (doc.otobo.de).
  • -out: Path to the keytab on the DC.

Then, move the keytab to the Docker host:

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 with SPNEGO Module ​

2.1 Build Stage in Dockerfile ​

The official Dockerfile uses a separate builder with the necessary dev packages:

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/

This compiles the SPNEGO module compatibly with your NGINX release (extras.getpagespeed.com).

2.2 Configuration in Runtime Container ​

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
  • Module Load: Insert load_module in line 4.
  • EnvSubst scripts generate /etc/krb5.conf from template data.

3. Docker Volumes & Nginx Templates ​

3.1 Create Custom Volume ​

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 ​

Create docker-compose/otobo-nginx-custom-config.yml:

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

Enable in the main .env:

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

4. .env Adjustments ​

  1. Back up your old /opt/otobo-docker/.env:

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

  2. Add the Kerberos variables:

    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. Transfer SSL certificates and DB passwords from your old .env.bak.

Then start with:

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

## 5. OTOBO Configuration

### 5.1 Auth Module in `Kernel/Config.pm`

Comment out LDAP/DB Auth and add the following to your `Kernel/Config.pm`:
```perl
$Self->{AuthModule} = 'Kernel::System::Auth::HTTPBasicAuth';
$Self->{'AuthModule::HTTPBasicAuth::ReplaceRegExp'} = '^(.+?)@.+?$';

This correctly interprets REMOTE_USER as the login (doc.otobo.de).

5.2 Activation in Admin Interface ​

  • System Configuration:

    • Set Customer::AuthModule to HTTPBasicAuth.
    • Apply AuthModule::HTTPBasicAuth::ReplaceRegExp.

  • Kernel/Config -> Execute Deploy.

6. Browser Setup ​

For SPNEGO to work, your browser must accept the host as trusted:

Chrome / Edge / IE ​

  • "Internet Options" → Security → Local intranet sites → Sites
  • Add the domain https://otobo.example.com and enable "Integrated Windows Authentication" (doc.otobo.de).

Firefox ​

  • Enter about:config in the address bar.
  • network.negotiate-auth.trusted-uris = https://otobo.example.com
  • network.negotiate-auth.delegation-uris = https://otobo.example.com

7. Debugging & Troubleshooting ​

  1. Check NGINX Logs

    bash
    docker logs otobo_nginx_1 -f

  2. Enter the Container

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

  3. Get SPN Token

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

  4. Test Keytab

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

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

8. Best Practices & Security ​

  • Dedicated Keytab: Never reuse the LDAP sync service account; avoid password collisions.
  • Least Privilege: Grant only the minimum necessary AD rights for the SSO account.
  • Keytab Rotation: Regularly renew the keytab every 90 days.
  • TLS for KDC: If possible, enable ldaps:// or GSSAPI over TLS.
  • Monitoring: Use tools like klist and kvno to monitor Kerberos tickets automatically.

With this comprehensive guide, your OTOBO Docker instance will be optimally prepared for Kerberos SSO – including secure, maintainable, and scalable authentication!

Sources: