Перейти к содержимому
Поиск
Разработка

OpenFGA: права доступа в Node.js — модели, группы и 8 задач

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

Александр Некрасов
OpenFGA: права доступа в Node.js — модели, группы и 8 задач — обложка

OpenFGA: кто может открыть, изменить и передать документ

В CRM сотрудник работает с заявками своей команды. В проектном сервисе заказчик видит согласованные документы, редактор меняет материалы проекта, администратор организации управляет рабочим пространством. Одна глобальная роль user или admin быстро перестаёт описывать такие правила: право зависит и от человека, и от конкретного объекта, и от связей между ними.

OpenFGA помогает вынести эту логику в отдельную модель авторизации. Приложение задаёт вопрос: может ли user:boris выполнить can_edit над document:alpha? Сервис проверяет отношения и возвращает ответ. При этом сам документ продолжает храниться в вашей базе, а вход пользователя остаётся задачей приложения.

В этой статье разберём восемь практических ситуаций, запустим настоящий сервер в Docker, обратимся к нему из Node.js и посмотрим, как защитить HTTP-обработчик. Мини-мастерская показывает записанные результаты реальных запусков на Windows и Linux: можно менять пользователя, документ, действие и состояние связей, сравнивая решения и исходные запросы.

Где пригодится такая модель доступа

Хороший кандидат — сервис, в котором один человек имеет разные полномочия над разными объектами. Например, редактор проекта может читать все его документы, но отдельный материал дополнительно доступен приглашённому консультанту. В CRM менеджер получает заявки через команду, а руководитель — через организацию. В системе обучения преподаватель управляет своим курсом, участник видит материалы группы, гость получает доступ к отдельному занятию.

Модель отношений полезна и при развитии продукта. Команда добавляет совместный доступ, перенос между проектами или новые роли и хочет понимать, какие правила изменились. Вместо разрозненных проверок в нескольких сервисах появляется определённая схема и набор положительных и отрицательных тестов.

Для маленькой закрытой страницы с двумя постоянными ролями отдельный сервис может оказаться лишним. OpenFGA добавляет сетевые запросы, хранение отношений, обслуживание и вопросы согласованности. Выбирать его стоит после описания реальных сценариев, а не потому, что любую проверку if обязательно нужно заменить инфраструктурой.

Аутентификация и авторизация решают разные задачи

Аутентификация устанавливает личность: пользователь вошёл по сессии, предъявил проверенный токен или прошёл другой предусмотренный вход. Авторизация отвечает на следующий вопрос: что этой личности разрешено сделать с конкретным ресурсом? OpenFGA работает со второй частью. Он не проверяет пароль посетителя и не превращает переданную браузером строку user:alice в доказанную личность.

Сервер приложения должен получить subject из доверенного контекста после проверки сессии. Из URL допустимо извлечь идентификатор документа, но действие выбирает сам обработчик: чтение проверяет can_view, изменение — can_edit. Если разрешить клиенту самостоятельно прислать пользователя и нужное отношение, он сможет спрашивать от имени владельца вместо себя.

В учебном HTTP-примере есть две фиксированные вымышленные сессии. Они нужны для воспроизводимой проверки и не являются готовой системой входа. Про проверку подписанных токенов отдельно можно прочитать в материале jose: JWT, подпись и ключи в Node.js. Служебный ключ доступа к OpenFGA также не заменяет пользовательскую сессию.

Мини-мастерская: восемь задач и матрица решений

Начните с выбора сценария. Затем поменяйте пользователя, документ и действие. Цветная карточка показывает разрешение или отказ, ниже видны конкретный запрос и ответ сервера. Матрица позволяет сравнить сразу всех участников. Рядом расположены фактические связи и полная модель, поэтому решение можно сопоставить с данными, на которых оно получено.

В сценарии отзыва доступны три последовательных состояния. Переключайте их и следите за Борисом: удаление прямого права ещё не закрывает доступ через группу. В сценариях Check, ListObjects и серверной проверки есть дополнительные записанные ответы. Можно скачать выбранный сценарий, раскрыть исходник, скопировать код или сохранить отдельный файл.

Публичная мастерская не обращается к открытому серверу авторизации. Она читает JSON, записанный при настоящем выполнении SDK и HTTP-запросов в изолированном стенде. Это позволяет спокойно изучать матрицу без служебных ключей в браузере. Для собственных данных скачайте проект и повторите capture локально: произвольные новые связи публичная страница не вычисляет.

Версии и устройство скачиваемого проекта

В проекте закреплены OpenFGA 1.22.1, официальный JavaScript SDK 0.9.8 и Bootstrap 5.3.9. Образ сервера указан с digest, зависимости Node устанавливаются через npm ci и lock-файл. Это делает исходный набор воспроизводимым; дальнейшие обновления стоит проводить отдельно, повторяя тесты поведения и миграций.

Каталог src содержит модель, сценарии, клиент, сборщик записей и пример защищённого HTTP-обработчика. В web находятся исходные файлы интерфейса, в public — готовая страница, локальный CSS, модель, записи Windows/Linux и просмотр исходников. Для изучения уже готовой мастерской сервер OpenFGA запускать не требуется.

Основные первичные материалы: обзор моделирования OpenFGA, установка через Docker и официальный JavaScript SDK. Ниже показана собственная учебная политика, а не универсальный набор прав для любого бизнеса. Смысл owner, viewer и администратора организации задаёт автор модели.

Фрагмент package.json

{
 "name":"aen-openfga-workshop","version":"1.0.0","private":true,"type":"module","license":"MIT","engines":{"node":">=24.15"},
 "scripts":{"capture":"node src/capture.mjs","build":"node tools/build.mjs","serve":"node tools/serve.mjs","test":"node --test tests/*.test.mjs"},
 "dependencies":{"@openfga/sdk":"0.9.8","bootstrap":"5.3.9"}
}

Windows: запуск сервера и настоящих проверок

Распакуйте архив в отдельную папку, запустите Docker Desktop с Linux-контейнерами и откройте PowerShell в корне проекта. Понадобятся Node.js 24 LTS и npm. Compose поднимет собственный сервер на 127.0.0.1:18088. Сначала дождитесь успешного ответа healthz, затем устанавливайте зависимости и запускайте capture.

Capture создаёт восемь временных stores, записывает модель и отношения, выполняет запросы и сохраняет ответы. Каждый созданный store удаляется в finally. Скрипт принимает только два заданных локальных адреса стенда и не предназначен для запуска против рабочей системы прав. Если меняете порт, согласуйте его с ограничением в src/client.mjs.

После тестов сборка обновляет public, а команда serve открывает локальный просмотр на порту 8554. Остановить сервер просмотра можно через Ctrl+C. Если нужно лишь полистать готовые примеры, достаточно npm run serve: этот маленький HTTP-сервер использует стандартные модули Node и не подключается к OpenFGA.

Фрагмент README.md

docker compose -p aen-openfga-lab up -d openfga
Invoke-RestMethod http://127.0.0.1:18088/healthz
npm ci --ignore-scripts --no-audit --no-fund
npm run capture
npm test
npm run build
npm run serve
# http://127.0.0.1:8554/

Linux: тот же проект на машине разработчика и сервере

На Linux логика запуска такая же: отдельная папка проекта, Docker с Compose, Node.js и зависимости из lock-файла. Не переносите node_modules с Windows. Установите зависимости заново, дождитесь healthz, выполните capture и тесты. Полученная Linux-запись появится рядом с Windows-записью, а мастерская позволит выбрать платформу клиента.

В проверочном Compose есть и готовый Linux-клиент на Node 24.22.2. Команда run –rm linux копирует проект во временный каталог контейнера, устанавливает зависимости и вызывает настоящий API сервиса openfga. Хостовый каталог подключён для чтения; результат записывается в специально выбранную папку public. Сервер OpenFGA в обоих случаях работает в Linux-контейнере, поэтому Windows здесь означает платформу Node-клиента.

Для VPS нужно другое хранение и защита служебного API; это разобрано ниже. Лабораторный запуск на выделенном сервере не превращает memory datastore в постоянную базу. Основы сети, сервисов и команд собраны также в статье Docker Compose для PHP и Node.js.

Фрагмент README.md

docker compose -p aen-openfga-lab up -d openfga
curl --fail http://127.0.0.1:18088/healthz
npm ci --ignore-scripts --no-audit --no-fund
npm run capture
npm test
npm run build
npm run serve

Фрагмент README.md: Linux-клиент в контейнере

docker compose -p aen-openfga-lab run --rm linux

Почему учебный сервер закрыт на loopback

В лаборатории используется memory datastore: удобно создать чистые данные и повторить эксперимент, но хранить рабочие права между перезапусками так нельзя. API опубликован только на 127.0.0.1, Playground отключён, порты базы и дополнительные интерфейсы наружу не выставляются. Браузерный просмотр работает отдельно и раздаёт статические файлы.

Внутри сети Compose проверочный клиент обращается к openfga:8080. Доступ по HTTP без аутентификации здесь относится к собственному изолированному тесту. Такой пример нельзя переносить на публичный адрес без изменения архитектуры. Управляющее API умеет менять отношения и модели, поэтому его доступность важнее удобства открыть страницу с любого устройства.

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

Фрагмент compose.yaml

services:
  openfga:
    image: openfga/openfga:v1.22.1@sha256:b852071314f1fda1194d341a6ebac0a4f619b3cd87a6626d2ccc7048af4ec671
    command: [run]
    environment:
      OPENFGA_DATASTORE_ENGINE: memory
      OPENFGA_PLAYGROUND_ENABLED: "false"
      OPENFGA_LOG_FORMAT: json
    ports:
      - "127.0.0.1:18088:8080"

Store, модель, типы и отношения: четыре основных понятия

Store объединяет набор моделей и отношений. Модель определяет типы объектов, возможные отношения и правила вычисления прав. Отдельная связь, tuple, говорит, что конкретный пользователь или набор пользователей имеет отношение к конкретному объекту. Например, user:alice связан как owner с document:alpha.

В нашем примере есть user, group, organization, project и document. Идентификаторы после двоеточия выбирает приложение. Они не обязаны быть именами людей: для рабочей системы обычно удобнее стабильные внутренние ID. Отображаемое имя и содержание документа OpenFGA хранить не требуется — они остаются в прикладной базе.

Клиент закрепляет storeId и authorizationModelId. Это помогает воспроизводимо понимать, по каким правилам обрабатывается запрос. Новая версия модели получает собственный ID; её внедрение требует проверки совместимости связей и клиентов. Сохраните исходное описание модели в репозитории, а выбранный ID — в конфигурации приложения, рядом с понятным процессом обновления.

Фрагмент src/client.mjs

export function isolatedClient({storeId, authorizationModelId} = {}) {
  const apiUrl = process.env.FGA_API_URL || 'http://127.0.0.1:18088';
  if (!['http://127.0.0.1:18088', 'http://openfga:8080'].includes(apiUrl)) {
    throw new Error('Capture accepts only the isolated workshop endpoint.');
  }
  return new OpenFgaClient({
    apiUrl, storeId, authorizationModelId,
    retryParams: {maxRetry: 0}, baseOptions: {timeout: 3000}
  });
}

Прямая связь и вычисляемое разрешение

Отношения owner, editor и viewer в учебной модели могут содержать непосредственно записанные связи. Разрешения can_edit и can_view вычисляются из них. Владелец или редактор может изменять документ, а тот, кто может изменять, также может читать. Эта цепочка выражена явно, поэтому не нужно отдельно записывать владельцу ещё и viewer.

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

Вспомогательные функции в исходнике собирают JSON модели: direct описывает прямое отношение, relation ссылается на другое отношение, union объединяет пути, from проходит через связанный объект. Это обычный авторский JavaScript для создания конфигурации; решения по этой конфигурации принимает настоящий OpenFGA.

Фрагмент src/model.mjs

const direct = () => ({this: {}});
const relation = name => ({computedUserset: {relation: name}});
const union = (...child) => ({union: {child}});
const from = (tupleset, computed) => ({tupleToUserset: {
  tupleset: {relation: tupleset}, computedUserset: {relation: computed}
}});
const allow = (...types) => ({directly_related_user_types:
  types.map(value => typeof value === 'string' ? {type: value} : value)
});

Сценарий 1. Владелец, читатель и человек без доступа

Откройте первый сценарий и сравните Алису, Веру и Олега. Алиса записана владельцем document:alpha и получает оба разрешения. Вера имеет viewer: читать можно, изменять нельзя. У Олега нет подходящих связей, поэтому оба запроса возвращают false. Все три случая важны: проверка только счастливого пути пропустит лишний доступ.

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

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

Фрагмент src/model.mjs

export const tuple = (user, relation, object) => ({user, relation, object});

Сценарий 2. Группа вместо ручной выдачи каждому человеку

Во втором сценарии Борис входит в group:editors. Участники этой группы связаны как editor с document:alpha. Запись group:editors#member обозначает набор членов конкретной группы. Когда сервер проверяет Бориса, он находит путь через членство и разрешает редактирование и чтение. Вера не входит в группу и доступа не получает.

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

Сначала определите, кто управляет составом группы и как изменение синхронизируется с кадровыми или организационными данными. Если исходная система уже удалила сотрудника, а связь member осталась, старый путь доступа сохранится. Тесты членства должны сопровождать как добавление, так и удаление и повторную доставку события.

Фрагмент src/model.mjs

{type: 'group', relations: {member: direct()}, metadata: {relations: {
    member: allow('user')
  }}},

Сценарий 3. Организация и проверка границ между клиентами

Здесь Лена состоит в organization:north, а Алиса является её администратором. Проект red связан с north, документ alpha — с red. В нашей политике обычный участник организации читает её документы, администратор также редактирует. Это выбор для демонстрации, а не обязательная семантика OpenFGA.

Переключите объект на beta. Он принадлежит проекту blue организации south, поэтому отношения с north не дают доступа. Такая отрицательная проверка особенно нужна в SaaS: пользователь одного клиента не должен получать документы другого через случайную общую роль. Полезно явно включать соседнюю организацию в тестовые данные, а не ограничиваться одним tenant.

Для чувствительных материалов правило «любой участник видит всё» может быть слишком широким. Можно убрать этот путь и выдавать права через проекты или конкретные документы. Продумайте и перенос объекта между организациями: смена прикладного поля tenant_id без соответствующего обновления отношений оставит две системы в разном состоянии.

Фрагмент src/model.mjs

{type: 'organization', relations: {member: direct(), admin: direct()},
    metadata: {relations: {
      member: allow('user', {type: 'group', relation: 'member'}),
      admin: allow('user')
  }}},

Сценарий 4. Документ наследует доступ от проекта

В четвёртом сценарии Борис — редактор project:red. Документ alpha связан с этим проектом отношением parent и наследует can_edit, а вместе с ним can_view. У beta нет такого родителя, поэтому доступ Бориса к red на него не распространяется. Вера при этом может читать beta по отдельной прямой связи.

Наследование подходит для папок, задач, вложений и документов проекта. Оно сокращает количество повторяющихся отношений, но требует ясного смысла родительской связи. В учебной модели parent у документа указывает именно на project; произвольную строку другого типа сервер не должен принимать как подходящую связь.

Обратите внимание на структуру правила: from обращается к разрешению родительского проекта. Поэтому изменение правил проекта может повлиять на все связанные документы. Перед таким обновлением проверьте несколько уровней и независимые объекты. При необходимости исключений «этот документ закрыт даже участникам проекта» потребуется специально спроектированная политика, а не надежда, что отсутствие прямого viewer перекроет наследование.

Фрагмент src/model.mjs

{type: 'document', relations: {
    parent: direct(), owner: direct(), editor: direct(), viewer: direct(),
    can_edit: union(relation('owner'), relation('editor'), from('parent', 'can_edit')),
    can_view: union(relation('viewer'), relation('can_edit'), from('parent', 'can_view'))
  }, metadata: {relations: {
    parent: allow('project'), owner: allow('user'),
    editor: allow('user', {type: 'group', relation: 'member'}),
    viewer: allow('user', {type: 'group', relation: 'member'})
  }}}

Сценарий 5. Check: отказ в доступе и ошибка запроса

Обычный ответ Check содержит allowed. Значение false означает, что по выбранной модели и отношениям право не найдено. Неизвестное отношение does_not_exist — другая ситуация: реальный API возвращает ошибку 400. Это неправильный запрос или несогласованная версия клиента, а не штатный отказ конкретному человеку.

В мастерской сравните оба результата. В коде полезно возвращать разрешение только при явном allowed === true, а исключения обрабатывать отдельно. Пользователь без прав получает понятный отказ, а команда разработки видит, что сервис вызван с неверной моделью или названием операции. Подменять все ошибки значением «доступ есть» недопустимо для защищённого ресурса.

В журнал диагностики обычно достаточно ID операции, типа объекта, кода ошибки и времени ответа. Не требуется записывать содержимое документа или служебный токен. Если текст ошибки показывается посетителю, отделите внутренние подробности от безопасного сообщения: названия внутренних объектов и модель могут быть лишними для публичного интерфейса.

Фрагмент src/client.mjs

export async function isAllowed(client, user, permission, object) {
  const response = await client.check({user, relation: permission, object}, consistency);
  return response.allowed === true;
}

Фрагмент src/capture.mjs: настоящий некорректный запрос

let failure;
   try{await client.check({user:'user:alice',relation:'does_not_exist',object:'document:alpha'},consistency);}catch(error){failure={status:error.statusCode||error.response?.status,code:error.responseData?.code||error.response?.data?.code||error.code,message:error.responseData?.message||error.message};}
   check('Invalid relation rejected by actual API',failure?.status===400);
   extra.invalidCheck={request:{user:'user:alice',relation:'does_not_exist',object:'document:alpha'},error:failure};

Сценарий 6. ListObjects для личного кабинета

Часто нужно не проверить один известный документ, а наполнить список доступными объектами. ListObjects получает пользователя, отношение и тип, затем возвращает подходящие ID. В шестом сценарии Алиса видит собственный alpha, Борис — beta и gamma через проект, Вера — gamma по прямому viewer, а Олег получает пустой список.

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

В мастерской результаты ListObjects сопоставлены с матрицей Check для всех трёх учебных документов. Когда пользователь затем открывает документ или выполняет действие, сервер снова проверяет актуальное право. Старый список в браузере не становится бессрочным разрешением: связи могли измениться между отображением кабинета и следующим запросом.

Фрагмент src/capture.mjs

extra.lists=[];
   for(const user of actors){const answer=await client.listObjects({user,relation:'can_view',type:'document'},consistency);extra.lists.push({request:{user,relation:'can_view',type:'document'},objects:(answer.objects||[]).sort()});}

Сценарий 7. Почему удаление viewer иногда ничего не меняет

У Бориса одновременно есть прямая связь viewer и право editor через group:editors. В первом состоянии он может читать и изменять alpha. Удаляем прямое viewer: чтение сохраняется, потому что can_edit через группу также входит в can_view. Это ожидаемый результат объединения путей, а не сбой отзыва.

Во втором изменении удаляется членство Бориса в группе. Теперь ни один путь не даёт ему разрешения, поэтому оба Check возвращают false. В мастерской можно переключить все три состояния, увидеть оставшиеся tuples и сравнить ответы. Именно такой пример помогает объяснить пользователю, почему кнопка «убрать участника документа» иногда не равна полному запрету доступа.

В реальном интерфейсе управления полезно показывать источник полномочия: прямое приглашение, группа, проект или организация. Перед обещанием «доступ отозван» определите, удалены ли все нужные пути. Если бизнесу требуется явный запрет поверх других разрешений, его следует отдельно выразить и протестировать в модели.

Фрагмент src/capture.mjs

await client.deleteTuples([tuple('user:boris','viewer','document:alpha')]);
   const second=await matrix(client,scenario.objects);phases.push({id:'direct-removed',title:'Удалили прямое viewer',tuples:scenario.tuples.filter(t=>t.relation!=='viewer'),queries:second});
   check('Removing direct viewer leaves group path',allowed(second,'user:boris','can_view')&&allowed(second,'user:boris','can_edit'));
   await client.deleteTuples([tuple('user:boris','member','group:editors')]);
   const third=await matrix(client,scenario.objects);phases.push({id:'membership-removed',title:'Удалили членство в группе',tuples:[tuple('group:editors#member','editor','document:alpha')],queries:third});

Сценарий 8. Защищаем HTTP-обработчик на сервере

Последний сценарий запускает настоящий небольшой HTTP-сервер и обращается к нему через fetch. Владелец получает документ с кодом 200. Запрос без учебной сессии получает 401, посторонний пользователь — 403. Попытка добавить в query user:alice и relation=owner остаётся запрещённой: обработчик берёт subject из своей таблицы сессий и сам выбирает can_view.

Проверка выполняется до выдачи тела документа. Для обновления данных аналогичное условие должно стоять перед записью; для файлов — перед отправкой содержимого или формированием ограниченной ссылки. Скрытая кнопка в интерфейсе улучшает удобство, но не защищает прямой HTTP-запрос к серверу.

В рабочем приложении добавьте проверку настоящей сессии, нормализацию идентификатора ресурса и обработку отсутствующего объекта. Решите, где уместно различать 403 и 404, чтобы не раскрывать существование закрытого документа. Учебный пример намеренно использует один вымышленный ресурс и не изображает готовую CRM или полноценный модуль входа.

Фрагмент src/enforcement.mjs

export async function startDocumentApi(client){
 const server=createServer(async(req,res)=>{
  const send=(status,body)=>{res.writeHead(status,{'Content-Type':'application/json; charset=utf-8','Cache-Control':'no-store'});res.end(JSON.stringify(body));};
  const url=new URL(req.url,'http://localhost');
  if(req.method!=='GET'||url.pathname!=='/documents/alpha'){send(404,{error:'not_found'});return;}
  const token=(req.headers.authorization||'').replace(/^Bearer /,'');
  const subject=demoSessions.get(token);
  if(!subject){send(401,{error:'authentication_required'});return;}
  // subject and permission come from trusted server context, never query parameters.
  try{
   if(!await isAllowed(client,subject,'can_view','document:alpha')){send(403,{error:'forbidden'});return;}
   send(200,{id:'alpha',title:'Учебный документ',body:'Вымышленные данные проекта.'});
  }catch{send(503,{error:'authorization_unavailable'});}
 });

Если сервис прав недоступен: таймаут и отказ без утечки

Чтобы проверить отказ инфраструктуры, тест открывает свободный loopback-порт и закрывает его. Настоящий SDK обращается к этому недоступному endpoint, получает ошибку соединения, а HTTP-обработчик возвращает 503 без тела документа. Основной сервер OpenFGA для этого не останавливается. В мастерской сохранён именно результат такого запроса, а не вручную подставленный статус.

Это поведение называют fail-closed: невозможность подтвердить право не выдаёт защищённые данные. Одновременно 503 позволяет отличить временную проблему сервиса от обычного отсутствия полномочия. Интерфейс может предложить повторить попытку, а мониторинг — сообщить команде об отказе зависимости.

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

Фрагмент src/service-client.mjs: шаблон доверенного клиента

export function serviceClient(env=process.env){
 for(const key of ['OPENFGA_API_URL','OPENFGA_STORE_ID','OPENFGA_MODEL_ID','OPENFGA_API_KEY'])if(!env[key])throw new Error('Missing configuration: '+key);
 const url=new URL(env.OPENFGA_API_URL);
 const local=['127.0.0.1','localhost','openfga'].includes(url.hostname);
 if(url.protocol!=='https:'&&!(url.protocol==='http:'&&local))throw new Error('Remote authorization endpoint requires HTTPS.');
 return new OpenFgaClient({
  apiUrl:url.href.replace(/\/$/,''),storeId:env.OPENFGA_STORE_ID,
  authorizationModelId:env.OPENFGA_MODEL_ID,
  credentials:{method:CredentialsMethod.ApiToken,config:{token:env.OPENFGA_API_KEY}},
  retryParams:{maxRetry:1,minWaitInMs:100},baseOptions:{timeout:1500}
 });
}

Consistency: что означает более строгая проверка

В запросах лаборатории используется HIGHER_CONSISTENCY. Это особенно показательно при отзыве: после удаления отношения мы сразу проверяем результат. В OpenFGA этот выбор связан с обходом кеша для проверки; детали и ограничения описаны в официальной документации consistency. Его не следует понимать как общую транзакцию между сервисом прав и всеми базами приложения.

Наша проверка выполнена против одного локального memory-сервера. Она подтверждает последовательность write, delete и check в этом стенде, но не измеряет распределённую задержку рабочей инфраструктуры. Реплики, сетевые ошибки, повторная доставка событий и выбранное хранение требуют отдельных испытаний.

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

Фрагмент src/client.mjs

export const consistency = {consistency: ConsistencyPreference.HigherConsistency};

Данные приложения и отношения должны оставаться согласованными

OpenFGA не знает, существует ли документ в вашей прикладной базе и действительно ли он переехал в другую организацию. Он видит переданные отношения. Если транзакция создания документа прошла, а запись прав потерялась, объект может оказаться недоступен. Если удаление документа завершилось, а отношения остались, появятся устаревшие связи.

Для таких переходов полезен управляемый процесс: прикладное изменение и событие фиксируются вместе, обработчик доставляет изменение отношений, хранит результат и умеет безопасно повторить операцию. Конкретная схема зависит от базы и требований продукта; шаблон outbox часто помогает не потерять событие между двумя системами. Это не даёт автоматической атомарности всего распределённого процесса.

Отдельно определите поведение повторной выдачи и удаления уже отсутствующей связи. Ошибка API не всегда означает, что нужного состояния нет: запрос мог примениться, а ответ — потеряться. Тестируйте восстановление и сверку состояния на собственных переходах, сохраняя ID операции и достаточный журнал без секретов.

Модель в репозитории и безопасное изменение правил

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

Сохраните тестовый набор с владельцем, читателем, посторонним пользователем, соседней организацией и альтернативными путями. Затем создайте новую модель, проверьте её отдельно и явно переключите model ID нужных клиентов. Не рассчитывайте, что использование «последней модели» само обеспечит согласованный переход всех сервисов.

В исходниках лаборатории модель строится в JavaScript и передаётся API как JSON. Тот же подход позволяет хранить её рядом с тестами, но для большой политики можно выбрать другой удобный инструмент разработки модели. Существенно, чтобы источник, опубликованный ID и реально исполняемые правила были связаны и воспроизводимо проверялись.

Фрагмент src/capture.mjs: запись и чтение модели

const written=await storeClient.writeAuthorizationModel(model);const authorizationModelId=written.authorization_model_id;
  const client=isolatedClient({storeId,authorizationModelId});
  await client.writeTuples(scenario.tuples);
  const actualModel=await client.readAuthorizationModel();
  check(`${scenario.key}: canonical model read back`,isDeepStrictEqual(noDefaults(actualModel.authorization_model.type_definitions),noDefaults(model.type_definitions)));

Linux/VPS: постоянный PostgreSQL и порядок запуска

В архиве есть отдельный compose.production.example.yaml. Он показывает PostgreSQL, шаг migrate и запуск OpenFGA с постоянным хранилищем. Это шаблон размещения, а не заявление о проверенном production-развёртывании. В лаборатории испытывался memory-сервер; отказоустойчивость, восстановление PostgreSQL и работа под вашей нагрузкой требуют собственной приёмки.

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

Порт базы наружу не публикуется. Данные находятся в именованном volume, который переживает замену контейнера. Это необходимое хранение, но ещё не резервная копия. Образ OpenFGA закреплён версией и digest; миграции и откат нужно рассматривать вместе со схемой базы и используемыми клиентами.

Фрагмент compose.production.example.yaml

postgres:
    image: postgres:17.12-bookworm
    environment:
      POSTGRES_USER: openfga
      POSTGRES_DB: openfga
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set a unique database password}
    volumes:
      - fga-postgres:/var/lib/postgresql/data
    healthcheck:
      test: [CMD-SHELL, pg_isready -U openfga -d openfga]
      interval: 5s
      timeout: 5s
      retries: 10
    restart: unless-stopped
  migrate:
    image: openfga/openfga:v1.22.1@sha256:b852071314f1fda1194d341a6ebac0a4f619b3cd87a6626d2ccc7048af4ec671
    command: [migrate]
    environment:
      OPENFGA_DATASTORE_ENGINE: postgres
      OPENFGA_DATASTORE_URI: ${OPENFGA_DATASTORE_URI:?Set PostgreSQL URI}
    depends_on:
      postgres:
        condition: service_healthy

Служебные ключи и закрытая конфигурация

Production-шаблон требует пароль PostgreSQL, URI подключения и отдельный API key сервиса прав. Файл с ними должен находиться вне Git и публичного каталога, с ограниченными правами чтения. Пароль в URI кодируется как компонент URL: специальные символы нельзя просто вставлять в строку подключения без обработки.

Preshared-ключ подтверждает доверенный сервисный клиент. Он не ограничивает этот клиент вашей ролью viewer и не представляет конечного пользователя. Поэтому нельзя отдавать такой ключ JavaScript в браузере или произвольному внешнему интегратору. Подробнее о поддерживаемых механизмах: аутентификация доступа к OpenFGA API.

Команда config –quiet проверяет Compose без печати раскрытых значений. Переменные контейнера всё равно доступны администратору Docker, поэтому полномочия на управление хостом должны соответствовать этой чувствительности. Для хранения конфигурации в репозитории пригодится отдельная практика SOPS + age; расшифрованный файл по-прежнему требует защиты на сервере.

Фрагмент VPS.md

sudo install -d -m 700 -o "$USER" /srv/openfga
install -m 600 /dev/null /srv/openfga/secrets.env
# Заполните файл своим способом управления секретами.
docker compose --env-file /srv/openfga/secrets.env \
  -p private-fga -f compose.production.example.yaml config --quiet
docker compose --env-file /srv/openfga/secrets.env \
  -p private-fga -f compose.production.example.yaml up -d

HTTPS, reverse proxy и сетевые границы

Если приложение и OpenFGA находятся в одной закрытой сети Compose, API можно вообще не публиковать на хосте. Когда сервис прав расположен на отдельном узле, ограничьте доступ сетью и настройте HTTPS с проверяемым сертификатом. Передача API key через открытое соединение за пределами доверенной границы не подходит для рабочей системы.

В VPS.md показан пример приватного Nginx virtual host: допустимая подсеть, TLS и proxy_pass на loopback. Домен, сертификат и адреса нужно заменить своими. Заголовок Authorization должен доходить до OpenFGA; не удаляйте его случайной общей настройкой прокси. Внешнее открытие всех портов ради диагностики здесь не требуется.

Если SDK сообщает об ошибке сертификата, исправьте доверие, имя и цепочку сертификатов. Отключение TLS-проверки меняет свойства соединения и не устраняет причину. Повседневные настройки прокси и таймаутов разобраны в статье Nginx: proxy, кеш и диагностика.

Фрагмент VPS.md

server {
    listen 443 ssl;
    server_name fga.internal.example;
    ssl_certificate /etc/ssl/fga/fullchain.pem;
    ssl_certificate_key /etc/ssl/fga/privkey.pem;
    allow 10.20.0.0/16;
    deny all;
    location / {
        proxy_pass http://127.0.0.1:18088;
        proxy_set_header Host $host;
        proxy_connect_timeout 2s;
        proxy_read_timeout 5s;
    }
}

Резервная копия и проверяемое восстановление

Для восстановления нужны не только файлы контейнера: сохраняйте базу отношений, исходную модель, выбранные model ID, версию сервера и конфигурацию. Volume защищает от исчезновения контейнера, но не от ошибки оператора, повреждения хоста или ошибочного изменения полномочий. Резервную копию храните отдельно по принятой политике.

Ниже приведён Linux-пример pg_dump для шаблона Compose. Пароль читается внутри контейнера из его конфигурации, а дамп попадает в закрытый каталог. Команды выполняются оператором, которому разрешено управление именно этим стендом. Ошибка pg_dump должна прерывать процедуру; ненулевой размер файла и хеш сами по себе ещё не доказывают успешное восстановление.

Проверяйте архив через pg_restore –list и восстанавливайте копию в отдельный экземпляр PostgreSQL. После восстановления повторите положительные и отрицательные запросы прав. Обновление OpenFGA сначала испытывайте на такой копии с миграцией: возврат старого бинарника после изменения схемы не обязательно является безопасным откатом.

Фрагмент VPS.md

set -eu
umask 077
mkdir -p /srv/openfga/backups
backup_path="/srv/openfga/backups/fga-$(date -u +%Y%m%dT%H%M%SZ).dump"
docker compose --env-file /srv/openfga/secrets.env \
  -p private-fga -f compose.production.example.yaml exec -T postgres \
  sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' \
  > "$backup_path"
test -s "$backup_path"
sha256sum "$backup_path"

Производительность и наблюдение за системой прав

Стоимость проверки зависит от модели, количества отношений и путей, выбранных запросов и инфраструктуры. Не переносите задержку маленькой лаборатории на каталог из миллионов объектов. Замеряйте конкретные Check и ListObjects при типичной и неблагоприятной структуре данных, включая глубокие связи и широкие группы.

Наблюдайте время ответа, сетевые таймауты, ошибки API, состояние базы и использование соединений. Большое число allowed:false может быть обычной работой продукта; рост 503 или неверных отношений означает другую проблему. Разделение этих показателей помогает не искать неисправность авторизации там, где пользователи просто открывают недоступные ресурсы.

Кеш разрешений ускоряет повторные операции, но меняет ожидания от отзыва. Выберите его срок и область применения осознанно, особенно для удаления и передачи чувствительных объектов. Рекомендации по эксплуатации и настройке собраны в официальном разделе production; готовые цифры производительности нужно получать на своей политике и данных.

Что действительно проверено в этом проекте

Клиент на Windows с Node 24.19.0 и клиент в Linux с Node 24.22.2 выполнили по 36 проверок настоящего API. Для каждой платформы сохранено 140 ответов Check по восьми сценариям, пять результатов ListObjects и пять запросов к демонстрационному HTTP-серверу. Проверены модель после чтения с сервера, прямые и наследуемые права, соседняя организация, некорректное отношение и последовательный отзыв.

Дополнительно на каждой платформе прошли шесть тестов структуры результатов и конфигурации клиента. Они проверяют явные boolean-ответы, альтернативный путь доступа, отсутствие тела документа при отказах и совпадение хешей с точными файлами проекта. Семантические результаты Windows и Linux совпали. В каждой записи указаны версии и механизм выполнения, чтобы их можно было связать с исходниками.

Эти испытания не подтверждают рабочую PostgreSQL-инсталляцию, кластер, корпоративный вход или восстановление production. Браузерная проверка интерфейса отделяется от API-тестов; узкая ширина в браузере также не является испытанием физического телефона. Такая граница позволяет использовать результаты по назначению и заранее понимать, что нужно проверить в своей среде.

Фрагмент tests/records.test.mjs

test('server enforcement rejects query impersonation and fails closed',()=>{const http=r.records.find(x=>x.key==='enforcement').extra.http;assert.deepEqual(http.map(x=>x.status),[200,401,403,403,503]);assert.ok(http.slice(1).every(x=>!('body'in x.body)));});
test('record provenance matches exact tested source bytes',async()=>{for(const [path,expected]of Object.entries(r.sourceHashes))assert.equal(createHash('sha256').update(await readFile(path)).digest('hex'),expected,path);});

Как встроить подход в собственное приложение

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

Затем оформите управление отношениями: кто может приглашать участника, менять группу, переносить документ и отзывать доступ. Эти операции также должны иметь собственные разрешения и журнал. Опишите, как прикладная база и OpenFGA догоняют друг друга после ошибки, и какой статус видит оператор, пока изменение не завершено.

Архив содержит модель, восемь сценариев, реальный SDK-клиент, HTTP-пример, записи запусков, интерфейс, тесты и инструкции Windows/Linux/VPS. Авторский код распространяется под MIT, SDK — Apache 2.0, Bootstrap — MIT; тексты лицензий лежат рядом. Меняйте учебную политику под свой продукт и повторяйте capture: мастерская покажет уже ваши проверенные результаты.