Permisos y ámbitos

Opfield usa ámbitos explícitos. Un ámbito tiene una base de capacidad y puede incluir un sufijo de recurso.

docker:containers:view
docker:containers:view:<node-id>/<resource-id>
databases:view:<database-id>
nodes:details:<node-id>

La base de capacidad describe la acción permitida. Un sufijo de recurso limita esa acción a un nodo o a la identidad de un recurso. Opfield evalúa la identidad autenticada, las concesiones efectivas de grupo y directas, la propiedad de los recursos, el estado actual del producto y los derechos del plan en el límite de cada operación del backend. La visibilidad en la navegación y los controles desactivados ayudan a los usuarios a entender su acceso, pero no son autorización.

Los permisos responden a dos preguntas separadas: qué acción está permitida y qué recurso está en el ámbito. Un usuario puede ver un Container sin ver los detalles sensibles del host, o gestionar una Route sin gestionar todas las Routes de su nodo Ingress. Prefiere la concesión más pequeña que permita el flujo de trabajo real en lugar de dar un acceso amplio para evitar que falte una pantalla.

Reglas de diseño

1. Concede a través de grupos para el acceso normal; reserva las adiciones directas a usuarios para las excepciones.
2. Prefiere las concesiones limitadas por recurso a las de un nodo completo o un área completa del producto.
3. Separa la visualización de la modificación, la revelación de secretos, la exportación, los montajes y las acciones destructivas.
4. Trata los tokens de API y las concesiones OAuth como autoridad delegada, no como administradores alternativos.
5. Prueba el recorrido resultante del usuario, incluidas la visibilidad en la navegación y la denegación directa por API.

Empieza por el trabajo que debe hacer la identidad. Enumera las acciones de lectura necesarias para descubrir y verificar el destino, las acciones de modificación necesarias para cambiarlo y cualquier dato o acción destructiva protegidos por separado. Después limita cada concesión al recurso, el nodo o la carpeta exactos a los que pertenece el trabajo. La pertenencia a grupos suele ser más fácil de revisar y revocar que muchas concesiones directas a usuarios.

No concedas un ámbito de gestión global solo porque el flujo de trabajo abarque varios tipos de recursos. Un flujo de publicación puede necesitar un acceso limitado a un Pages Project, un dominio, un certificado, una Route y el estado de un Build Worker, sin necesitar la administración general de nodos ni la exportación de claves privadas. Prueba el flujo de trabajo completo con la identidad sin privilegios de administrador prevista antes de usarlo en producción.

Niveles de ámbito y visibilidad

Los ámbitos globales se aplican en toda el área del producto permitida. Las concesiones limitadas a un nodo restringen las operaciones a los recursos de un nodo gestionado concreto cuando el contrato del recurso admite ese ámbito. Las concesiones limitadas a un recurso identifican un recurso duradero de Opfield. Las carpetas pueden agrupar los recursos compatibles e intervenir en el diseño del acceso, pero mover un recurso a una carpeta no cambia su propiedad en ejecución ni su camino de red.

Cualquier ámbito de acción implica la visualización de los mismos recursos: proxy:edit:<route-id> muestra esa Route, y docker:containers:manage:<node-id> muestra los contenedores de ese nodo. Los ámbitos de creación son la excepción: no implican ninguna visualización, tanto si son amplios como si están limitados a una carpeta o a un nodo. Consulta Acceso de visualización implícito.

Las apps son visibles con apps:view sobre la app o sobre uno de sus entornos. Sin él, un usuario sigue viendo una app cuando puede ver uno de sus miembros (un contenedor, un Deployment, un proyecto Compose, una base de datos, un almacenamiento, una Route o un sitio de Pages) gracias a sus propias concesiones sobre el recurso, sobre la carpeta del entorno o sobre la carpeta de la app. Entonces solo ve los entornos que contienen esos miembros y solo esos miembros, y la vista general, la actividad y los incidentes se limitan a ellos. Las variables, los nodos permitidos, el mantenimiento, la promoción y todas las acciones de la app siguen necesitando sus ámbitos de app.

La visibilidad de los recursos y la visibilidad de los hosts son distintas a propósito. Un usuario puede operar una carga de trabajo asignada sin conocer el inventario de hosts no relacionado. La búsqueda, la navegación, REST, el descubrimiento de MCP, las suscripciones en tiempo real y las peticiones directas a los recursos deben aplicar todas las mismas reglas de acceso efectivo. Un elemento de navegación oculto no demuestra una denegación; verifica también una petición directa.

Restringe el acceso a una carpeta

Una concesión de carpeta limita a un usuario, un grupo, un token de API o una concesión OAuth a los recursos que hay dentro de una carpeta y de sus subcarpetas. Es adecuada para un equipo de proyecto que solo debe ver y operar sus propios recursos, por ejemplo todo lo que pertenece a MyProject.

1. Crea una carpeta MyProject en cada área que use el equipo, por ejemplo Routes, contenedores Docker y bases de datos. Cada tipo de recurso tiene su propio árbol de carpetas, así que una carpeta de Routes no cubre contenedores. Consulta Compatibilidad con carpetas por tipo de recurso.
2. Mueve los recursos existentes del proyecto a esas carpetas. Mover un recurso requiere el ámbito de gestión de carpetas del área y acceso de edición al recurso.
3. En el editor de grupos o en los permisos adicionales del usuario, selecciona los ámbitos que necesita el equipo, abre la restricción de cada ámbito y elige la carpeta MyProject. La concesión guardada tiene la forma <scope>:folder/<folder-id>.

Objetivo	Ámbitos restringidos a la carpeta
Ver y operar los contenedores y Deployments del proyecto	docker:containers:view, docker:containers:manage; añade docker:containers:environment, docker:containers:secrets o docker:containers:console solo cuando sea necesario
Crear contenedores y Deployments nuevos en la carpeta, incluida la descarga de sus imágenes	docker:containers:create
Gestionar las Routes del proyecto	proxy:view, proxy:edit, proxy:create
Consultar las bases de datos del proyecto	databases:view, databases:query:read

Lo que ve el usuario:

• Todos los recursos de la carpeta y de sus subcarpetas, incluidos los que se creen en ella o se muevan a ella más adelante. Opfield resuelve las concesiones de carpeta en cada petición, y las páginas abiertas recogen los recursos que pasan a ser visibles sin volver a iniciar sesión.
• Nada más: las listas solo muestran los recursos concedidos, una carpeta concedida que todavía está vacía muestra una lista vacía y las peticiones directas a otros recursos se deniegan. Un recurso que sale de la carpeta deja de ser visible salvo que el usuario tenga una concesión aparte para él.
• Los diálogos de creación solo ofrecen las carpetas en las que el usuario puede crear. No folder se oculta cuando el usuario no puede crear en el nivel superior, y la única carpeta permitida aparece preseleccionada. A través de la API o de MCP, pasa la carpeta como folderId; crear en otro sitio devuelve 403. Cuando un recurso se ejecuta en un nodo, el diálogo solo enumera los nodos en los que el usuario puede desplegar, sin conceder la administración de nodos.
• Un ámbito de creación por sí solo muestra la carpeta como destino, pero nada de su contenido. Concede también un ámbito de visualización sobre la carpeta cuando el equipo deba ver lo que ya hay allí.
• Los Containers y los Deployments creados a partir de un origen Git van a la carpeta elegida, también cuando el primer build los crea más tarde. Mientras uno espera su primer build, aparece en esa carpeta y se puede mover con Move to folder… o arrastrándolo; el primer build lo crea después en la carpeta en la que esté en ese momento. Consulta Carpeta de las cargas de trabajo construidas.
• Una creación rechazada indica las carpetas y los nodos donde el usuario sí puede crear, por ejemplo Missing docker:containers:create at the root (no folder). Your docker:containers:create access is limited to folder 'MyProject' (<id>): pass folderId for one of them. Las creaciones de Docker devuelven este mensaje en la consola y en la REST API; para otros tipos de recursos, los errores de las herramientas de MCP y de AI Workspace añaden la misma lista de carpetas y nodos.

Settings > Authentication > Identity provisioning > Auto-assign permissions for created resources está activado por defecto. Añade concesiones para cada recurso nuevo a los permisos adicionales de su creador: siempre la visualización del nuevo recurso, y otros ámbitos por recurso solo cuando el creador ya los tiene de forma amplia o sobre la carpeta o el nodo de destino. Así, un usuario con solo un ámbito de creación ve exactamente los recursos que ha creado. Un creador limitado a una carpeta conserva el mismo acceso si el recurso se saca después de la carpeta, pero no gana nada nuevo: ver y crear en una carpeta no se convierten en acceso a la consola ni a los secretos. Desactivar el ajuste solo afecta a los recursos nuevos; las concesiones existentes se mantienen y se pueden cambiar en Assign permissions.

Los tokens de API y las concesiones OAuth aceptan las mismas restricciones de carpeta. Sus carpetas se resuelven primero y el resultado se limita después por el propio acceso del propietario, de modo que un token nunca ve más que su propietario; consulta Restringe los tokens y las concesiones OAuth.

Comprueba a qué puede llegar una identidad

GET /api/auth/me/access devuelve el acceso de quien llama agrupado por área del producto: si es amplio o limitado, las carpetas concedidas con sus rutas, los nodos, las cuentas y los recursos individuales con las acciones permitidas en cada uno, y dónde puede crear quien llama (create.atRoot, create.folders, create.nodes). Funciona con una sesión, un token de API o un token OAuth, e indica que un token o una concesión OAuth están limitados por el acceso actual de su propietario. El ID, el nombre, el correo y el grupo del usuario solo se incluyen para una sesión del navegador y para AI Workspace, nunca para un token. Los clientes MCP y AI Workspace obtienen el mismo resumen con la herramienta get_my_access, y MCP también lo sirve como el recurso opfield://access; consulta Averigua a qué puede acceder quien llama.

El acceso limitado a carpetas es normal para los agentes y la automatización. Una lista devuelve solo lo que quien llama puede ver, así que una lista vacía en la raíz no es una denegación. Cuando pruebes una identidad limitada a carpetas, lee primero su resumen de acceso y crea después en una de las carpetas indicadas con folderId.

Restringe el acceso a Git a determinados repositorios

Los ámbitos de las integraciones de Git se pueden limitar a una cuenta conectada y, por debajo, a grupos y proyectos de GitLab o a propietarios y repositorios de GitHub. Una concesión sobre un grupo de GitLab cubre sus subgrupos y todos los proyectos que hay debajo; una concesión sobre un propietario de GitHub cubre todos los repositorios de esa organización o ese usuario. En el editor de grupos, en los permisos adicionales de un usuario, en el formulario de tokens de API y en el consentimiento de OAuth y MCP, marca un conector para cubrir todos sus repositorios, o abre Add groups or projects… (GitLab) o Add owners or repositories… (GitHub) bajo el conector y busca destinos más concretos. Las concesiones guardan ID estables del proveedor, así que renombrar o mover un grupo o un repositorio no las cambia.

Para que un equipo construya desde un proyecto, concede integrations:gitlab:use sobre ese proyecto junto a los permisos propios de la carga de trabajo: use sobre el proyecto basta para configurar un origen de build de Docker o de Pages. Mantén esa concesión: los builds manuales la vuelven a comprobar, y los builds automáticos de un origen guardado en esta versión se pausan cuando la cuenta que lo guardó pierde use. Los tokens de API y las concesiones OAuth llevan las mismas restricciones y nunca llegan a un repositorio al que su propietario no pueda llegar en ese momento. Consulta Restricciones de las integraciones de Git para el formato de los calificadores y Restringe el acceso a los repositorios para ver qué comprueba cada operación.

Opera cargas de trabajo sin adoptarlas

Los permisos de Docker limitados por recurso funcionan sobre los contenedores que Opfield descubrió pero no creó. Puedes dejar que un equipo reinicie un servicio y lea sus logs sin entregar a Opfield todo el host ni la configuración de la aplicación.

Objetivo	Concesión	Notas
Leer los logs, las estadísticas y los procesos de un contenedor independiente	docker:containers:view:<node-id>/<resource-id>	No hay un ámbito aparte para los logs; view los cubre
Iniciar, detener, reiniciar o matar un contenedor independiente y leer sus logs	docker:containers:manage:<node-id>/<resource-id>	manage implica view sobre el mismo contenedor. También permite matar y recrear; no hay un ámbito solo de reinicio
Abrir una shell en ese contenedor	añade docker:containers:console:<node-id>/<resource-id>	El acceso a la consola siempre es una concesión aparte
Leer los logs agregados y la monitorización de un proyecto Compose externo	docker:compose:view:<node-id>/<project-id>	Funciona antes de la adopción y en todos los planes
Iniciar, detener o reiniciar un proyecto Compose	docker:compose:manage:<node-id>/<project-id> después de adoptar el proyecto	Los proyectos externos son de solo lectura hasta la adopción; las acciones de ciclo de vida se aplican al proyecto completo, no a contenedores de Compose individuales
Aplicar el mismo acceso a un grupo de recursos	los mismos ámbitos con folder/<folder-id>	Cubre los recursos compatibles de la carpeta de Docker y de sus subcarpetas

Un contenedor independiente es cualquier contenedor sin etiquetas de proyecto de Docker Compose, incluido uno iniciado con docker run. Opfield le da una identidad de recurso estable que sobrevive a las operaciones de recreación y actualización realizadas a través de Opfield. Si el contenedor se elimina y se vuelve a iniciar fuera de Opfield, Opfield registra un recurso nuevo y revoca las concesiones sobre la identidad anterior. Consulta Contenedores que Opfield no creó.

Un proyecto Compose externo conserva su identidad mientras Opfield lo observa. Si el proyecto desaparece del nodo, por ejemplo tras docker compose down, Opfield lo elimina del inventario salvo que el proyecto esté en una carpeta de Docker; cuando vuelve a aparecer, recibe una identidad nueva, y las concesiones sobre la identidad anterior del proyecto dejan de coincidir. Coloca en una carpeta de Docker los proyectos externos que tengan concesiones limitadas al proyecto, o concede el acceso a través de la carpeta.

Separaciones importantes

• Editar un contenedor no implica editar sus montajes.
• Acceder a una base de datos no implica revelar sus credenciales.
• Usar la inferencia no implica acceder a AI Workspace.
• Ver un recurso no implica ver los detalles de su nodo host.
• Editar una Route no implica exportar la clave privada de su certificado.

Otras operaciones sensibles siguen el mismo principio. El acceso a la consola o a los archivos es independiente de la visualización normal de las cargas de trabajo. La exportación de archivos es independiente de la visualización de los archivos o de la configuración del recurso. Modificar un secreto no implica revelarlo, y los valores de solo escritura se sustituyen en lugar de recuperarse. El consentimiento OAuth y el descubrimiento de herramientas de MCP no añaden ámbitos que el usuario propietario no tenga.

AI Workspace y MCP remoto siguen dentro de la autorización normal de Opfield. El acceso a AI Workspace y el uso de Opfield Inference son capacidades separadas. MCP remoto requiere su propio recurso OAuth y mcp:use; las sesiones del navegador, los tokens de API gw_ normales, los tokens de logging, los tokens de inferencia o los tokens OAuth emitidos para otro recurso no son credenciales MCP intercambiables.

Identidades programáticas

Usa credenciales separadas para la administración interactiva, CI, la monitorización y las herramientas de terceros. Un token de API actúa con la autoridad delegada de su usuario de Opfield. Un cliente OAuth añade un ciclo de vida explícito de redirección y consentimiento. MCP remoto usa OAuth y solo expone las herramientas compatibles con la identidad y el estado actuales del producto. Un token gwi_ dedicado pertenece al plano de datos de Opfield Inference y no se puede usar como una credencial normal de la API de Opfield.

Crea las credenciales de automatización con un responsable, una finalidad, una rotación prevista y un sistema dependiente conocido. Guarda los secretos una sola vez en un gestor de secretos, nunca en URL de repositorios, en el historial de comandos, en capturas de pantalla ni en logs. Prueba una acción permitida y otra denegada. Si se pierde un token, crea un sustituto y revoca el valor antiguo; los secretos enmascarados no se pueden recuperar desde la interfaz.

Revocación

Las operaciones de sesión, API, MCP y WebSocket protegidas vuelven a validar el acceso. Revocar un grupo, un token o una concesión sobre un recurso debe detener las nuevas acciones privilegiadas y terminar los flujos protegidos cuando sea necesario. Una página cargada previamente o una herramienta descubierta no conservan la autoridad tras la revocación.

Cuando cambien las responsabilidades de un usuario, revisa juntos la pertenencia a grupos, las concesiones directas, las sesiones activas, los tokens de API, las concesiones OAuth y las dependencias de automatización. Bloquear a un usuario detiene el uso nuevo sin borrar la atribución. Eliminar a un usuario conserva los registros de auditoría históricos, y restaurar un registro eliminado no lo reactiva silenciosamente. Se rechaza eliminar al último administrador.

Eliminar un recurso (un nodo, una Route, un dominio, un certificado, una CA, una Access List, una plantilla, un grupo, una carpeta, un conector, un Pages Project, una base de datos, un almacenamiento, un entorno de logging, un Deployment, un Compose Project, una app u otro recurso) elimina todos los permisos que lo nombran de los usuarios, los grupos, los tokens de API y las concesiones OAuth y MCP, de modo que un recurso posterior con el mismo nombre nunca los hereda. Los permisos que quedaron sobre recursos eliminados antes de la 2.11 se eliminan al arrancar y cada hora.

Para rotar credenciales, crea el sustituto, actualiza el sistema dependiente, verifica que se usa correctamente y revoca después la credencial antigua. Tras una sospecha de divulgación, revoca primero cuando sea operativamente seguro, inspecciona la actividad de auditoría y los ID de petición, invalida por separado las sesiones relacionadas y rota cualquier secreto posterior que pueda haber quedado expuesto.

Verificación y diagnóstico de fallos

Prueba los permisos desde la identidad que los va a usar, no desde una cuenta de administrador. Confirma la visibilidad esperada en la navegación y en la búsqueda, lee el recurso de destino, realiza una operación permitida e intenta una operación claramente fuera del ámbito. Para la automatización, prueba también un fallo de validación y el seguimiento de un Task asíncrono.

Interpreta con precisión los fallos habituales: 401 indica autenticación ausente o no válida; 403 suele significar que falta un ámbito o un derecho del plan; 404 puede reflejar la visibilidad del recurso además de su ausencia; 409 indica un conflicto de ciclo de vida, de cuota o de estado actual; y 422 indica una entrada no válida. No resuelvas un conflicto de derechos del plan o de ciclo de vida ampliando los permisos.

Consulta Ámbitos, tokens y OAuth para ver los flujos de trabajo de implementación.