OTOBO / Znuny Guide

Português

English
Deutsch
Français
Español
Italiano
Polski
Nederlands

Português

English
Deutsch
Français
Español
Italiano
Polski
Nederlands

Introdução ​

O Kerberos SSO (Single Sign-On) permite um login contínuo para seus agentes através do Active Directory, sem a necessidade de transmitir senhas em texto puro. Em uma instalação OTOBO baseada em Docker, o NGINX é usado como um proxy web com o módulo SPNEGO, que é compilado em um contêiner "builder" separado. Em seguida, o módulo gerado dinamicamente (ngx_http_auth_spnego_module.so) é transferido para o contêiner NGINX real e a configuração padrão é substituída por uma compatível com Kerberos :contentReference[oaicite:0]{index=0}. Seguimos as melhores práticas do projeto oficial OTOBO Docker, que implementa uma clara separação entre os estágios de build e de execução.

Neste artigo, você receberá:

  • Uma visão geral abrangente das diferenças entre OTOBO e Znuny no contexto do Kerberos SSO.
  • Um guia passo a passo, desde a preparação do AD e criação de keytab até a configuração do Docker.
  • Dicas para depuração, configuração de navegador e melhores práticas para diferentes versões do OTOBO.

Diferenças entre OTOBO e Znuny ​

Embora OTOBO e Znuny sejam funcionalmente muito semelhantes (ambos derivam do projeto OTRS original), existem os seguintes ajustes finos no contexto do Kerberos:

  • Caminhos de Configuração: OTOBO usa /opt/otobo-docker/nginx-conf/krb5.conf por padrão, enquanto o Znuny geralmente usa /opt/znuny/nginx-conf/krb5.conf.
  • Arquivos de Template: Os templates do NGINX diferem ligeiramente em nomes e sintaxe de placeholders; OTOBO fornece um arquivo otobo_nginx-kerberos.conf.template, e o Znuny um arquivo com nome semelhante znuny_nginx-kerberos.conf.template.
  • Versionamento: OTOBO 11.x traz parâmetros SSO estendidos ("KerberosAdminServer", "KerberosDefaultDomain"), que ainda faltam no Znuny 6.x.

Pré-requisitos ​

  1. Active Directory com Kerberos (Realm e KDC já configurados).
  2. Um Setup Docker do OTOBO conforme Instalação Oficial com Docker :contentReference[oaicite:2]{index=2}.
  3. Registros DNS:
    • Um registro A para o seu FQDN do OTOBO (não um CNAME!), por exemplo, otobo.example.com → 192.0.2.10.
    • Resolução de nome reverso para o hostname, para que as resoluções SPN do Kerberos funcionem.

1. Usuário do Active Directory e SPN ​

1.1 Criar Usuário ​

Crie uma conta de serviço dedicada no seu AD, por exemplo, HTTP/otobo.example.com (UserPrincipalName). Observe:

  • Caixa alta para HTTP/; o Kerberos espera exatamente este prefixo :contentReference[oaicite:3]{index=3}.
  • Sem caracteres especiais na senha (por exemplo, &).

1.2 Gerar SPN e Keytab ​

Faça login em um DC com direitos de administrador e 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 com Realm em caixa alta.
  • -mapUser: Nome da conta SAM (pre-W2K), por exemplo, otobo-svc (doc.otobo.de).
  • -out: Caminho para a keytab no DC.

Em seguida, mova a keytab para o host 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 com Módulo SPNEGO ​

2.1 Estágio de Build no Dockerfile ​

O Dockerfile oficial usa um builder separado com os pacotes de desenvolvimento necessários:

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/

Isso compila o módulo SPNEGO de forma compatível com sua versão do NGINX (extras.getpagespeed.com).

2.2 Configuração no Contêiner de Execução ​

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
  • Carregamento do Módulo: Adicionar load_module na linha 4.
  • Scripts Envsubst geram /etc/krb5.conf a partir de dados de template.

3. Volumes Docker e Templates Nginx ​

3.1 Criar Volume Personalizado ​

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 Override do docker-compose ​

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

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

Ative no .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. Ajustes no .env ​

  1. Faça backup do seu antigo /opt/otobo-docker/.env:

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

  2. Adicione as variáveis 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. Migre os certificados SSL e senhas de banco de dados do seu antigo .env.bak.

Em seguida, inicie com:

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

## 5. Configuração do OTOBO

### 5.1 Módulo de Autenticação em `Kernel/Config.pm`

Comente a autenticação LDAP/DB e adicione em seu `Kernel/Config.pm`:
```perl
$Self->{AuthModule} = 'Kernel::System::Auth::HTTPBasicAuth';
$Self->{'AuthModule::HTTPBasicAuth::ReplaceRegExp'} = '^(.+?)@.+?$';

Isso interpreta corretamente REMOTE_USER como login (doc.otobo.de).

5.2 Ativação na Interface de Admin ​

  • Configuração do Sistema:

    • Defina Customer::AuthModule para HTTPBasicAuth.
    • Migre AuthModule::HTTPBasicAuth::ReplaceRegExp.

  • Kernel/Config -> Execute Deploy.

6. Configuração do Navegador ​

Para que o SPNEGO funcione, seu navegador deve aceitar o host como confiável:

Chrome / Edge / IE ​

  • "Opções da Internet" → Segurança → Sites da Intranet Local → Sites
  • Adicione o domínio https://otobo.example.com e ative a "Autenticação Integrada do Windows" (doc.otobo.de).

Firefox ​

  • Digite about:config na barra de endereços.
  • network.negotiate-auth.trusted-uris = https://otobo.example.com
  • network.negotiate-auth.delegation-uris = https://otobo.example.com

7. Depuração e Solução de Problemas ​

  1. Verificar Logs do NGINX

    bash
    docker logs otobo_nginx_1 -f

  2. Entrar no Contêiner

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

  3. Obter Token SPN

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

  4. Testar Keytab

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

    Erro KDC cannot fulfill request → DNS/SPN incorreto (plugins.miniorange.com).

8. Melhores Práticas e Segurança ​

  • Keytab Dedicada: Nunca reutilize a conta de serviço de sincronização LDAP, evite colisões de senhas.
  • Menor Privilégio: Conceda apenas as permissões mínimas necessárias no AD para a conta SSO.
  • Rotação de Keytab: Renove a keytab regularmente a cada 90 dias.
  • TLS para KDC: Se possível, ative ldaps:// ou GSSAPI sobre TLS.
  • Monitoramento: Monitore as tickets Kerberos de forma automatizada com ferramentas como klist e kvno.

Com este guia abrangente, sua instância OTOBO Docker estará otimamente preparada para Kerberos SSO – autenticação segura, mantenível e escalável incluída!

Fontes: