Области, API-токены, OAuth и MCP

Все права, их описания, поддерживаемые ограничения и доступность для токенов перечислены в справочнике скоупов.

Программный доступ должен быть уже и проще отзываться, чем сеанс администратора-человека. Владелец автоматизации определяет нужный сценарий, владелец ресурса согласует охват, а владелец безопасности проверяет срок действия и хранение учётных данных. Успех означает, что интеграция выполняет назначенное действие, получает отказ вне своих областей и ротируется без остановки несвязанных систем.

Пользователи управляют API-токенами в Profile > Authorizations > API Tokens. Секрет показывается один раз. Храните его в менеджере секретов, назначайте минимальные области и отзывайте неиспользуемые токены.

Клиенты OAuth делегируют полномочия пользователя с явно заданными URI перенаправления и согласием. Удалённый MCP использует ту же модель ресурсов и областей, что REST API и Console; это не привилегированный обходной путь.

Используйте отдельные учётные данные для CI, мониторинга и интерактивных инструментов. Избегайте долговременных токенов администратора. Ограничивайте автоматизацию конкретными нодами, Routes, рабочими нагрузками, базами данных или проектами Pages, за которые она отвечает.

Обычные учётные данные API с префиксом gw_ и учётные данные OAuth не действуют в контура данных Opfield Inference. Для Inference используются отдельные пользовательские токены gwi_.

Записывайте создание, использование и отзыв токенов в аудит. При подозрении на раскрытие немедленно выполняйте ротацию и отдельно проверяйте активные сеансы.

Выберите тип учётных данных

Учётные данные	Использование
Session	Интерактивный доступ к Operations Console
API token	Прямая автоматизация от имени одного пользователя Opfield
OAuth client	Делегированная авторизация пользователя и сторонние приложения
Remote MCP OAuth	Клиенты инструментов, работающие через поверхность MCP Opfield
Inference token	Запросы к отдельной контура данных Opfield Inference

Не подменяйте один тип другим только потому, что его проще скопировать. Тип учётных данных определяет согласие, отзыв, оценку областей, назначение аудита и семейство доступных адресов API.

Создайте токен с минимальными правами

1. Определите точные операции и ресурсы, которыми управляет автоматизация.
2. Создайте отдельного пользователя или служебную идентичность, если атрибуцию нужно разделить.
3. Назначьте минимальные глобальные области и области ресурсов.
4. Создайте токен и один раз сохраните секрет.
5. Поместите его в менеджер секретов и передавайте только во время выполнения.
6. Проверьте один разрешённый и один запрещённый запрос.
7. Зафиксируйте владельца, назначение, ожидаемый срок действия и ротацию и зависимую систему.

Не встраивайте токены в URL репозитория, историю команд, снимки экрана или журналы. Замаскированное значение из UI нельзя получить повторно; при утрате создайте замену и отзовите прежний токен.

Что токены могут и не могут делать в 2.11

API-токены и разрешения OAuth для Opfield API или MCP могут содержать любую область прав, кроме короткого списка областей только для пользователей: областей AI Workspace и песочниц AI (ai:workspace:use, feat:ai:configure, ai:skills:manage и ai:sandbox:*), mcp:use, inference:setup, admin:users:impersonate и integrations:gitlab:sandbox:clone. Поэтому программный доступ позволяет управлять нодами и их конфигурацией, пользователями и группами, настройками Opfield, коннекторами интеграций и хостинга, виртуальными машинами хостинга, операциями Relay, обновлениями, администрированием Inference и личными ключами Inference gwi_ владельца. Каждая делегированная область остаётся ограничена текущими правами владельца.

Некоторые действия по-прежнему требуют интерактивного сеанса в браузере:

• создание API-токенов и авторизаций OAuth, а также само согласие OAuth;
• чат AI Workspace и песочницы AI;
• запуск Impersonation;
• вход, а также изменение собственных способов входа владельца, MFA, Passkeys или сеансов; токен, который пытается это сделать, получает SELF_SIGN_IN_PROGRAMMATIC;
• управление личными учётными данными GitLab.

Поскольку токены теперь могут содержать административные области, относитесь к токену с административными областями как к учётной записи администратора: назначьте ему владельца, срок действия и, по возможности, узкую область ресурсов.

В Opfield 2.11 переименован ряд областей. Создание токенов, параметр OAuth scope и изменение авторизаций OAuth ещё два выпуска принимают старые имена и сохраняют новые; существующие токены и разрешения преобразованы при обновлении. Новый токен или запрос OAuth с областью, например integrations:github:manage, также получает области, добавленные для неё при обновлении (здесь repo:read), если они есть у вас; экран согласия показывает их, и их можно снять. Области, требующие ручного подтверждения, например repo:write или pki:ca:export, так не добавляются. См. «Устаревшие имена скоупов».

Ограничение токенов и разрешений OAuth

Токен или разрешение OAuth можно ограничить папками, нодами или отдельными ресурсами так же, как права пользователя. Ограничение папкой охватывает папку, её подпапки и ресурсы, созданные в ней или перемещённые в неё позже. См. «Ограничение доступа папкой».

• API-токены: в Profile > Authorizations > API Tokens у каждой выбранной области, которая поддерживает ограничения, есть свой выбор папок, нод и ресурсов. В нём доступно только то, что можете использовать вы сами.
• Согласие OAuth и MCP: ограничения сначала свёрнуты. Для области, которая есть у вас в общем виде, показано All resources · Restrict…; для области, которая есть у вас только для части ресурсов, — No resources selected, пока вы их не выберете. Limit selected scopes to folder… сразу применяет одну папку ко всем выбранным областям этого типа ресурсов. Области и ограничения существующей авторизации OAuth можно позже изменить в Profile > Authorizations.
• Интеграции Git: в обеих формах области Git можно ограничить подключением, группой или проектом GitLab либо владельцем или репозиторием GitHub с помощью Add groups or projects… или Add owners or repositories… под каждым подключением. Такой токен при каждой операции с репозиторием проверяется и по собственному ограничению, и по вашему текущему доступу к Git, поэтому теряет доступ к репозиторию, как только его теряете вы. См. «Ограничения интеграций Git».

Opfield сначала раскрывает собственные ограничения токена папками и нодами, а затем ограничивает результат вашим текущим доступом, поэтому токен никогда не видит больше, чем вы. Право создания при делегировании никогда не считается правом просмотра. Если клиент запрашивает общую область, которая есть у вас только для части ресурсов, Opfield сужает разрешение до этих ресурсов.

OAuth и MCP

Регистрируйте точные URI перенаправления и запрещайте URI с подстановочными шаблонами. Проверяйте запрошенные области при выдаче согласия и отделяйте клиенты разработки от клиентов рабочей среды. По умолчанию согласие оставляет области высокого риска невыбранными, чтобы их приходилось выбирать явно, — например admin:system, admin:users, admin:groups, settings:gateway:edit, nodes:manage, proxy:raw:write, proxy:unrestricted, proxy:templates:manage, pki:ca:export, системные учётные данные коннекторов (integrations:*:use), integrations:ssh:use, платные или разрушительные действия хостинга, storage:credentials:reveal, storage:iam, databases:backups:restore и feat:ai:use. Инструменты удалённого MCP используют те же проверки авторизации и видимость ресурсов, что REST API и Console; обнаружение инструмента не выдаёт права на его выполнение.

Обрабатывайте ошибки авторизации раздельно:

• 401: аутентификация отсутствует, истекла или недействительна;
• 403: аутентифицированной идентичности не хватает области или права по тарифу;
• 409: текущее состояние ресурса или квота конфликтует с операцией;
• 422: запрос не прошёл валидацию.

Просроченные коды авторизации и токены OAuth, а также клиенты OAuth без разрешений в течение 90 дней удаляются категорией автоматической очистки Expired OAuth Grants; токен обновления хранится до истечения срока, чтобы его повторное использование по-прежнему обнаруживалось. См. «Автоматическая очистка и хранение».

Ротация и реагирование на инциденты

Создайте замену, обновите зависимую систему, подтвердите успешное использование и только затем отзовите прежние учётные данные. При подозрении на раскрытие сначала отзовите их, если это безопасно для работы сервиса, проверьте аудит, отдельно завершите связанные сеансы и замените каждый зависимый секрет, который мог быть раскрыт.

Проектирование областей и владение

Начинайте с операции, а не с названия роли. Перечислите точные вызовы чтения и изменения, затем ограничьте области ресурсов минимальной стабильной границей владения: Folder, нодой, Route, рабочей нагрузкой, базой данных или Pages Project. Добавляйте глобальную область только тогда, когда процесс действительно работает со всеми ресурсами этого типа. Разделяйте права просмотра, раскрытия, экспорта, Console, монтирования, секретов и жизненного цикла: обычное чтение не должно давать доступ к учётным данным или чувствительным операциям хоста.

У каждых учётных данных должны быть владелец, машинный потребитель, назначение, среда и условие удаления. Токен CI не должен одновременно использоваться в интерактивном терминале оператора. Для клиентов OAuth в рабочей и нерабочей средах нужны разные идентификаторы клиентов, URI перенаправления, секреты и записи согласия. При смене владельца замените учётные данные, а не оставляйте их в учётной записи ушедшего сотрудника.

Операционная проверка

Перед включением автоматизации в рабочей среде:

1. вызовите безопасный адрес чтения API с новыми учётными данными;
2. выполните одно ожидаемое изменение одноразового ресурса;
3. докажите, что ресурс вне области скрыт или запрещён;
4. убедитесь, что аудит указывает ожидаемого пользователя или OAuth client;
5. проверьте маскирование токенов, заголовков авторизации и параметров обратного вызова в журналах;
6. отзовите учётные данные и подтвердите, что потребитель безопасно прекращает работу;
7. установите замену и зафиксируйте проверенный порядок ротации.

Отзыв API token не завершает автоматически сеансы браузера, разрешения OAuth, токены Inference или учётные данные внешних поставщиков. Во время инцидента проверяйте каждое семейство отдельно.