Pular para conteúdo

Troubleshooting — autenticação

Respostas do login

HTTP Mensagem Causa
401 usuário ou senha inválidos senha errada (local), ou todos os diretórios falharam (o motivo por diretório vai para a auditoria em login_failed.detail.errors)
423 usuário temporariamente bloqueado por tentativas inválidas security.lockout_attempts falhas seguidas. Aguarde lockout_minutes ou desbloqueie
403 usuário desativado conta inativa
403 nenhum grupo do usuário está mapeado para um papel LDAP: nenhum grupo mapeado e sem papel padrão
403 usuário do diretório não provisionado na plataforma auto_provision desligado e usuário inexistente
409 já existe um usuário local com este nome conflito entre um usuário local e um de diretório com o mesmo nome
401 sessão inválida ou expirada / token de API inválido ou expirado access token vencido (a SPA renova sozinha) ou token de API revogado/expirado

Consulte Auditoria, ação login_failed: o detalhe traz o motivo e se a conta foi bloqueada.

LDAP / AD

Use Diretórios › Testar com um usuário:

Passo que falha Causa provável Ação
bind falhou: invalidCredentials DN ou senha da conta de serviço confira o DN completo (CN=…,OU=…), não só o login
erro de comunicação com o diretório: … certificate verify failed CA não confiável cole a CA em PEM no campo Certificado da CA ou ajuste Validar certificado
socket connection error / timeout porta, firewall, DNS teste openssl s_client -connect dc01:636 a partir do container da API
usuário de teste não encontrado com o filtro configurado filtro ou Base DN o filtro precisa conter {username}; a Base DN deve incluir a OU do usuário
filtro de usuário retornou mais de um resultado filtro amplo demais inclua objectClass e o atributo único
login ok, mas sem permissões grupo não mapeado o mapeamento aceita o DN completo ou só o CN. O teste lista os grupos diretos; aninhados exigem nested_groups (AD)
grupos aninhados não reconhecidos (OpenLDAP) memberOf não tem os grupos indiretos a regra recursiva só existe no AD. Mapeie os grupos diretos

Papéis de origem diretório são recalculados a cada login: removido do grupo no AD, o usuário perde o papel no próximo login (sessões abertas valem até expirar).

Recuperar acesso de administrador

# compose (produção)
docker compose exec api quantix reset-admin --username admin
# laboratório
docker compose -f docker-compose.lab.yml exec api quantix reset-admin
# Kubernetes
kubectl -n quantix exec deploy/qv-quantix-vision-api -- quantix reset-admin

O comando gera uma senha temporária (impressa no terminal), torna a conta local e ativa, remove o bloqueio e exige troca no próximo login. Com security.local_auth_enabled desligado, superadministradores locais continuam podendo entrar.

Note

quantix reset-admin funciona para qualquer usuário existente (--username). Para criar o primeiro administrador de novo, apague o usuário e reinicie a API: o bootstrap recria QV_ADMIN_USERNAME com QV_ADMIN_PASSWORD.