Intermediário 12 minPlano diário

Open WebUI: gerenciar os acessos às documentos

Folhas de papel estão espalhadas ao lado de um notebook sobre uma mesa de madeira.

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 Mohamed Meguedmi·Atualização 2026-11-20·Testado no Windows, macOS e Linux
!
Fontes e versão
Os comportamentos descritos seguem a página oficial de permissões do Open WebUI (docs.openwebui.com, seção Authentication & Access > RBAC > Permissions). Não foi possível revisar essa página no momento da redação (20/11/2026): os nomes de menus, nomes de permissões e rotas de API mudam de uma versão para outra. Anote a versão da sua instância (Configurações > Sobre) e confira cada ponto com a documentação dessa versão.

#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

O kit completo para criar o seu próprio RAG local.

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

  1. 01
    1. Restringir as permissões padrão
    No 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.
  2. 02
    2. Criar os grupos
    Um 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.
  3. 03
    3. Criar ou reorganizar as bases
    Em 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.
  4. 04
    4. Configurar o acesso de cada base
    Deixe 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.
  5. 05
    5. Controlar os modelos que carregam bases
    Um 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).
→
Um documento de teste por base
Adicione em cada base um pequeno arquivo de texto contendo uma frase única e sem significado, por exemplo TEMOIN-RH-7Q2. Se essa string aparecer em uma resposta obtida por uma conta que não deveria ler a base, o vazamento está comprovado, seja qual for o caminho utilizado. Isso é mais confiável do que julgar uma resposta que "parece" com o conteúdo de um documento.

#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).

Terminal — códigos HTTP por conta
U=http://localhost:3000
KB=identifiant-de-la-base   # visible dans l'adresse de la page de la base
JOURNAL=~/owui-acces-$(date +%F).log

# Un fichier de clé par compte de test, droits 600
for compte in admin rh compta aucun-groupe; do
  CLE=$(cat ~/.config/owui-test/$compte)
  liste=$(curl -s -o /dev/null -w '%{http_code}' \
    -H "Authorization: Bearer $CLE" "$U/api/v1/knowledge/")
  base=$(curl -s -o /dev/null -w '%{http_code}' \
    -H "Authorization: Bearer $CLE" "$U/api/v1/knowledge/$KB")
  echo "$(date -Is) $compte liste=$liste base=$KB:$base"
done | tee -a "$JOURNAL"

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.

Terminal — bases visíveis para uma conta
curl -s -H "Authorization: Bearer $(cat ~/.config/owui-test/compta)" \
  "$U/api/v1/knowledge/" | jq -r '(.items? // .)[] | .name'

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.
Terminal — teste de referência direta a uma base
# Compte qui NE doit PAS lire la base $KB
curl -s "$U/api/chat/completions" \
  -H "Authorization: Bearer $(cat ~/.config/owui-test/compta)" \
  -H "Content-Type: application/json" \
  -d '{"model":"votre-modele",
       "messages":[{"role":"user","content":"Recopie la phrase qui commence par TEMOIN."}],
       "files":[{"type":"collection","id":"'"$KB"'"}]}' \
  | grep -o 'TEMOIN-[A-Z0-9-]*' || echo "témoin absent"

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.

!
Isolamento não garantido
Mesmo com uma matriz de acesso bem-feita, Open WebUI não é uma solução de gestão documental certificada. Para dados cobertos por sigilo profissional ou dados de saúde, uma instância separada por escopo (contêineres, volumes e contas distintos) continua sendo mais simples de demonstrar do que uma segmentação por grupos em uma instância única.

#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.

i
O que o teste de 30/10/2026 comprova
Que uma conta de usuário, nesta imagem e sem nenhuma configuração de grupo, não lê pela API uma base privada criada por um administrador. Isso não prova nada sobre o chat, os modelos, os grupos ou o conteúdo de uma base não vazia.

#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).
Este guia ajudou você?

Um comentário, um erro ou uma observação? Avise-nos; isso ajuda a melhorar o guia para todos.