Open WebUI: gerenciar os acessos às documentos

Assim que uma instância do Open WebUI passa a atender vários departamentos, a pergunta deixa de ser apenas “o modelo responde bem?” e passa a ser “quem pode consultar quais documentos?”. Open WebUI: gerenciar o acesso aos documentos envolve três mecanismos (funções, grupos e visibilidade de cada base de conhecimento) que se combinam de uma forma nem sempre intuitiva. Este guia explica esse modelo, propõe um procedimento de isolamento por grupo e, em seguida, um método para testar cada conta separadamente e procurar sobreposições. Ele não promete isolamento total: apenas parte do percurso foi observada pela redação, e isso está indicado.
#Por que isolar os documentos no Open WebUI
Uma base de conhecimento (Knowledge) do Open WebUI é uma coleção de arquivos divididos em trechos e indexados. Quando um usuário a menciona com # no chat, ou quando ela está vinculada a um modelo, o Open WebUI busca os trechos próximos da pergunta e os injeta no contexto. O modelo pode então reproduzir esses trechos, às vezes palavra por palavra.
Consequência direta: ter acesso a uma base significa poder ler o conteúdo dela, mesmo sem nunca abrir o arquivo. Em uma instância de equipe, misturar em uma única base os procedimentos públicos, os holerites e os contratos de fornecedores equivale a entregar todos esses documentos a qualquer pessoa que possa consultá-la. A segmentação é feita, portanto, base por base, e não arquivo por arquivo: um documento sensível deve ficar em uma base cujo escopo de acesso corresponda à sua sensibilidade.
A auto-hospedagem resolve a questão da transferência para um provedor externo, não a dos acessos internos. Os guias do site sobre o RGPD lembram que o princípio da minimização também se aplica aos colegas: uma pessoa só deveria acessar os dados necessários à sua função.
#Funções, grupos e visibilidade das bases
Aproveite a nossa experiência e um percurso guiado para construir o seu RAG local e trabalhar com os seus próprios documentos.
- Espaço online vitalício
- PDF + arquivos
- Reembolsado em 30 dias
O controle de acesso do Open WebUI se baseia em três camadas. Confundi-las é a principal fonte de erros.
- As funções
- Cada conta tem uma função: administrador, usuário ou pendente (pending). Uma conta pendente não pode fazer nada até que um administrador a aprove. Um administrador gerencia a instância e, com as configurações padrão, vê o conteúdo do espaço de trabalho das outras contas. A função é, portanto, uma barreira grosseira: ela separa quem administra de quem usa.
- Os grupos
- Criados no painel de administração (seção Usuários > Grupos), eles servem para duas coisas: carregar permissões funcionais (poder criar bases, compartilhar, usar determinadas funções) e servir de destino quando se compartilha um recurso. Um usuário pode pertencer a vários grupos.
- A visibilidade de um recurso
- Cada base de conhecimento, assim como cada modelo personalizado, prompt ou ferramenta, tem uma configuração de acesso. Privada: somente o proprietário (e os administradores, conforme a configuração descrita mais abaixo) tem acesso, além dos grupos adicionados explicitamente. Pública: todos os usuários da instância podem lê-la. Para cada grupo adicionado, em geral se escolhe leitura ou escrita.
O isolamento por grupo consiste, portanto, em manter as bases privadas e depois adicionar apenas o grupo ou os grupos envolvidos, com permissão de leitura para a maioria dos membros. A escrita (adicionar, substituir, excluir arquivos) fica reservada a poucas pessoas, de preferência por meio de um grupo separado do dos leitores.
#Direitos que se somam: a armadilha das permissões padrão
Segundo a documentação oficial, as permissões do Open WebUI são cumulativas: um usuário recebe a união das permissões padrão (as que se aplicam a todos os usuários) com as de todos os seus grupos. A permissão mais ampla prevalece. Não existe um grupo de “proibição” que retire um direito concedido em outro lugar.
Duas consequências práticas. Primeiro, se as permissões padrão autorizam uma ação (por exemplo, compartilhar publicamente uma base), nenhum grupo pode retirá-la de um usuário: é preciso restringir o padrão e depois liberar a ação apenas para os grupos que precisam dela. Segundo, pertencer a um grupo adicional só pode ampliar os acessos. Adicionar uma pessoa ao grupo “Diretoria” sem removê-la de “Estagiários” dá a ela os dois escopos.
- Permissões padrão
- A configurar primeiro, da forma mais restritiva razoável: sem compartilhamento público, criação de bases limitada se a instância não for um ambiente de testes (sandbox).
- Permissões de grupo
- Reabrem funções para um subconjunto: um grupo "Editores de documentação" que pode criar e compartilhar bases, por exemplo.
- Acesso por recurso
- Independente das permissões funcionais: poder criar bases não dá acesso às bases dos outros. É a configuração de cada base que decide quem pode lê-la.
#Pré-requisitos
- Uma instância do Open WebUI atualizada
- Instalada e conectada ao Ollama (por padrão em http://localhost:11434), com um modelo de embeddings funcionando. O guia “Open WebUI com Ollama: guia completo” aborda a instalação.
- Um backup verificado
- Reorganizar os acessos significa modificar bases usadas no dia a dia. Arquive o volume Docker antes de começar (veja "Restaurar Open WebUI e Ollama após uma falha").
- Um mapeamento dos documentos
- Uma tabela simples: qual base, quais documentos, qual sensibilidade, quais departamentos devem ler, quem deve escrever. Sem ela, a configuração é feita conforme os pedidos chegam e acaba se desviando.
- Contas de teste
- Pelo menos uma conta sem privilégios de administrador por grupo a verificar, além de uma conta que não pertença a nenhum grupo. Testes feitos com uma conta de administrador não provam nada sobre os acessos dos usuários.
- As chaves de API autorizadas
- Para os testes por linha de comando, o administrador precisa autorizar as chaves de API (configurações de administração); cada conta de teste gera uma em Configurações > Conta.
#Gerenciar os acessos aos documentos no Open WebUI: 5 etapas
- 011. Restringir as permissões padrãoNo painel de administração, abra as permissões padrão dos usuários. Desative o compartilhamento público de bases de conhecimento e de modelos e limite a criação de bases se ela não for necessária para todos. Verifique também a função atribuída aos novos cadastrados: “pendente” evita que uma conta criada por engano tenha acesso imediato a qualquer coisa.
- 022. Criar os gruposUm grupo por escopo de documentos (“RH”, “Contabilidade”, “Suporte”) e, se necessário, um grupo de editores por escopo. Dê a eles os mesmos nomes das bases correspondentes: isso facilita a revisão das configurações. Se os seus grupos vêm de um diretório via OAuth ou LDAP, verifique na documentação da sua versão como a sincronização de grupos é configurada e se um grupo removido no diretório também é removido no Open WebUI.
- 033. Criar ou reorganizar as basesEm Espaço de trabalho > Conhecimento, uma base por escopo. Mover um documento sensível de uma base ampla para uma base restrita exige removê-lo explicitamente da primeira: um arquivo importado em duas bases existe duas vezes, com duas configurações de acesso.
- 044. Configurar o acesso de cada baseDeixe a base como privada, adicione o grupo correspondente com permissão de leitura e o grupo de editores com permissão de escrita. Evite adicionar pessoas uma a uma: o acesso individual se perde quando alguém sai da empresa ou muda de cargo, enquanto um grupo é mantido atualizado em um único lugar.
- 055. Controlar os modelos que carregam basesUm modelo personalizado (Espaço de trabalho > Modelos) pode ter bases vinculadas. Configure o acesso ao modelo de forma pelo menos tão restrita quanto o das bases que ele carrega e teste esse caso em particular (veja a seção sobre sobreposições).
#Testar os acessos de cada usuário separadamente
A interface de administração mostra o que está configurado, não o que um usuário realmente obtém. A única verificação conclusiva é se colocar no lugar de cada conta. Dois métodos complementares: uma janela de navegação anônima por conta de teste (para ver as listas e o chat como o usuário) e chamadas à API com a chave de cada conta (para obter códigos HTTP reproduzíveis e datados).
O script abaixo consulta, para cada conta de teste, a lista de bases visíveis e depois uma base específica, e registra os códigos de resposta em log. As chaves são lidas de arquivos privados, uma por conta, e nunca passadas em texto claro no comando. As rotas /api/v1/knowledge/ são as da API do Open WebUI; confirme-as na sua versão. A porta 3000 corresponde ao comando Docker mais comum (-p 3000:8080).
Um código 200 na base significa que a conta pode lê-la pela API; um código 401 ou 403 significa uma recusa. O código da lista geralmente é 200 para qualquer conta válida: o que importa é o conteúdo dela. O comando a seguir exibe os nomes das bases visíveis para uma conta; dependendo da versão, a resposta é um array ou um objeto contendo um array, daí o filtro que trata os dois casos.
Em seguida, monte uma matriz: uma linha por conta, uma coluna por base, o valor esperado (leitura, escrita, nenhum) e o valor observado. Qualquer célula em que o observado seja mais amplo que o esperado é um defeito a corrigir antes de importar documentos reais. Execute a matriz novamente após cada atualização do Open WebUI e após cada alteração de grupo: uma configuração correta hoje pode ser alterada por uma migração ou por um erro de operação.
#Sobreposições a verificar
Negar o acesso direto a uma base não basta para provar que uma conta não consegue obter o conteúdo dela. Existem vários caminhos indiretos em uma instância do Open WebUI; o comportamento deles depende da versão e da configuração, e nenhum foi testado pela redação. São hipóteses a serem verificadas com o documento-testemunha, não falhas constatadas.
- Modelo com base vinculada
- Um usuário que tem acesso a um modelo personalizado vinculado a uma base, mas não à base em si: ele obtém os trechos da base ao conversar com o modelo? Teste fazendo ao modelo uma pergunta sobre a frase-testemunha.
- Referência direta por identificador
- A API de completion aceita uma lista de arquivos ou de coleções a serem usados como contexto. Uma conta não autorizada que conhece o identificador de uma base pode referenciá-la dessa forma? Veja a chamada de teste abaixo.
- Conversas compartilhadas
- Uma conversa compartilhada por link contém as respostas já geradas e, portanto, possivelmente trechos de documentos. O link pode circular fora do grupo. Verifique quem pode criar links de compartilhamento e o que vê uma conta que o abre.
- Arquivos anexados ao chat
- Um documento arrastado para uma conversa não é uma base de conhecimento e não segue as mesmas configurações. Um usuário do grupo RH que anexa um holerite em uma conversa compartilhada anula o isolamento.
- Acesso dos administradores
- Por padrão, os administradores veem os recursos das outras contas. A documentação menciona uma variável de ambiente (BYPASS_ADMIN_ACCESS_CONTROL) para alterar esse comportamento; verifique o nome e o efeito dela na sua versão. Em todo caso, um administrador mantém o acesso ao servidor e ao banco de dados: limite o número de contas de administrador.
- Grupos herdados do diretório
- Com uma sincronização OAuth ou LDAP, um desligamento ou uma mudança de departamento deve se refletir nos grupos. Teste o caso de uma conta removida de um grupo no diretório, depois que ela fizer login novamente.
Se a string-testemunha aparecer, a base vaza por esse caminho: remova a base dos modelos acessíveis a essa conta e relate o comportamento ao projeto com o número da sua versão. Se ela não aparecer, o teste é negativo apenas para esta versão, este modelo e esta conta. Um modelo também pode se recusar a responder ou reformular: examine a resposta completa, e não apenas a busca pela string.
#Solução de problemas
- Um usuário não vê uma base compartilhada com o grupo dele
- Verifique se ele é de fato membro do grupo (e não de um grupo com o mesmo nome) e, depois, se ele fez login novamente. Abra uma nova conversa: a lista sugerida com # é montada na abertura.
- Um usuário vê uma base que não deveria ver
- Procure nesta ordem: base tornada pública, grupo amplo adicionado por engano, participação em um segundo grupo, permissão padrão ampla demais. Como os direitos são cumulativos, a causa quase sempre é algo adicionado, e não algo que deixou de ser removido.
- O teste de API retorna 401 para todas as contas
- Chaves de API desativadas pelo administrador, chave copiada com um espaço ou URL errada. Teste primeiro a conta de administrador em uma base que pertença a ela.
- Os testes passam na API, mas o chat mostra a base
- Compare com a mesma conta em uma janela anônima, sem sessão de administrador aberta no mesmo navegador. Um teste feito por engano com uma sessão de admin é a causa mais frequente de resultados falsos.
- Após a atualização, as configurações mudaram
- As migrações podem renomear ou reorganizar as permissões. Execute novamente a matriz completa e leia as notas de versão da release instalada.
#O que foi verificado e o que não foi
Em 30/10/2026, a redação executou uma imagem Docker isolada do Open WebUI, sem acesso à rede nem GPU, com duas contas fictícias. Uma base de conhecimento privada e vazia, criada pela conta de administrador, foi solicitada pela API: resposta HTTP 200 para o administrador, HTTP 401 para a conta de usuário. Essa é a única observação direta deste guia. A versão exata da imagem não é informada aqui.
Não foram testados: uma base contendo documentos, os grupos e o compartilhamento por grupo, as permissões de escrita, o compartilhamento público, os modelos vinculados a uma base, a referência direta por identificador, as conversas compartilhadas, a sincronização de grupos via diretório, nem uma auditoria completa da instância. Os scripts deste guia são fornecidos como método; os resultados deles na sua instância são os únicos que importam. Nenhum volume de busca foi medido para a consulta pretendida.
#Para se aprofundar
- Open WebUI com Ollama: guia completo
- Instalação, contas e configurações básicas da interface: https://quelllm.fr/guide/open-webui-ollama-tutoriel
- Implantar um chatbot de IA para sua equipe na intranet
- Proxy reverso, autenticação e operação de uma instância multiusuário: https://quelllm.fr/guide/deployer-chatbot-ia-equipe-intranet
- RAG local com Ollama sem programar
- Funcionamento das bases de conhecimento na interface: https://quelllm.fr/guide/rag-local-ollama-sans-coder
- Fonte primária
- Open WebUI, documentação oficial, Authentication & Access > RBAC > Permissions: https://docs.openwebui.com/features/authentication-access/rbac/permissions/ (não revisada em 20/11/2026; verificar na versão instalada).
Um comentário, um erro ou uma observação? Avise-nos; isso ajuda a melhorar o guia para todos.