OTOBO Kerberos SSO – Single Sign-On with Active Directory

Introduction

Kerberos SSO (Single Sign-On) enables seamless login for your agents 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 standard configuration is replaced by a Kerberos-enabled one :contentReference[oaicite:0]{index="0"}.
This follows the proven procedure 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 various OTOBO versions.

Differences from other systems

Although OTOBO and Znuny are functionally very similar (both originate from the original OTRS project), there are the following fine-tuned 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, while Znuny provides a similarly named znuny_nginx-kerberos.conf.template.
• Versioning: OTOBO 11.x introduces extended SSO parameters (“KerberosAdminServer”, “KerberosDefaultDomain”) that 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 records:
   • An A-Record for your OTOBO FQDN (no CNAME!), e.g., otobo.example.com → 192.0.2.10.
   • Reverse lookup for the hostname so that Kerberos SPN resolutions work.

1. Active Directory User and SPN

1.1 Create user

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

• Capitalization 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:

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:

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:

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 to be compatible with your NGINX release (extras.getpagespeed.com).

2.2 Configuration in the runtime 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: 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

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:

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

Activate in the main .env:

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:

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

2. Add the Kerberos variables:

   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:

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 ensures REMOTE_USER is correctly interpreted as a login (doc.otobo.de).

5.2 Activation in the Admin Interface

• System Configuration:

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

• Kernel/Config -> Run 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
• Add 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

   docker logs otobo_nginx_1 -f

2. Enter the container

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

3. Get SPN token

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

4. Test keytab

   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

• Separate keytab: Never reuse the LDAP sync service account; avoid password collisions.
• Least Privilege: Assign 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: Automatically monitor Kerberos tickets using tools like klist and kvno.

---

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

---

Sources:

• rotheross/otobo-nginx-kerberos-webproxy on Docker Hub (hub.docker.com)
• SPNEGO HTTP Auth NGINX Module (stnoonan) (extras.getpagespeed.com)
• Official OTOBO Installation Docs (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 Developer and Administrator Manuals
• Microsoft Docs: ktpass.exe (community.znuny.org)
• Mozilla MDN: SPNEGO in Firefox (doc.otobo.de)
• NGINX Docs: dynamic modules (extras.getpagespeed.com)

Frequently asked questions

How does Kerberos SSO benefit OTOBO agents and what is its underlying mechanism in a Docker environment?

Kerberos Single Sign-On (SSO) significantly enhances the login experience and security for OTOBO agents by enabling seamless authentication via Active Directory. This eliminates the need for agents to manually enter passwords, as their credentials are not transmitted in plain text, thereby bolstering security. In a Docker-based OTOBO installation, NGINX functions as a web proxy, leveraging the SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) module. This module is initially compiled within a dedicated "builder" container, ensuring compatibility with the NGINX release. Subsequently, the dynamically generated ngx_http_auth_spnego_module.so is transferred to the active NGINX container, and the standard NGINX configuration is replaced with a Kerberos-enabled version. This process adheres to a clear separation between build and runtime stages, which is a proven procedure in official OTOBO Docker projects.

Quellen

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

What are the critical prerequisites for successfully implementing Kerberos SSO with OTOBO Docker, especially regarding DNS?

Successful implementation of Kerberos SSO with OTOBO Docker requires several key prerequisites. Firstly, you must have an existing Active Directory environment with Kerberos (including a configured Realm and Key Distribution Center, KDC). Secondly, a functional OTOBO Docker setup is essential, ideally following the official installation guidelines. Crucially, DNS records play a vital role: you need an A-Record for your OTOBO Fully Qualified Domain Name (FQDN), such as otobo.example.com, which points directly to the OTOBO server's IP address (e.g., 192.0.2.10). It is important to note that a CNAME record is not suitable for Kerberos authentication. Additionally, reverse lookup for the hostname must be correctly configured to ensure that Kerberos Service Principal Name (SPN) resolutions work as expected. These precise DNS configurations are fundamental for the proper functioning of Kerberos ticket validation.

Quellen

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

What specific differences should I be aware of when configuring Kerberos SSO for OTOBO compared to Znuny?

While OTOBO and Znuny share a common origin from the OTRS project and are functionally similar, there are distinct differences in their Kerberos SSO configurations. These include:

• Configuration Paths: OTOBO typically utilizes /opt/otobo-docker/nginx-conf/krb5.conf as its default path for the Kerberos configuration file, whereas Znuny installations commonly rely on /opt/znuny/nginx-conf/krb5.conf.
• Template Files: The NGINX template files used for Kerberos integration also vary. OTOBO provides a file named otobo_nginx-kerberos.conf.template, while Znuny uses a similarly structured znuny_nginx-kerberos.conf.template. These templates exhibit minor differences in their naming conventions and placeholder syntax.
• Versioning and Parameters: OTOBO 11.x introduces enhanced SSO parameters, specifically "KerberosAdminServer" and "KerberosDefaultDomain", which are not available in Znuny 6.x. This means newer OTOBO versions offer more refined control over Kerberos settings.

Quellen

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

What are the key steps for preparing Active Directory and generating the necessary Kerberos keytab for OTOBO SSO?

Preparing Active Directory and generating the Kerberos keytab for OTOBO SSO involves a few critical steps. First, you must create a dedicated service account in your Active Directory. It is imperative that the UserPrincipalName (UPN) for this account is formatted precisely as HTTP/otobo.example.com, with HTTP/ in uppercase, as Kerberos expects this specific prefix. Additionally, the password for this service account should not contain special characters such as & to avoid potential issues. Second, to generate the SPN and Keytab, log in to a Domain Controller with administrative privileges and use the ktpass.exe command-line tool. The command requires parameters like -princ (SPN with realm in uppercase), -mapUser (the SAM account name), -crypto All, -pass (the service user's password), -ptype KRB5_NT_PRINCIPAL, and -out (the desired path for the krb5.keytab file). Finally, after the keytab is generated, you must securely transfer the krb5.keytab file from the Domain Controller to your Docker host, placing it in the /opt/otobo-docker/nginx-conf/ directory, where the NGINX container can access it for authentication purposes.

Quellen

• OTOBO Kerberos SSO – Single Sign-On with Active Directory
• sso-kerberos.rst - RotherOSS/doc-otobo-installation - GitHub

How is the NGINX SPNEGO module built and integrated into the OTOBO Docker runtime environment?

The NGINX SPNEGO module is integrated into the OTOBO Docker environment through a two-stage Docker build process. The build stage, typically named builder-for-kerberos, starts from a base NGINX image and installs essential development packages like gcc, libc-dev, make, libkrb5-dev, and wget. It then downloads both the NGINX source code and the spnego-http-auth-nginx-module source. The NGINX source is configured with --with-compat and --add-dynamic-module to include the SPNEGO module, which is subsequently compiled into a dynamic module file, ngx_http_auth_spnego_module.so. In the runtime container, otobo-nginx-kerberos-webproxy, this pre-compiled ngx_http_auth_spnego_module.so is copied from the builder stage into the /usr/lib/nginx/modules directory. Additionally, necessary Kerberos client packages such as krb5-user are installed. The final step involves inserting a load_module directive into the NGINX configuration (/etc/nginx/nginx.conf), typically on line 4, to dynamically load the SPNEGO module, thereby enabling Kerberos authentication capabilities within the NGINX web proxy.

Quellen

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

After setting up Active Directory and NGINX, what final OTOBO-specific configurations are required to enable Kerberos SSO?

Once Active Directory and NGINX are configured, several OTOBO-specific adjustments are necessary to fully enable Kerberos SSO. First, you need to manage Docker Volumes and NGINX Templates. This involves creating a custom Docker volume, copying the otobo_nginx.conf.template into it, and then updating your docker-compose.yml to mount this custom volume. Crucially, your .env file must be adjusted by backing up the existing one, copying the _https_kerberos template, and adding specific Kerberos variables such as OTOBO_NGINX_KERBEROS_KEYTAB, OTOBO_NGINX_KERBEROS_REALM, OTOBO_NGINX_KERBEROS_KDC, OTOBO_NGINX_KERBEROS_ADMIN_SERVER, and OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN. Remember to transfer any existing SSL certificates and database passwords from your old .env backup. Second, within OTOBO's internal configuration, you must modify the Kernel/Config.pm file. Here, you should comment out any existing LDAP or database authentication modules and add the following lines: $Self->{AuthModule} = 'Kernel::System::Auth::HTTPBasicAuth'; and $Self->{'AuthModule::HTTPBasicAuth::ReplaceRegExp'} = '^(.+?)@.+?$';. This ensures that OTOBO correctly interprets the REMOTE_USER variable provided by NGINX as the agent's login. Finally, activate the HTTPBasicAuth module in the OTOBO Admin Interface under System Configuration by setting Customer::AuthModule to HTTPBasicAuth.

Quellen

• OTOBO Kerberos SSO – Single Sign-On with Active Directory
• sso-kerberos.rst - RotherOSS/doc-otobo-installation - GitHub