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.