Control de acceso granular

LibreChat incluye un sistema de autorización completo además de la autenticación. El acceso no es de "todo o nada": cada entidad compartible en la aplicación (agentes, prompts, servidores MCP, agentes remotos, archivos, conversaciones) tiene su propia Lista de Control de Acceso (ACL), y cada función puede habilitarse o restringirse de forma independiente por usuario, grupo, rol o públicamente.

Esta página explica cómo encajan las piezas para que pueda modelar los permisos según las necesidades de su organización, desde un equipo pequeño donde todos comparten libremente, hasta una implementación empresarial con grupos de Entra ID sincronizados, roles personalizados y administradores delegados.

El modelo de acceso de un vistazo

La autorización de LibreChat tiene tres capas independientes que se combinan entre sí:

Los tres se evalúan para los mismos cuatro tipos principales:

• Usuario: una cuenta individual de LibreChat
• Grupo: una colección de usuarios (locales o sincronizados desde Entra ID)
• Role: un perfil de permiso con nombre (p. ej., USER, ADMIN o cualquier rol personalizado)
• Público: cada usuario autenticado en la instancia

Capa 1: Permisos de funciones (basados en roles)

Los permisos a nivel de función restringen capacidades completas de la aplicación para un rol determinado. Estos responden a preguntas como "¿Pueden los usuarios con este rol crear agentes?", "¿Tienen permiso para compartir prompts públicamente?", "¿Pueden invocar el intérprete de código?".

Roles del sistema integrados

LibreChat se entrega con dos roles de sistema que siempre están presentes y no pueden eliminarse:

• ADMIN: asignado a la primera cuenta registrada en la instancia. Los administradores pueden ver todos los recursos, modificar cualquier configuración, acceder al panel de administración y configurar el comportamiento de toda la plataforma.
• USER: el rol predeterminado asignado a cada cuenta nueva.

Los administradores pueden ser promovidos manualmente actualizando el documento de usuario en MongoDB, consulte Administrator Controls.

Tipos de permisos

Cada rol contiene una matriz de tipos de permisos × acciones:

La distinción entre SHARE y SHARE_PUBLIC es importante: puedes permitir que un rol comparta agentes con usuarios o grupos específicos (SHARE) sin dejar que los hagan visibles para todos en la instancia (SHARE_PUBLIC).

Configuración de permisos de funciones

La forma recomendada de gestionar los permisos de funciones es el LibreChat Admin Panel, el cual edita la matriz de permisos directamente en cada rol (incluyendo cualquier rol personalizado que cree). Los cambios surten efecto sin necesidad de volver a desplegar LibreChat y se aplican específicamente al rol que desea modificar, en lugar de al valor predeterminado global de USER.

Roles personalizados

Más allá de USER y ADMIN, los administradores pueden crear roles personalizados con su propia matriz de permisos de funciones (introducida en la v0.8.5; ver #12528). Un usuario puede tener múltiples roles, y sus permisos efectivos son la unión de todos los roles que posee. Los roles personalizados se gestionan desde el panel de administración.

Anulaciones de configuración con alcance de rol y grupo

Además de los indicadores de funciones (feature flags), la versión v0.8.5 introdujo un sistema de anulación de configuración respaldado por BD (#12354). Esto le permite asignar una configuración diferente al estilo librechat.yaml a grupos o roles específicos. Por ejemplo, un grupo de "Investigación" podría tener acceso a endpoints adicionales, un límite de recursión más alto y capacidades de agente diferentes a las predeterminadas. Las anulaciones se resuelven al iniciar sesión y se componen sobre la configuración base.

Capa 2: ACL de recursos (Compartición por entidad)

Cada recurso compartible en LibreChat tiene su propia Lista de Control de Acceso (ACL), independiente de los permisos basados en roles. Así es como un usuario individual con permiso SHARE elige quién obtiene acceso a su agente, prompt o servidor MCP.

Tipos de recursos

Las ACL de recursos se aplican actualmente a:

• Agentes (agent)
• Prompts / Grupos de Prompts (promptGroup)
• Servidores MCP (mcpServer)
• Agentes remotos (remoteAgent), para la API de agentes
• Archivos (file), normalmente heredados del recurso que los utiliza
• Projects (project), admite herencia, por lo que los recursos compartidos con un proyecto heredan automáticamente las ACL

Roles de acceso (Preajustes de permisos)

En lugar de exponer bits de permisos sin procesar a los usuarios finales, el uso compartido emplea tres roles con nombre por tipo de recurso:

Internamente, los permisos se almacenan como una máscara de bits (permBits) para cada par (recurso, principal); los superconjuntos se gestionan automáticamente, por lo que otorgar el rol de Editor implica el de Viewer.

Conceder acceso desde la UI

1. Abra el recurso (constructor de agentes, formulario de prompts, configuración del servidor MCP, etc.)
2. Haz clic en el botón Share (visible cuando eres el propietario, un administrador o se te ha concedido SHARE)
3. En el diálogo de compartir:
   • Utilice el selector de personas para buscar usuarios, grupos o roles que añadir
   • Elija un rol de acceso (Viewer / Editor / Owner) por principal
   • Opcionalmente, activa el Acceso público para que el recurso sea visible para todos en la instancia (requiere el permiso de función SHARE_PUBLIC)
4. Guardar. Los beneficiarios verán el recurso la próxima vez que actualicen.

Lo que ven los beneficiarios

• Los Viewers (espectadores) ven el recurso como un elemento listo para usar en el selector correspondiente (por ejemplo, el menú desplegable de agentes). No pueden abrir el generador, ver las instrucciones sin procesar ni modificar la configuración.
• Los Editors pueden abrir la configuración del recurso y modificarla, pero no pueden eliminarla ni volver a compartirla.
• Los Owners tienen la misma interfaz de usuario que el autor original y pueden eliminar y volver a compartir libremente.
• El autor original siempre conserva el control total independientemente del estado de la ACL, y los administradores pueden gestionar cualquier recurso en la instancia.

Herencia de proyectos

Los permisos pueden heredarse de un project padre. Cuando una entrada de ACL se hereda, el enlace inheritedFrom apunta de vuelta a la fuente. Esto es lo que impulsa al proyecto "Global" en LibreChat, donde un recurso añadido al proyecto global se vuelve disponible para todos los usuarios sin necesidad de una entrada por principal.

Capa 3: Concesiones del sistema (Capacidades de administrador)

Las concesiones del sistema (system grants) son una tabla de concesiones independiente utilizada para capacidades de nivel administrativo, que responden a preguntas como "¿Puede este usuario acceder al panel de administración?" o "¿Puede este grupo gestionar servidores MCP a nivel global?". Siempre están limitadas a un principal (usuario, grupo o rol) y a una cadena de capacidad.

Las capacidades canónicas incluyen:

Las capacidades de gestión implican su correspondiente capacidad de lectura (por ejemplo, tener manage:users otorga automáticamente read:users). Un usuario con SystemRoles.ADMIN posee implícitamente todas las capacidades; las concesiones le permiten delegar un subconjunto de poderes de administrador a entidades no administradoras sin convertirlas en administradores completos.

Las concesiones de sistema (system grants) se emiten y revocan a través del panel de administración.

Principals in Depth

Usuarios

Cuentas estándar de LibreChat. Los usuarios pueden ser locales (correo electrónico/contraseña) o federados (OAuth2, OIDC, SAML, LDAP). Los usuarios federados pueden vincularse a una identidad externa (idOnTheSource); para Entra ID, este es el OID, que es lo que permite la sincronización de grupos.

Grupos

Un grupo es una colección nombrada de usuarios. LibreChat admite dos fuentes:

• Grupos locales: creados y gestionados desde el panel de administración o directamente en la base de datos. Los miembros son IDs de usuario de LibreChat.
• Grupos de Entra ID (Azure AD): sincronizados desde Microsoft Graph cuando un usuario inicia sesión a través de Azure OIDC con token reuse habilitado. Cada grupo sincronizado almacena su Entra Object ID como idOnTheSource, lo que mantiene a LibreChat en sincronía con la membresía del inquilino.

Los grupos pueden aparecer en cualquier ACL, en la búsqueda de peoplePicker y como destino principal para anulaciones de configuración o concesiones del sistema. Un solo recurso compartido con un grupo de 500 personas es una entrada de ACL (no 500), y los cambios de membresía en Entra se propagan automáticamente en el siguiente inicio de sesión.

Roles

Cualquier sistema o rol personalizado puede utilizarse como principal. Compartir un agente con un rol (por ejemplo, SupportEngineers) otorga acceso a todos los usuarios que actualmente poseen ese rol, sin necesidad de enumerar a las personas individualmente. Los roles pueden ocultarse del selector de personas a través de interface.peoplePicker.roles para entornos donde el uso compartido basado en roles sea una preocupación exclusiva del administrador.

Público

Un principal especial que coincide con cada usuario autenticado. Las concesiones públicas solo están permitidas cuando el usuario que otorga el acceso posee el permiso de función SHARE_PUBLIC para ese tipo de recurso.

Visibilidad del selector de personas

El selector de personas (el cuadro de búsqueda en los diálogos de compartir) puede restringirse a nivel de instancia para ocultar tipos de principales que no sean relevantes para su despliegue:

interface:
  peoplePicker:
    users: true
    groups: true
    roles: false

Esto solo afecta a la interfaz de usuario de búsqueda; las entradas de ACL existentes para tipos de principal ocultos siguen funcionando y se aplican normalmente.

Migraciones desde versiones anteriores a ACL

Las versiones anteriores a v0.8.0-rc3 utilizaban un modelo de propiedad más sencillo. La actualización requiere ejecutar la migración de ACL para que los agentes y prompts existentes sigan siendo accesibles:

Dry run (vista previa de cambios):

npm run migrate:agent-permissions:dry-run
npm run migrate:prompt-permissions:dry-run

Ejecutar:

npm run migrate:agent-permissions
npm run migrate:prompt-permissions

Consulta la guía de migración de agentes para las variantes de Docker y las opciones de batch-size.

Documentación relacionada

• Agentes: Compartir y permisos
• Configuración de la interfaz (permisos de funciones)
• Autenticación
• Reutilización de tokens de OpenID Connect (requerido para la sincronización de grupos de Entra ID)
• Azure / Entra ID OAuth2
• Integración con SharePoint
• API de Agents (Agents remotos)
• Panel de administración de LibreChat