Ámbitos, tokens de API, OAuth y MCP

Consulta la referencia de ámbitos para ver cada permiso, su descripción, las restricciones admitidas y su delegación en tokens.

El acceso programático debe ser más fácil de revocar y más restringido que la sesión de un administrador humano. El responsable de la automatización define el flujo de trabajo necesario, el responsable del recurso aprueba su alcance y el responsable de seguridad revisa la vida útil y el almacenamiento de las credenciales. El éxito significa que la integración puede realizar la acción prevista, se le deniega todo lo demás y se puede rotar sin interrumpir sistemas no relacionados.

Los usuarios gestionan los tokens de API en Profile > Authorizations > API Tokens. Los secretos se muestran una sola vez. Guárdalos en un gestor de secretos, asigna los ámbitos mínimos y revoca los tokens que no se usen.

Los clientes OAuth delegan la autoridad de un usuario con URI de redirección explícitas y consentimiento. MCP remoto usa el mismo modelo de recursos y ámbitos que REST y la consola; no es una puerta trasera privilegiada.

Usa credenciales separadas para CI, la monitorización y las herramientas interactivas. Evita los tokens de administrador de larga duración. Limita la automatización por recursos a los nodos, Routes, cargas de trabajo, bases de datos o Pages Projects exactos de los que es responsable.

Las credenciales normales de la API gw_ y las credenciales OAuth no entran en el plano de datos de Opfield Inference. La inferencia usa tokens de usuario gwi_ dedicados.

Audita la creación, el uso y la revocación de tokens. Rota de inmediato tras una sospecha de divulgación y verifica las sesiones activas por separado.

Elige el tipo de credencial

Credencial	Uso
Sesión	Acceso interactivo a la Operations Console
Token de API	Automatización directa que pertenece a un usuario de Opfield
Cliente OAuth	Autorización delegada de usuarios y aplicaciones de terceros
OAuth de MCP remoto	Clientes de herramientas que actúan a través de la superficie MCP de Opfield
Token de inferencia	Peticiones al plano de datos separado de Opfield Inference

No sustituyas un tipo por otro solo porque sea más fácil de copiar. El tipo de credencial determina el consentimiento, la revocación, la evaluación de ámbitos, la finalidad de la auditoría y la familia de endpoints a la que puede acceder.

Crea un token con el mínimo privilegio

1. Identifica las operaciones y los recursos exactos de los que es responsable la automatización.
2. Crea un usuario o una identidad de servicio dedicados cuando la atribución deba estar separada.
3. Asigna los ámbitos globales y de recursos mínimos.
4. Crea el token y anota el secreto una sola vez.
5. Guárdalo en un gestor de secretos e inyéctalo en tiempo de ejecución.
6. Prueba una petición permitida y otra denegada.
7. Registra el responsable, la finalidad, la caducidad o la rotación prevista y el sistema dependiente.

Evita incluir tokens en URL de repositorios, en el historial de comandos, en capturas de pantalla o en logs. Un valor enmascarado en la interfaz no se puede recuperar después; crea un sustituto y revoca el token antiguo cuando se pierda el secreto.

Qué pueden hacer y qué no los tokens

Los tokens de API y las concesiones OAuth para la API de Opfield o para MCP pueden tener cualquier ámbito de permisos excepto una breve lista reservada a los usuarios: los ámbitos de AI Workspace y de los AI sandboxes (ai:workspace:use, feat:ai:configure, ai:skills:manage y ai:sandbox:*), mcp:use, admin:users:impersonate e integrations:gitlab:sandbox:clone. Por tanto, el acceso programático puede gestionar los nodos y su configuración, los usuarios y los grupos, los ajustes de Opfield, los conectores de integraciones y de hosting, las VM de hosting, las operaciones de Relay, las actualizaciones, la administración de la inferencia y las claves de inferencia gwi_ personales del propietario. Cada ámbito delegado sigue limitado por los permisos actuales del propietario.

Algunas acciones siguen ligadas a una sesión interactiva en el navegador:

• crear tokens de API y autorizaciones OAuth, y el propio consentimiento OAuth;
• el chat de AI Workspace y los AI sandboxes;
• iniciar una suplantación;
• iniciar sesión, y cambiar los métodos de inicio de sesión, el MFA, las passkeys o las sesiones del propio propietario; un token que lo intente devuelve SELF_SIGN_IN_PROGRAMMATIC;
• gestionar las credenciales personales de GitLab.

Como ahora los tokens pueden tener ámbitos administrativos, trata un token con ámbitos de administrador como una cuenta de administrador: dale un responsable, una caducidad y un alcance de recursos reducido cuando sea posible.

Opfield 2.11 renombró varios ámbitos. La creación de tokens, los parámetros OAuth scope y las ediciones de autorizaciones OAuth siguen aceptando los nombres antiguos durante dos versiones y guardan los nuevos; los tokens y las concesiones existentes se convirtieron durante la actualización. Un token o una petición OAuth nuevos para un ámbito como integrations:github:manage reciben también los ámbitos que la actualización añadió para él (en este caso repo:read) cuando los tienes; la pantalla de consentimiento los muestra y puedes desmarcarlos. Los ámbitos que requieren aprobación manual, como repo:write o pki:ca:export, nunca se añaden así. Consulta Nombres de ámbitos retirados.

Restringe los tokens y las concesiones OAuth

Un token o una concesión OAuth se pueden limitar a carpetas, nodos, entornos de apps o recursos individuales de la misma forma que los permisos de un usuario. Una restricción por carpeta cubre la carpeta, sus subcarpetas y los recursos que se creen en ella o se muevan a ella más adelante. Consulta Restringe el acceso a una carpeta.

• Tokens de API: el diálogo de tokens de Profile > Authorizations > API Tokens muestra el acceso del token como una lista. Add Access añade una línea. En Resources, elige un Role, Where se aplica (Everywhere, In a project folder, In an app environment o Specific resources) y qué Covers; en Git repositories, elige un conector, los repositorios y el nivel de acceso. El diálogo solo ofrece lo que tú mismo puedes conceder.
• Selector de ámbitos: Review N scopes, en la parte inferior del diálogo de tokens y de la pantalla de consentimiento de OAuth y MCP, abre los propios ámbitos. La cabecera de cada sección muestra hasta dónde llegan sus ámbitos: Everywhere, un lugar o N places. Haz clic en ella para elegir entre las carpetas, las apps y los entornos que contienen ese tipo de recurso. Los ámbitos de una sección la siguen; Only this scope… da a un ámbito su propia restricción. Un ámbito que solo tienes para algunos recursos muestra No resources selected hasta que los eliges.
• Consentimiento de OAuth y MCP: la pantalla de consentimiento muestra lo que pide el cliente como líneas de acceso. Los ámbitos de alto riesgo quedan fuera de la concesión hasta que los apruebas en Review N scopes. Para cambiar más adelante los ámbitos y las restricciones de una autorización existente, ábrela en Profile > Authorizations > OAuth Applications, edita Scopes y haz clic en Save Scopes.
• Integraciones de Git: el selector de ámbitos restringe los ámbitos de Git a un conector, un grupo o proyecto de GitLab, o un propietario o repositorio de GitHub, con Add groups or projects… o Add owners or repositories… bajo cada conector. Un token así se comprueba contra su propia restricción y contra tu acceso actual a Git en cada operación con un repositorio, de modo que deja de llegar a un repositorio en cuanto pierdes el acceso a él. Consulta Restricciones de las integraciones de Git.

Opfield expande primero las restricciones propias del token por carpetas y nodos y limita después el resultado por tu acceso actual, de modo que un token nunca ve más que tú. Una concesión de creación nunca cuenta como concesión de visualización cuando la delegas. Si un cliente pide un ámbito amplio que solo tienes para algunos recursos, Opfield reduce la concesión a esos recursos.

OAuth y MCP

Registra URI de redirección exactas y rechaza el comportamiento de redirección con comodines. Revisa los ámbitos solicitados durante el consentimiento y separa los clientes de desarrollo de los de producción. El consentimiento deja sin marcar por defecto los ámbitos de alto riesgo para que haya que seleccionarlos explícitamente, por ejemplo admin:system, admin:users, admin:groups, settings:opfield:edit, nodes:manage, proxy:raw:write, proxy:unrestricted, proxy:templates:manage, pki:ca:export, las credenciales de sistema de los conectores (integrations:*:use), integrations:ssh:use, las acciones de hosting de pago o destructivas, storage:credentials:reveal, storage:iam, databases:backups:restore y feat:ai:use. Las herramientas de MCP remoto usan las mismas comprobaciones de autorización y la misma visibilidad de recursos que REST y la consola; descubrir una herramienta no concede permiso para ejecutarla.

Trata los fallos de autorización por separado:

• 401: autenticación ausente, caducada o no válida;
• 403: la identidad autenticada no tiene el ámbito o el derecho del plan necesarios;
• 409: el estado actual del recurso o una cuota entran en conflicto con la operación;
• 422: la validación de la petición ha fallado.

Los códigos de autorización y los tokens OAuth caducados, y los clientes OAuth que llevan 90 días sin ninguna concesión, se eliminan con la categoría de mantenimiento Expired OAuth Grants; un token de actualización se conserva hasta que caduca para que se siga detectando su reutilización. Consulta Mantenimiento y retención.

Rotación y respuesta ante incidentes

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, invalida por separado las sesiones relacionadas y rota cualquier secreto posterior que pueda haber quedado expuesto.

Diseño de ámbitos y propiedad

Empieza por la operación, no por el nombre de un rol. Enumera las llamadas exactas de lectura y de modificación que necesita la integración y vincula después los ámbitos de recursos al límite de propiedad estable más pequeño: una carpeta, un nodo, una Route, una carga de trabajo, una base de datos o un Pages Project. Añade un ámbito global solo cuando el flujo de trabajo abarque de verdad todos los recursos de ese tipo. Separa los permisos de visualización, revelación, exportación, consola, montaje, secretos y ciclo de vida; el acceso de lectura normal no debe implicar acceso a credenciales ni a operaciones sensibles del host.

Cada credencial necesita un responsable humano, un consumidor máquina, una finalidad, un entorno y una condición de retirada. Un token que usa CI no debe usarse también para la sesión de terminal de un operador. Los clientes OAuth de producción y de otros entornos deben tener ID de cliente, URI de redirección, secretos y registros de consentimiento distintos. Cuando cambia el responsable, transfiere o sustituye la credencial en lugar de dejarla asociada a la cuenta de un usuario que se ha marchado.

Verificación operativa

Antes de activar la automatización en producción:

1. llama a un endpoint de lectura inofensivo con la nueva credencial;
2. realiza un cambio previsto sobre un recurso desechable;
3. demuestra que un recurso fuera del ámbito está oculto o se deniega;
4. confirma que la atribución de la auditoría identifica al usuario o al cliente OAuth esperado;
5. verifica que los valores de los tokens, las cabeceras de autorización y los parámetros de callback se ocultan en los logs;
6. revoca la credencial y demuestra que el consumidor falla de forma segura;
7. instala el sustituto y documenta el orden de rotación probado.

Revocar un token de API no termina automáticamente las sesiones del navegador, las concesiones OAuth, los tokens de inferencia ni las credenciales guardadas en proveedores externos. Durante un incidente, inventaría cada familia de credenciales por separado.