Pular para o conteúdo principal

Autenticação e segurança

O Libre WebUI usa contas locais com sessões JWT. Uma instalação nova sempre permite inicializar um administrador local. O cadastro público de todas as contas locais ou OAuth posteriores vem fechado.

Configuração inicial​

Quando não há usuários:

  1. O Libre WebUI mostra o fluxo inicial.
  2. A pessoa cria a primeira conta local.
  3. A conta recebe o papel admin.
  4. Cadastros posteriores permanecem fechados até serem explicitamente ativados.

Bancos existentes mantêm seus usuários e papéis.

Contas locais​

O cadastro exige:

  • Nome de usuário
  • Senha entre 12 caracteres e 72 bytes UTF-8, com maiúscula, minúscula e número
  • E-mail opcional

Senhas são armazenadas com hash bcrypt. As rotas de login e cadastro têm limite de frequência.

Aprovação de cadastro​

O cadastro público não concede acesso por si só. Toda conta criada pelo formulário ou por OAuth começa em pending e precisa ser aprovada por um administrador.

A única exceção é a inicialização: a primeira conta real em um banco vazio é criada atomicamente como active com papel admin. Todas as demais aguardam revisão.

O usuário pendente vê:

  • O cadastro retorna 202 com approvalRequired: true, sem token, e a interface explica a aprovação.
  • Login correto é recusado com 403 e código ACCOUNT_PENDING ("Sua conta aguarda aprovação do administrador"). OAuth volta à página de login com ?approval=pending.
  • O estado da conta é relido a cada solicitação autenticada; uma sessão nunca sobrevive ao estado active.

O administrador vê:

  • Um cartão Aprovações pendentes no gerenciamento, com Ativar conta e rejeitar. Rejeição exclui; não há estado suspenso separado.
  • Enquanto conectado, recebe um badge em Usuários e um aviso quando chegam registros. O resumo é consultado cerca de uma vez por minuto (GET /api/users/pending-approvals, somente administrador).
  • A aprovação (PATCH /api/users/:id/approve) registra quem e quando, mas não muda o papel: a conta continua user até ser promovida. Vale na próxima tentativa de login.

Contas existentes não são afetadas por atualização. Somente cadastros públicos posteriores começam pendentes. Contas criadas por administrador ficam ativas imediatamente.

Ativar cadastro público deliberadamente​

O cadastro vem desativado. Defina esta variável somente durante uma janela planejada:

ENABLE_SIGNUP=true

Depois, volte para false. Usuários existentes ainda entram e administradores ainda criam contas.

Um banco vazio sempre permite um administrador local mesmo com ENABLE_SIGNUP=false; OAuth não ocupa essa vaga. Em implantação privada remota, proteja o host com uma lista de identidades como Cloudflare Access antes de iniciar e crie o primeiro administrador pela rota protegida.

Papéis​

PapelFinalidade
adminAdministração, usuários, sistema e operação confiável do runtime Work
userFluxos normais de chat, modelos, personas, documentos e configurações

Instalar, excluir, copiar, enviar e descarregar modelos é exclusivo de administradores porque altera recursos do host.

Acesso ao Work​

Work é restrito a administradores por padrão porque permite ao modelo executar comandos arbitrários em um contêiner gerenciado. Um administrador pode abrir para todos os usuários ativos na aba Gerenciamento de Usuários em Configurações; a configuração persiste e vale imediatamente, inclusive para terminais abertos. Espaços com pasta do host continuam exclusivos porque montam caminhos do servidor. Trate qualquer pessoa com acesso como operador confiável do runtime.

A autorização usa o papel atual no banco, não apenas o cache do JWT. Rebaixar revoga imediatamente. O backend tenta abortar execuções e parar contêineres/prévias, preservando registros e volumes. Se a limpeza falhar, o acesso permanece revogado e a mudança informa o erro.

Excluir um usuário destrói seus dados Work. Primeiro, o Libre para contêineres e remove volumes; se não puder provar sucesso, a exclusão falha para permitir correção e nova tentativa.

Grupos e permissões de recursos​

Administradores criam grupos e gerenciam membros. Grupos são principais de permissões: o proprietário de chat, nota, documento, coleção, pasta, persona, prompt, habilidade ou calendário pode conceder read, write ou admin a usuário ou grupo pela API. Todas as superfícies usam o mesmo diálogo (Compartilhamento); servidores de ferramentas também podem ser limitados assim. Recursos são privados por padrão — o papel global admin não concede acesso ao conteúdo alheio. A associação é avaliada a cada solicitação, e remover um membro revoga imediatamente. A visão de acesso efetivo na aba Gerenciamento de Usuários em Configurações explica o motivo listando papel, grupos, recursos e permissões.

Log de auditoria de segurança​

Ações sensíveis — logins e falhas, logouts, revogações, alterações de usuários, grupos, permissões e tokens — entram em um log somente de acréscimo separado das análises. Detalhes são limpos antes do armazenamento: chaves semelhantes a segredos são removidas e tamanhos limitados, então senhas, tokens e prompts não entram. Alterações de grupo e permissão gravam o evento na mesma transação. Administradores consultam o log na aba Gerenciamento de Usuários em Configurações; a retenção padrão é 180 dias (AUDIT_RETENTION_DAYS).

Sessões​

O backend assina JWTs com JWT_SECRET. Defina um segredo estável:

JWT_SECRET=replace-with-a-long-random-secret

Alterá-lo invalida sessões. Tokens locais e OAuth usam JWT_EXPIRES_IN, padrão 7d; mudanças afetam novas sessões. WebSockets trocam o token durável por um ticket curto e descartável e fecham quando a sessão expira.

Cada login cria também um registro de sessão no servidor vinculado ao JWT. Configurações → Sessões lista dispositivos, método, primeira/última atividade e expiração. Revogar ou "Sair de outras sessões" invalida imediatamente em todas as réplicas e fecha WebSockets; logout revoga a atual. Tokens anteriores sem ID duram até expirar, mas "sair de outras" em um login novo também define um corte por conta que os rejeita.

Autenticação de dois fatores e passkeys​

Configurações → Sessões gerencia ambos:

  • Aplicativo autenticador (TOTP). O cadastro mostra um segredo base32 e link otpauth://; confirmar o primeiro código de 6 dígitos ativa e revela dez códigos de recuperação. Depois, o login por senha retorna um desafio curto e POST /api/auth/mfa/verify conclui com TOTP ou recuperação. O passo de tempo aceito é registrado para impedir repetição. Códigos de recuperação ficam apenas como tokens unidirecionais e funcionam uma vez. Desativar ou regenerar exige provar novamente um fator.
  • Passkeys (WebAuthn). "Entrar com passkey" usa credencial detectável sem senha e exige verificação (bloqueio, biometria ou PIN) no cadastro e login. Attestation é aceita como none, ES256 e EdDSA são compatíveis, e o material é criptografado com o ID como token de consulta. Desafios são únicos e expiram em cinco minutos; contador não zero que não avança é rejeitado como sinal de clonagem. Exigem HTTPS ou localhost; defina WEBAUTHN_RP_ID para vários hosts.

O token de desafio após a senha é assinado com um segredo derivado, mas distinto de JWT_SECRET: não autentica API, é vinculado a uma conta e finalidade e é consumido no sucesso.

Administradores podem exigir segundo fator para todos (Usuários → cartão de política ou MFA_REQUIRED_MODE=required). Quem não tiver será conduzido ao cadastro no próximo login. O administrador pode redefinir TOTP para recuperação; passkeys permanecem sob controle do usuário. Cadastro, ativação, falhas, desativação, mudanças, passkeys e redefinições entram na auditoria.

MFA vale para login por senha. OAuth e OIDC confiam no segundo fator do provedor e não repetem. Tokens de API não são afetados.

Tokens de API​

Configurações → Chaves de API emite tokens pessoais (prefixo lwk_). O segredo aparece uma vez e só seu hash é salvo. Cada token traz escopos (chat, models, documents, notes, personas, media, work, admin); o backend mapeia famílias de rotas, então um token de notas não alcança chats ou administração, e gerenciamento de sessões nunca é acessível. Podem expirar, registram último uso, podem ser revogados e têm limite por token entre réplicas. Tokens administrativos só podem ser criados por administradores e ainda exigem esse papel no uso. Um token chat também é a chave da API pública /v1 compatível com OpenAI.

Cloudflare Turnstile​

Quando ambas as chaves existem, protege login e cadastro:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=chat.example.com

O frontend atribui ações login e signup. O backend verifica com Cloudflare e recusa host ou ação divergente. BASE_URL fornece o host esperado quando TURNSTILE_EXPECTED_HOSTNAME não está definido.

Sem uma das chaves, fica desativado.

GitHub OAuth​

GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback

Cria usuários locais com prefixo gh_ e papel user.

Hugging Face OAuth​

HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback

Cria usuários locais com prefixo hf_ e papel user.

Ambos usam state criptograficamente aleatório vinculado a cookie HttpOnly SameSite curto. O callback rejeita ausência ou divergência. Após sucesso, o JWT volta em cookie HttpOnly de 60 segundos, é trocado e removido; tokens Bearer nunca entram em URLs, histórico ou referrer.

Redirecionamentos e CORS​

Defina BASE_URL para callbacks e CORS_ORIGIN para acesso:

BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example

No desenvolvimento:

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

Modo de demonstração​

É um modo de prévia do frontend, com credenciais preenchidas e respostas simuladas. Não é autenticação de produção.

Lista de segurança​

  • Defina JWT_SECRET forte.
  • Mantenha DATA_DIR persistente e controlado.
  • Faça backup de ENCRYPTION_KEY com o banco.
  • Configure Turnstile para cadastro público.
  • Use HTTPS em público.
  • Restrinja chaves de provedores ao mínimo.
  • Mantenha callbacks OAuth exatos.
  • Conceda Work somente a quem é confiável para operar o runtime.

Documentos relacionados​