Guia completo para gerenciamento e criação de usuários no LibreChat

Se você busca uma alternativa auto-hospedada para interagir com diferentes modelos de inteligência artificial, o LibreChat é uma das opções mais completas. A plataforma permite centralizar o acesso a provedores como OpenAI, Anthropic e Google, mas também oferece algo especialmente importante quando usada por uma equipe: controlar quem pode entrar e quais funções estão disponíveis.

Essa gestão vai além da simples criação de uma conta com e-mail e senha. O LibreChat combina sistemas de autenticação, funções, grupos, permissões para funções específicas e listas de controle de acesso para recursos compartilhados. Isso permite impedir que certos usuários criem agentes, permitir que uma equipe edite mensagens ou delegar parte da administração sem conceder acesso total ao servidor. E se você ainda está considerando a plataforma, confira nossa comparação entre [inserir lista de plataformas aqui]. LibreChat, ChatGPT e outras alternativas.

Como criar usuários no LibreChat

Por padrão, o LibreChat permite que uma pessoa se registre usando seu endereço de e-mail e uma senha. Quando uma nova instância é iniciada, A primeira conta registrada recebe a função de ADMINISTRADOR.Portanto, é aconselhável criá-lo antes de publicar o serviço e usar credenciais seguras para isso.

El As contas restantes registradas recebem inicialmente a função de USUÁRIO.O administrador pode controlar o login e o cadastro usando diferentes variáveis ​​no arquivo. .env:

ALLOW_EMAIL_LOGIN=true
ALLOW_REGISTRATION=true
ALLOW_SOCIAL_LOGIN=false
ALLOW_SOCIAL_REGISTRATION=false

ALLOW_EMAIL_LOGIN permite o uso de contas locais, enquanto ALLOW_REGISTRATION Controla se os novos cadastros são disponibilizados por e-mail. As outras duas variáveis ​​fazem o mesmo para provedores de redes sociais compatíveis.

Uma configuração típica para uma instância privada envolve primeiro a criação das contas necessárias e, em seguida, o fechamento do registro público:

ALLOW_EMAIL_LOGIN=true
ALLOW_REGISTRATION=false

Mesmo com o registro desativado, o administrador pode adicionar uma conta local usando o script incluído no LibreChat. Em uma instalação usando o arquivo Docker Compose padrão, o comando é:

docker compose exec api npm run create-user

O assistente solicitará o endereço de e-mail e a senha da nova conta. Em uma instalação local, sem Docker, ele pode ser executado a partir da raiz do projeto:

npm run create-user

O LibreChat também inclui um script para excluir contas. Antes de usá-lo, é recomendável verificar quais conversas, agentes e recursos pertencem ao usuário, pois excluir uma conta não deve ser confundido com remover temporariamente o acesso.

Utilize LDAP, SAML, OAuth ou OpenID Connect.

Para uma equipe pequena, contas locais podem ser suficientes. Em uma organização, é mais conveniente conectar o LibreChat ao sistema de identidade já utilizado pelos funcionários.

A plataforma suporta diferentes métodos de autenticação:

• LDAP ou Active Directory, para validar usuários em relação a um diretório existente.
• SAML, comumente usado para implementar autenticação única empresarial.
• OAuth2, compatível com provedores como Google, GitHub, Discord ou Apple.
• OpenID Connect, usado para conectar serviços como Keycloak, Auth0, AWS Cognito ou Microsoft Entra ID.

É importante saber que SAML e OpenID Connect não funcionam simultaneamente. Se ambos estiverem ativados, O LibreChat prioriza o OpenID Connect e desativa o SAML.Além disso, esses dois métodos não permitem separar o login de usuários existentes do cadastro de novos usuários por meio de uma variável simples, como ocorre no cadastro local ou social.

Na Keycloak você pode usar OPENID_REQUIRED_ROLE Para impedir o acesso a quem não possui uma das funções autorizadas. Isso é útil se você não quiser que nenhuma conta no diretório possa acessar a instância.

Integre o LibreChat com o ID de login da Microsoft.

O Microsoft Entra ID pode se conectar ao LibreChat como um provedor OpenID Connect. Cada usuário é vinculado usando seu ID estável e pode fazer login usando suas credenciais corporativas.

A integração pode ser ampliada usando o Microsoft Graph para que o seletor de pessoas do LibreChat possa encontrar usuários e grupos dentro da organização. Isso requer as permissões apropriadas no aplicativo registrado com o Entra ID e a reutilização do token OpenID deve estar habilitada.

OPENID_REUSE_TOKENS=true
USE_ENTRA_ID_FOR_PEOPLE_SEARCH=true
ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS=true
OPENID_GRAPH_SCOPES=User.Read,People.Read,GroupMember.Read.All,User.ReadBasic.All

Algumas permissões, como GroupMember.Read.AllEles podem precisar da autorização de um administrador do Entra ID.

Essa integração não deve ser descrita simplesmente como sincronização automática de nomes. O Microsoft Graph permite pesquisar pessoas, visualizar associações e usar grupos externos dentro do sistema de permissões, sempre dentro do escopo concedido ao aplicativo.

Gerencie usuários a partir do painel do LibreChat.

O LibreChat possui um painel de administração separado que se conecta à mesma API e banco de dados da instância principal. Através dele, você pode visualizar usuários, gerenciar grupos e funções, aplicar configurações específicas e conceder privilégios administrativos.

No entanto, na documentação atual, o O painel de administração do LibreChat ainda aparece marcado como "Prévia".Embora já possa ser testado e faça parte das implementações oficiais usando o Docker Compose, é recomendável verificar seu status e compatibilidade antes de utilizá-lo em um ambiente de produção.

O painel permite, entre outras operações:

• Pesquise e visualize as contas da instância.
• Crie grupos locais e modifique seus membros.
• Crie funções personalizadas e atribua-as aos usuários.
• Modifique as permissões associadas a cada função.
• Aplique configurações diferentes a grupos ou funções.
• Delegação de funções administrativas por meio de concessões do sistema.

O painel funciona como um serviço separado. As operações são processadas por meio de rotas. /api/admin/* O LibreChat verifica se a conta possui as permissões administrativas necessárias antes de aceitar cada alteração.

Entendendo a diferença entre funções e grupos

O LibreChat incorpora duas funções de sistema que estão sempre presentes:

• ADMINPossui acesso total às configurações, recursos e funções administrativas.
• USUÁRIO: é a função básica que as novas contas recebem.

A partir do LibreChat 0.8.5, você também pode criar funções personalizadasCada uma contém uma matriz de permissões para decidir se seus membros podem usar, criar, compartilhar ou publicar agentes, prompts, servidores MCP e outras funções.

Por exemplo, você poderia criar uma função chamada "Editor de Prompts" com permissão para criar e compartilhar prompts, mas sem a capacidade de publicar agentes ou modificar configurações gerais.

Um usuário pode ter várias funções. Nesse caso, suas permissões efetivas são calculadas usando o união das capacidades concedidasIsso significa que adicionar uma segunda função, mais permissiva, pode devolver uma função que você estava tentando restringir na primeira.

Os grupos têm uma finalidade diferente. São utilizados para agrupar usuários por departamento, projeto ou necessidade de acesso. Podem ser criados localmente ou a partir de uma integração compatível, como o Entra ID.

Os grupos são utilizados como destinatários de recursos compartilhados e também podem receber substituições de configuraçãoDessa forma, um grupo de pesquisadores poderia usar endpoints adicionais ou uma configuração diferente sem alterar a experiência do restante da organização.

Configure as permissões para agentes, prompts e servidores MCP.

As permissões de função determinam o que cada função pode fazer. O LibreChat permite que você controle ações separadamente, como:

• USAR: utilize uma função ou um tipo de recurso.
• CRIARCriar novos recursos.
• COMPARTILHARCompartilhe-os com usuários, grupos ou funções específicos.
• COMPARTILHAR_PÚBLICO: torná-los acessíveis a todos os usuários autenticados da instância.

A diferença entre SHARE y SHARE_PUBLIC Isso é especialmente importante. Você pode permitir que uma equipe compartilhe agentes internamente sem conceder a eles a capacidade de publicá-los para toda a organização.

Em versões anteriores, muitas dessas permissões eram inicializadas usando o bloco interface de librechat.yamlEssa possibilidade ainda existe para se preparar para o cargo. USER durante a inicialização, mas Já não é o método recomendado para administração diária..

O painel permite modificar diretamente as permissões de cada função, incluindo funções personalizadas, sem precisar reiniciar o LibreChat. O YAML continua sendo útil para a implantação inicial e para instalações totalmente gerenciadas por arquivos.

Compartilhe recursos usando listas ACL

As permissões gerais por si só não determinam quem pode abrir cada agente ou prompt. Os recursos compartilháveis ​​também têm uma lista de controle de acesso ou ACL própria.

Este sistema aplica-se, entre outras coisas, a agentes, grupos de prompts, servidores MCP, agentes remotos, arquivos e projetos. O proprietário pode compartilhar cada recurso com usuários, grupos ou funções e escolher um destes níveis:

• Visualizador: permite visualizar e usar o recurso.
• Editor: permite que você o utilize e modifique suas configurações.
• Proprietário: concede controle total para editar, excluir e compartilhar novamente.

Por exemplo, uma pessoa pode ter permissão geral para usar agentes, mas não poderá acessar um agente privado se ele não estiver listado em sua ACL. Da mesma forma, receber acesso de Visualizador a um agente não concede automaticamente permissão para criar novos agentes.

Ao compartilhar agentes com arquivos, instruções internas ou ferramentas capazes de modificar dados, você deve revisar cuidadosamente o nível de privilégio atribuído a eles. O LibreChat alerta que um agente pode revelar informações anexadas durante uma conversa, mesmo quando o usuário não tem acesso direto às suas configurações.

Delegar tarefas administrativas com concessões do sistema

Atribuir privilégios de ADMINISTRADOR a alguém para executar uma única tarefa viola o princípio do menor privilégio. Para evitar isso, o LibreChat incorpora o que é chamado de... concessão do sistema.

Essas concessões permitem que capacidades administrativas específicas sejam concedidas a um usuário, grupo ou função. Exemplos documentados incluem:

• manage:users, para gerenciar usuários.
• manage:roles, para gerenciar funções.
• manage:mcpservers, para gerenciar servidores MCP.
• read:usage, para consultar informações de utilização.

Dessa forma, o gerente de suporte pode gerenciar contas sem ter acesso total à instância inteira. As verificações são realizadas na API do LibreChat, portanto, o painel não pode conceder privilégios a si mesmo.

Como o painel de administração ainda está em versão prévia, é recomendável testar minuciosamente essas delegações e manter pelo menos uma conta de administrador local para recuperação.

Quais arquivos estão envolvidos na configuração?

O LibreChat distribui a configuração entre diferentes componentes, mas cada um tem um propósito claro:

• .env: contém variáveis ​​de ambiente, segredos, opções de autenticação e conexões com serviços.
• librechat.yaml: define endpoints personalizados, modelos, opções de interface, agentes, MCP e outros recursos avançados.
• Banco de dados: Salva usuários, funções personalizadas, grupos, ACLs, concessões e configurações gerenciadas a partir do painel.

Em uma instalação do Docker, não basta criar librechat.yamlO arquivo deve ser montado dentro do contêiner da API. Após a modificação, o serviço também precisa ser reiniciado.

As versões atuais validam o YAML durante a inicialização. Se ele contiver uma chave desconhecida, indentação incorreta ou um valor incompatível, O LibreChat será interrompido e exibirá o erro nos registros.Você pode verificá-los com:

docker compose logs api

Existe uma variável chamada CONFIG_BYPASS_VALIDATION Isso pode contornar a validação temporariamente, mas não deve ser usado como solução permanente. A abordagem correta é localizar e corrigir o erro.

O MongoDB armazena os dados principais do LibreChat, incluindo contas e conversas. O MeiliSearch é usado para acelerar as buscas de mensagens, e o PostgreSQL com suporte a vetores está envolvido na API RAG. Esses últimos serviços não são essenciais para o sistema do usuário e podem depender de recursos habilitados em cada implementação.

Recomendações para proteger contas

Uma instância do LibreChat pode conter conversas privadas, documentos corporativos e credenciais de acesso a outros serviços. Por esse motivo, o gerenciamento de usuários deve ser projetado antes de disponibilizar o serviço para toda a equipe.

É aconselhável aplicar estas medidas:

• Crie e proteja a primeira conta de ADMINISTRADOR antes de publicar a instância.
• Desative o registro aberto quando não for necessário.
• Utilize HTTPS e seus próprios segredos JWT seguros.
• Configure a verificação de e-mail e a recuperação de senha se estiver usando contas locais.
• Aplique o princípio do menor privilégio a funções, ACLs e concessões de sistema.
• Analise periodicamente os usuários, grupos e recursos compartilhados publicamente.
• Mantenha uma conta administrativa local para recuperar o acesso caso o provedor de SSO falhe.
• Verifique os registros após modificar a autenticação ou as permissões.

Criar e gerenciar usuários no LibreChat exige distinguir entre autenticação e autorização. O método de login verifica a identidade de cada pessoa; as funções determinam quais recursos ela pode usar; os grupos facilitam a administração coletiva; e as ACLs (Listas de Controle de Acesso) determinam quem pode acessar cada recurso específico.

Com essa estrutura, você pode usar o LibreChat em um pequeno servidor privado ou em uma organização com um diretório corporativo, sem dar a todos os usuários acesso total a agentes, prompts, servidores MCP ou funções administrativas.