Права и области

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

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

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

Права отвечают на два разных вопроса: какое действие разрешено и на какой ресурс оно распространяется. Например, пользователь может видеть Container, но не чувствительные сведения о хосте, или управлять одним Route, не получая управление всеми Routes на его ноде Ingress. Выдавайте минимальный набор разрешений, необходимый для реального сценария, а не широкий доступ только ради появления недоступного экрана.

Правила проектирования

1. Для обычного доступа используйте группы, а прямые разрешения пользователям оставляйте для исключений.
2. Предпочитайте разрешения на конкретный ресурс доступу ко всей ноде или разделу продукта.
3. Разделяйте просмотр и изменение, раскрытие секретов, экспорт, точки монтирования и разрушительные действия.
4. Считайте API-токены и разрешения OAuth делегированными полномочиями, а не альтернативным способом получить права администратора.
5. Проверяйте полный путь пользователя: видимость навигации и отказ при прямом запросе к API.

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

Не выдавайте глобальное право управления только потому, что рабочий процесс затрагивает несколько типов ресурсов. Для публикации могут понадобиться ограниченные права на Pages Project, Domain, сертификат, Route и состояние Build Worker, но не общее администрирование нод или экспорт закрытых ключей. До использования в рабочей среде проверьте весь процесс через предполагаемую идентичность без административных прав.

Уровни областей и видимость

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

Любая область действия подразумевает просмотр тех же ресурсов: proxy:edit:<route-id> показывает этот Route, а docker:containers:manage:<node-id> — контейнеры на этой ноде. Исключение — области создания: они не подразумевают никакого просмотра, ни в общем виде, ни с ограничением папкой или нодой. См. «Подразумеваемый просмотр».

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

Ограничение доступа папкой

Право на папку ограничивает пользователя, группу, API-токен или разрешение OAuth ресурсами одной папки и её подпапок. Так удобно выдать проектной команде доступ только к её собственным ресурсам, например ко всему, что относится к MyProject.

1. Создайте папку MyProject в каждом разделе, которым пользуется команда, например в маршрутах, контейнерах Docker и базах данных. У каждого типа ресурсов своё дерево папок, поэтому папка маршрутов не охватывает контейнеры. См. «Поддержка папок по типам ресурсов».
2. Переместите в эти папки существующие ресурсы проекта. Для перемещения нужны область управления папками раздела и право изменения ресурса.
3. В редакторе группы или в дополнительных правах пользователя выберите нужные области, откройте ограничение каждой из них и выберите папку MyProject. Сохранённое право имеет вид <scope>:folder/<folder-id>.

Задача	Области, ограниченные папкой
Видеть контейнеры и развёртывания проекта и управлять ими	docker:containers:view, docker:containers:manage; docker:containers:environment, docker:containers:secrets или docker:containers:console добавляйте только при необходимости
Создавать новые контейнеры и развёртывания в папке, включая загрузку их образов	docker:containers:create
Управлять маршрутами проекта	proxy:view, proxy:edit, proxy:create
Выполнять запросы к базам данных проекта	databases:view, databases:query:read

Что видит пользователь:

• Все ресурсы папки и её подпапок, включая созданные в ней или перемещённые в неё позже. Opfield вычисляет права на папки при каждом запросе, и открытые страницы показывают новые доступные ресурсы без повторного входа.
• Больше ничего: списки содержат только разрешённые ресурсы, пустая разрешённая папка показывает пустой список, а прямые запросы к другим ресурсам отклоняются. Ресурс, перемещённый из папки, перестаёт быть виден, если у пользователя нет отдельного права на него.
• Диалоги создания предлагают только папки, в которых пользователь может создавать ресурсы. Вариант No folder скрыт, если создавать на верхнем уровне нельзя, а единственная доступная папка выбирается автоматически. В API и MCP передайте папку в folderId; создание в другом месте возвращает 403. Если ресурс работает на ноде, диалог показывает только ноды, на которых пользователь может его развернуть, не выдавая права администрирования нод.
• Одна область создания показывает папку как место назначения, но не её содержимое. Если команда должна видеть уже существующие ресурсы, выдайте на папку и область просмотра.
• Контейнеры и развёртывания, созданные из источника Git, попадают в выбранную папку, в том числе когда их позже создаёт первая сборка. Пока такой ресурс ждёт первой сборки, он показан в этой папке, и его можно переместить командой Move to folder... или перетаскиванием; первая сборка создаёт его в той папке, где он находится в этот момент. См. «Папки для рабочих нагрузок из сборки».
• Отказ в создании называет папки и ноды, где пользователь может создавать ресурсы, например 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. Создание ресурсов Docker возвращает такое сообщение и в Console, и в REST API; для других типов ресурсов тот же список папок и нод добавляют ошибки инструментов MCP и AI Workspace.

Параметр Settings > Authentication > Identity provisioning > Auto-assign permissions for created resources включён по умолчанию. Он добавляет права на каждый новый ресурс в дополнительные права его создателя: всегда — просмотр нового ресурса, а остальные области уровня ресурса — только если они уже есть у создателя в общем виде или для папки либо ноды назначения. Поэтому пользователь только с областью создания видит ровно те ресурсы, которые создал сам. Поэтому создатель с доступом к папке сохраняет тот же доступ, если ресурс позже переместят из папки, но не получает ничего нового: просмотр и создание в папке не превращаются в доступ к консоли или секретам. Выключение параметра влияет только на новые ресурсы; существующие права сохраняются, и их можно изменить в Assign permissions.

API-токены и разрешения OAuth поддерживают те же ограничения папками. Их папки раскрываются первыми, а результат затем ограничивается доступом владельца, поэтому токен никогда не видит больше, чем его владелец; см. «Ограничение токенов и разрешений OAuth».

Что доступно идентичности

GET /api/auth/me/access возвращает доступ вызывающего, сгруппированный по разделам продукта: общий он или ограниченный, выданные папки с путями, ноды, аккаунты и отдельные ресурсы с разрешёнными для каждого действиями, а также где вызывающий может создавать ресурсы (create.atRoot, create.folders, create.nodes). Запрос работает с сеансом, API-токеном и токеном OAuth и отмечает, что права токена или разрешения OAuth ограничены текущим доступом владельца. Идентификатор, имя, адрес электронной почты и группа пользователя включаются только для сеанса браузера и AI Workspace и никогда — для токена. Клиенты MCP и AI Workspace получают ту же сводку от инструмента get_my_access, а MCP также отдаёт её как ресурс gateway://access; см. «Что доступно вызывающему».

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

Ограничение доступа к Git по репозиториям

Области интеграций Git можно ограничить одним подключённым аккаунтом, а внутри него — группами и проектами GitLab или владельцами и репозиториями GitHub. Право на группу GitLab охватывает её подгруппы и все проекты в них, право на владельца GitHub — все репозитории этой организации или пользователя. В редакторе группы, дополнительных правах пользователя, форме API-токена и согласии OAuth и MCP отметьте подключение, чтобы охватить все его репозитории, или откройте под подключением Add groups or projects… (GitLab) либо Add owners or repositories… (GitHub) и найдите более узкие цели. Права хранят постоянные идентификаторы провайдера, поэтому переименование или перенос группы либо репозитория их не меняет.

Чтобы команда могла собирать один проект, выдайте integrations:gitlab:use на этот проект вместе с собственными правами рабочей нагрузки: use на проект достаточно, чтобы настроить источник сборки Docker или Pages. Не отзывайте это право: ручные сборки проверяют его заново, а автоматические сборки источника, сохранённого в этом выпуске, приостанавливаются, если сохранившая его учётная запись теряет use. API-токены и разрешения OAuth несут те же ограничения и никогда не получают доступ к репозиторию, который в этот момент недоступен их владельцу. Формат ограничений описан в разделе «Ограничения интеграций Git», а проверки каждой операции — в разделе «Ограничение доступа к репозиториям».

Операции без принятия под управление

Права Docker уровня ресурса действуют и для контейнеров, которые Opfield обнаружил, но не создавал. Команде можно разрешить перезапуск сервиса и чтение его журналов, не передавая Opfield весь хост или конфигурацию приложения.

Задача	Право	Примечания
Читать журналы, статистику и процессы одного автономного контейнера	docker:containers:view:<node-id>/<resource-id>	Отдельной области для журналов нет — их покрывает view
Запускать, останавливать, перезапускать и принудительно завершать один автономный контейнер и читать его журналы	docker:containers:manage:<node-id>/<resource-id>	manage подразумевает view для того же контейнера. Оно также разрешает принудительное завершение и пересоздание; области только для перезапуска нет
Открывать командную оболочку в этом контейнере	добавить docker:containers:console:<node-id>/<resource-id>	Доступ к консоли всегда выдаётся отдельно
Читать объединённые журналы и мониторинг внешнего проекта Compose	docker:compose:view:<node-id>/<project-id>	Работает до принятия под управление и на любом тарифе
Запускать, останавливать и перезапускать проект Compose	docker:compose:manage:<node-id>/<project-id> после принятия проекта под управление	Внешние проекты доступны только для чтения до принятия; действия жизненного цикла применяются ко всему проекту, а не к отдельным контейнерам Compose
Выдать одинаковый доступ к группе ресурсов	те же области с folder/<folder-id>	Покрывает поддерживаемые ресурсы в папке Docker и её подпапках

Автономный контейнер — любой контейнер без меток проекта Docker Compose, в том числе запущенный командой docker run. Opfield присваивает ему стабильную идентичность ресурса, которая сохраняется при пересоздании и обновлении через Opfield. Если контейнер удалить и снова запустить вне Opfield, Opfield зарегистрирует новый ресурс и отзовёт права на прежнюю идентичность. См. Контейнеры, созданные не через Opfield.

Внешний проект Compose сохраняет идентичность, пока Opfield его наблюдает. Если проект исчезает с ноды, например после docker compose down, Opfield удаляет его из инвентаря, если проект не помещён в папку Docker; при повторном появлении он получает новую идентичность, и права на прежний проект перестают совпадать. Помещайте внешние проекты, на которые выданы права уровня проекта, в папку Docker или выдавайте доступ через папку.

Важные разграничения

• Право изменять Container не даёт права изменять точки монтирования.
• Доступ к базе данных не даёт права раскрывать учётные данные.
• Право использовать Inference не даёт доступа к AI Workspace.
• Просмотр ресурса не даёт права просматривать сведения о его ноде.
• Право изменять Route не даёт права экспортировать закрытый ключ сертификата.

Для других чувствительных операций действует тот же принцип. Доступ к Console или файлам отделён от обычного просмотра рабочей нагрузки. Экспорт архива отделён от просмотра файлов или конфигурации ресурса. Право изменить секрет не означает право его раскрыть: значения, доступные только для записи, заменяются, а не извлекаются. Согласие OAuth и обнаружение инструментов MCP не добавляют областей, которых нет у пользователя-владельца.

AI Workspace и удалённый MCP используют обычную модель авторизации Opfield. Доступ к AI Workspace и использование Opfield Inference — разные возможности. Для удалённого MCP требуются собственный ресурс OAuth и mcp:use; сеансы браузера, обычные API-токены gw_, токены журналирования, токены вывода и токены OAuth для другого ресурса не взаимозаменяемы с учётными данными MCP.

Программные идентичности

Используйте отдельные учётные данные для интерактивного администрирования, CI, мониторинга и сторонних инструментов. API-токен действует с делегированными полномочиями своего пользователя Opfield. OAuth client добавляет явный жизненный цикл перенаправления и согласия. Удалённый MCP использует OAuth и показывает только инструменты, совместимые с текущей идентичностью и состоянием продукта. Отдельный токен gwi_ относится к контура данных Opfield Inference и не подходит для обычных запросов к API Opfield.

Для каждых учётных данных автоматизации укажите владельца, назначение, ожидаемый срок ротации и зависимую систему. Один раз сохраните секрет в менеджере секретов и не помещайте его в URL репозитория, историю команд, снимки экрана или журналы. Проверьте одно разрешённое и одно запрещённое действие. Если токен утрачен, создайте новый и отзовите прежний: замаскированный секрет нельзя восстановить через UI.

Отзыв прав

Сеансы, API, MCP и защищённые операции WebSocket повторно проверяют доступ. Отзыв группы, токена или разрешения ресурса должен блокировать новые привилегированные действия и при необходимости завершать защищённые потоки. Ранее открытая страница или уже обнаруженный инструмент не сохраняют полномочия после отзыва.

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

Удаление ресурса — ноды, Route, домена, сертификата, центра сертификации, списка доступа, шаблона, группы, папки, подключения, проекта Pages, базы данных, хранилища, окружения журналирования, Deployment, Compose Project или другого ресурса — убирает все права, в которых он назван, у пользователей, групп, API-токенов и разрешений OAuth и MCP, поэтому новый ресурс с тем же именем их не унаследует. Права, оставшиеся на ресурсах, удалённых до 2.11, удаляются при запуске и затем каждый час.

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

Проверка и диагностика ошибок

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

Интерпретируйте ошибки по уровню, который их выдаёт: 401 означает отсутствующую или недействительную аутентификацию; 403 обычно указывает на отсутствующую область или недоступную по тарифу функцию; 404 может означать отсутствие видимости ресурса, а не только его отсутствие; 409 указывает на конфликт жизненного цикла, квоты или текущего состояния; 422 означает недопустимые входные данные. Проверьте код и ответ конкретного API-запроса, а для асинхронной операции — сообщение Task. Не пытайтесь решить конфликт тарифа или жизненного цикла расширением прав.

Практические сценарии описаны в разделе Области, токены и OAuth.