Англійська для розробників OpenFGA

OpenFGA є відкритим, тонко-зеренним рушієм авторизації, заснованим на роботі Google Zanzibar — замість жорсткого кодування «if role == admin» перевірок по всій вашій кодовій базі, ви визначаєте модель авторизації і зберігаєте права доступу як корені відносин, які оцінюються центральною службою. Словник невідомий навіть досвідченим розробникам, оскільки він запозичує реляційну і теоретичну мову графів, а не типові терміни доступу за ролями. Вот что нужно вашей команде, чтобы обсудить это точно.

---

Модель авторизації

** Модель авторизації ** — схема, яка визначає існуючі типи об’ єктів (документи, теки, команди) і можливі зв’ язки між ними (власник, редактор, переглядач); її версії перевіряються і оцінюється за допомогою кожної перевірки прав доступу.

• “Ми випустили нову версію моделі авторизації, яка додає до документів відношення « рецензент » — старі кортежі все ще перевіряються за допомогою цього відношення, оскільки існуючі відношення залишено неушкодженими.” *

** Визначення типу ** — частина моделі, яка описує один тип об’ єкта і відносини, які він підтримує, зокрема, як ці відносини можна успадкувати (наприклад, редактори теки автоматично є редакторами документів, які знаходяться у ній).

• “В визначенні типу теки вказано, що доступ редактора каскадується до кожного документа, що знаходиться всередині теки, отже, нам не потрібно писати окрему кортежну функцію для кожного файла.” *

** Відношення ** — з’ єднання з назвою між користувачем (або набором користувачів) і об’ єктом, наприклад, « власник », « переглядач » або « член » — це будівельний блок, що використовується для розв’ язання кожної перевірки прав доступу.

• “Перед додаванням нового відношення перевірте, чи існуюче відношення вже не покриває випадок використання — кожне нове відношення додає поверхню обслуговування до моделі.” *

---

Кільця і перевірки

Кількість зв’ язків

Relationship tuple є збереженим фактом — user:anna is owner of document:budget-2026 — який представляє одну конкретну надання доступу.

“Коли користувача додають до команди, ми пишемо кореня зв’ язку, який зв’ язує їх як членів — цей один запис розблоковує всі ресурси, до яких команда має доступ.”

Перевірка API

Check API відповідає на одне так/ні питання — «чи може цей користувач виконати цю дію на цьому об’єкті?» — розв’язуючи авторизаційну модель проти збережених кортежів.

“Кожна кнопка « може редагувати » в інтерфейсі користувача викликає API Перевірити — ми ніколи не виводимо права доступу з боку клієнта з кешованих даних ролі.”

Контекстна кільцева

** контекстна кортеж** — це тимчасовий кортеж, який надається лише на час виконання однієї перевірки, він корисний для оцінки гіпотетичного або обмеженого часом доступу без запису його до сховища.

• “Ми використовували контекстну кортежну функцію для перевірки того, що станеться, якщо цього користувача додадуть до команди « законних », але не надають йому доступу до системи.” *

Список об’ єктів

** ListObjects ** — це виклик API, який повертає всі об’ єкти, з якими користувач має певне відношення — це протилежне до Check, яке використовується для фільтрування перегляду списку за тим, що користувач може бачити.

• “Панель управління викликає ListObjects один раз, щоб отримати всі документи, які може переглядати користувач, замість виконання виклику Check per row.” *

---

Розробка моделей

** Пряме відношення ** — відношення, яке було надано явно певному користувачеві, на відміну від відношення, яке успадковується за допомогою групи або батьківського об’ єкта.

“Ми розробили модель командного власництва як пряме співвідношення, тому відкликання доступу однієї людини не вплине випадково на решту команди.”

** Спадкування зв’ язків (набір користувачів) ** — вираз, який означає, що членство у одному з цих зв’ язків автоматично надає вам право на членство у іншому, наприклад, « будь- який редактор батьківської теки є також редактором цього документа »

• “Спадкування зв’ язків з теки до документа дозволяє нам уникнути написання кортежу для кожного файла, коли хтось приєднується до команди.” *

---

Пояснення OpenFGA команді

Situation	Phrase
Justifying it over hardcoded roles	”Our permission logic outgrew simple role checks — fine-grained, relationship-based authorization scales better once we have per-document sharing.”
Explaining a modeling decision	”We’re using a userset for folder-to-document inheritance so shared-folder access doesn’t require a tuple write per file.”
Describing a performance choice	”We call ListObjects once for the whole list view instead of a Check per row — that’s the pattern OpenFGA recommends for filtered lists.”
Discussing model versioning	”Old tuples still resolve correctly against the new model version, so this migration doesn’t need a backfill.”

Поширені помилки

• Плутанина relation (названий тип з’єднання в моделі) з relation tuple (один конкретний випадок цього з’єднання) — модель визначає, що можливо, а тублиці записують, що фактично надано.
• Виконання виклику Check на елемент у списку замість використання ListObjects — це призведе до викликів авторизації у стилі N+1, які не масштабуються.
• Забувши, що контекстні кортежі є лише під час перевірки — вони не зберігаються, отже, покладатися на них для фактичного контролю доступу — це помилка, а не можливість.

Практичні вправи

1. Поясніть у двох реченнях відмінність між коренем відносин і моделлю авторизації для співробітника команди, який не має досвіду роботи з системами у стилі Zanzibar.
2. Написати короткий опис PR для додавання зв’ язку « рецензент » до типу документа і кільця, необхідні для його надання.
3. Створити чернетку повідомлення, у якому буде пояснено, чому ListObjects є правильним вибором для заповнення списку відфільтрованих документів, замість викликів Check за рядками.

Зв’язані ресурси

• Англійська для кращого розробника Auth
• Англійська для розробників Supabase
• Англійська для розробників TigerBeetle

Наприклад, слово «навигація» означає «навигація за моделями»

OpenFGA є потужним інструментом, але його успіх залежить не тільки від технічних деталей кореляційних кортежів і перевірок, але також від того, як ці концепції поширюються. Для не-англомовних носіїв англійської мови - або, дійсно, * будь-хто *, що прагне до точності в професійному спілкуванні - розуміння тонких відмінностей у фразування може бути вирішальним, щоб уникнути непорозумінь під час перегляду коду, обговорення дизайну і документації. Це не просто про те, щоб знати визначення; це про те, щоб виразити їх впевнено і чітко. Часто, трохи інший вибір слів може кардинально змінити сприйнятий ризик або складність зміни. Наприклад, заява «Ця перевірка примушує обмеження» звучить значно більш упевнено, ніж сказати «Ця перевірка дозволяє обмеження», навіть якщо вони описують той же результат. Аналогічно, описання чогось як «потенційної вразливості» має набагато більшу вагу, ніж просто зауваження, що це «область для поліпшення»

Поширеною пасткою є надмірне використання технічного жаргону без повного розгляду розуміння аудиторії. Уявіть, що ви пишете PR- опис, який описує зміну у моделі авторизації. Замість того, щоб сказати: « Я змінив кортеж user:canRead, щоб відобразити нові правила », розгляньте можливість написання цього рядка так: « Це оновлення роз’ яснює права доступу, надані користувачам під час доступу до ресурсів за допомогою зв’ язку user:canRead, забезпечуючи відповідність оновленим вимогам безпеки ». Останнє слово є більш доступним і містить контекст. Коли рецензент запитує про пояснення складної перевірки, простого «Я реалізував нове обмеження» буде недостатньо. Краще було б сказати: « Ця перевірка забезпечує, що користувач може отримати доступ до даних лише якщо вони мають пряме відношення, визначене в моделі — ключовий принцип наших дозволів у стилі Zanzibar ». Сфокусування на тому, * чому * щось робиться, поряд з тим, * що * робиться, є постійно більш ефективним.

Крім того, звернення уваги на модальні дієслова – should, could, may – є життєво важливим. « Перевірка should prevent…» передбачає сильну рекомендацію або очікування, тоді як « Перевірка might prevent…» говорить про меншу ймовірність успіху. Використання відповідного модального дієслова точно передасть вашу оцінку і керуватиме очікуваннями. Пам’ ятайте, що навіть здавалося б незначні вибір фрази може вплинути на те, як інші інтерпретують ваші наміри. Бути обдуманим щодо вашої мови сприяє ясності і співпраці в команді.

# Check for user:canRead on resource /users/{user_id}
fga check --type "check" \
  --name "User Read Access" \
  --tuple user:canRead \
  --resource /users/{user_id} \
  --check "user.id == {{.User}}"

Цей простий приклад CLI показує типовий сценарій — визначення перевірки доступу для читання даних користувача. Ключовим моментом є те, що опис, незалежно від того, чи це PR або Slack, повинен бути ясним і зрозумілим, підкреслюючи * чому * ця конкретна перевірка існує в рамках більш широкої моделі OpenFGA.