Загальна інформація

Функціонал взаємодії акредитованих Майданчиків із ЦБД

1. Отримання токена доступу
   Після проходження акредитації, Брокеру надається унікальний Авторизаційний ключ (Authorization token). Цей токен виступає інструментом ідентифікації Брокера та розширює його можливості взаємодії з ЦБД. Передбачена можливість взаємодіяти тільки з обʼєктами, на які надані права.

2. Розширені можливості API для акредитованих брокерів
   Використовуючи отриманий токен, брокери можуть:

   • Публікувати об'єкти: надсилати запит для створення нових об'єктів у ЦБД, таких як procedure, asset та інші
   • Модифікувати існуючі об'єкти: змінювати раніше опубліковані об'єкти, якщо вони ще не набули термінального статусу відповідно до правил ЦБД і існуючих endPoints.

3. Безпека та авторизація
   Токен є обов’язковою складовою кожного запиту до API, який стосується створення чи зміни об'єктів. Це забезпечує:

   • Унікальність доступу до даних конкретного брокера.
   • Обмеження доступу до функціоналу відповідно до рівня акредитації (прав доступу до обʼєктів).
   • Логування усіх дій у ЦБД для аудиту та прозорості.

4. Додаткові обмеження

   • Брокери можуть працювати лише з тими об'єктами, які були створені з використанням їх токена, або якщо вони отримали owner token до раніше створеного обʼєкта + їх Авторизаційний ключ дозволяє виконувати дії над обʼєктам вказаного типу.
   • Токен може бути деактивований або вимагати регулярного оновлення для посилення безпеки доступу.

Мета функціоналу:
Цей механізм забезпечує контрольований, прозорий та безпечний доступ до ресурсів ЦБД, дозволяючи розширювати свій функціонал для Брокера, але залишаючи управління основними правилами та процесами на боці ЦБД.

CDB objects

Терміни

Авторизаційний ключ - унікальний токен, який видається Брокеру після проходження акредитації та укладання договорів. Це ключ доступу для здійнення маніпуляцій над обʼєктами визначених сервісів ЦБД. Ключ дає можливість публікувати обʼєкти та змінювати існуючі обʼєкти їх власнику, якщо це передбачено сервісом.

На читання Обʼєкти мають бути доступні без використання авторизаційного ключа (якщо зворотнє не передбачено вимогами до конкретного типу обʼєктів. Наприклад, процедури [GFW] Факторинг - не публічні на читання за певних умов)

• Валідність - характеризує технічну придатність ключа для використання в системі. Ключ відповідає всім технічним вимогам системи: має правильний формат, не прострочений і не скомпрометований.
• Активність - визначає адміністративний статус ключа в системі

Авторизаційний ключ може перебувати в одному з наступних станів:

Адміністратор може деактивувати ключ без втрати його валідності, якщо необхідно тимчасово обмежити дії брокера.

Owner token - унікальний токен, який отримує Брокер одразу після публікації обʼєкта, або після зміни owner-а для обʼєкта. Це ключ доступу до обʼєкта.

JWT token - унікальний токен, який отримує Брокер одразу після заватаження документа в Document Service

Брокер - майданчик, який взаємодіє з ЦБД

Дозволи (Permissions) - це набір правил або прав, які визначають, які дії може виконувати Брокер на ЦБД. Вони забезпечують контроль доступу до обʼєктів або операцій, забезпечуючи захист і дотримання політик безпеки.

Дозволи для Брокера є можливість налаштувати:

1. По сервісу, до якого надається доступ (procedure, jobber, registry etc)
2. По типу Обʼєкта в межах одного сервісу (asset, lease_request etc)
   1. Для сервісу Procedure обʼєктом вважається Напрям + тип. Наприклад, basicSell-english, smallPrivatization-dutch, commercialLease-priorityEnglish etc
      1. Має бути можливість додати permission для basicSell-english, але не надати для basicSell-dutch
3. По типу дії над обʼєктом. Наприклад, для сервісу procedure для обʼєкта basicSell-english можливість публікувати обʼєкт procedure та обʼєкт bids
   1. procedure - можливість публікувати обʼєкти procedure та вносити зміни в існуючі обʼєкти, де Брокер є власником
   2. bids - можливість публікувати обʼєкти procedure.bids та вносити зміни в існуючі обʼєкти, де Брокер є власником
   3. read_procedure - можливість читати приватні обʼєкти (для Факторингу)
   4. read_protected_data - можливість читати анонімізовані поля (для Факторингу)

User stories

Use cases

Use Case 1: Налаштування permissions для Брокера по його Авторизаційному ключу та видача ключа Брокеру

Передумова: Брокер пройшов акредитацію, створена внутрішня заявка на видачу ключів для Брокера

Основний сценарій:

1. Адміністратор ЦБД отримавши запит, створює для зазначеного в заявці Брокера Авторизаційний ключ
2. Вказує зазначені з заявці permissions для Брокера по його Автризаційному ключу
3. Система надає брокеру можливість публікувати та змінювати об’єкти в межах дозволених сервісів.
4. Авторизаційний ключ передається брокеру через захищений канал

Результат: Брокер отримав можливість публікувати і змінювати свої обʼєкти використовуючи отриманий Авторизаційний токен

Use Case 2: Внесення змін в permissions для Брокера, який вже має Авторизаційний ключ

Передумова: Отримано заявку на зміну доступів Брокера

Сценарій 1:

1. Отримано запит "Майданчик акредитовано для роботи з новим напрямком"
2. Адміністратор ЦБД надає Брокеру нові permissions
   1. 
3. Відповідальний зі сторони Prozorro.Sale інформує Брокера про дату початку дії нового permission

Результат: Брокер отримав можливість публікувати і змінювати обʼєкти, до яких були надані права. Читати публічні обʼєкти має бути можливість і без permission

Сценарій 2:

1. Отримано запит "Забрати у Майданчика права працювати з напрямком ХХ"
2. Адміністратор ЦБД забирає у вказаного Брокера permissions, які дозволяють публікувати\змінювати обʼєкти вказаного напрямку
3. Відповідальний зі сторони Prozorro.Sale інформує Брокера про зміну прав

Результат: Брокер втратив можливість публікувати і змінювати обʼєкти, від яких були забрані права. Читати публічні обʼєкти має бути можливість і без permission. В такому випадку, існуючі обʼєкти цього Брокера вже не доступні йому для подальших змін. Бізнесово передбачена можливість перенести обʼєкт до іншого Власника, який має права на цей вид обʼєкту.

Use Case 3: Деактивація Авторизаційного ключа

Передумова: Авторизаційний ключ створено та використовується брокером

Основний сценарій:

1. Адміністратор знаходить ключ належний Брокеру.
2. Деактивує ключ.
3. Система зупиняє доступ до функцій публікації та редагування.
4. Ключ залишається доступним для читання через mirror.

Use Case 4: Повторна активація Авторизаційного ключа для Брокера якому раніше ключ деактивували

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

Основний сценарій:

1. Адміністратор ідентифікує потрібний Авторизаційний ключ, що належить конкретному Брокеру, в системі.
2. Адміністратор обирає опцію повторної активації ключа.
3. Система підтверджує, що ключ в деактивованому статусі.
4. Система активує ключ та надає доступ Брокеру до функцій публікації та редагування.
5. Система відображає повідомлення про успішну активацію ключа.

Бізнесово: Якщо цей Брокер зберіг owner токени до "старих" обʼєктів, то з новим авторизаційним ключем він може продовжити взаємодіяти зі "старими" обʼєктами, за умови, що в них залишились валідні owner токени і їх не передавали іншому Майданчику.

Альтернативний сценарій:

2a. Ключ уже активний:
2a.1. Система інформує адміністратора, що ключ уже активний, і дії не потрібні.

Use Case 5: Публікація об'єктів брокером

Передумови:

1. Брокер має валідний та активний ключ.

Основний сценарій:

1. Брокер надсилає запит на API для публікації об’єкта.
2. Система перевіряє валідність і активність ключа.
3. Якщо ключ дійсний, об’єкт публікується в системі.

Use Case 6: Перевипуск Авторизаційного ключа

Передумова:
Брокер вже має (або мав) Авторизаційний ключ, але його втрачено чи став недоступним через певні обставини.

Основний сценарій:

1. Адміністратор ідентифікує Брокера, який потребує перевипуску Авторизаційного ключа.
2. Адміністратор обирає функцію перевипуску Авторизаційного ключа в системі.
3. Система перевіряє, чи існує попередній ключ для цього Брокера.
4. Система анулює існуючий ключ та генерує новий Авторизаційний ключ.
5. Система надає новий ключ Адміністратору для передачі Брокеру.
6. Система логує дію перевипуску для забезпечення аудиту.

Бізнесово: У Брокера має залишитись можливість працювати з обʼєктами, які були йому доступні з попереднім Авторизаційним ключем. Тобто, з точки зору роботи з обʼєктами - перевипуск ключа не має впливати на процес. По старому ключу - доступ має бути заблоковано. Після перевипуску, якщо Брокер робить запит із старим ключем, то він має отримувати помилку аналогічну, коли ключ не валідний.

Альтернативний сценарій:

3a. У Брокера немає попереднього ключа:
3a.1. Система інформує адміністратора, що перевипуск неможливий, оскільки попередній ключ не знайдено.
3a.2. Адміністратор може створити новий ключ для Брокера через окрему функцію.

4a. Попередній ключ активно використовується:
4a.1. Система інформує адміністратора, що перевипуск замінить діючий ключ.
4a.2. Адміністратор підтверджує дію.
4a.3. Система анулює попередній ключ і генерує новий.

Use Case 7: Зміна існуючих об'єктів

Передумови:

1. Брокер є власником об’єкта (ключ збігається з owner-key).
2. Ключ валідний і активний.

Основний сценарій:

1. Брокер надсилає запит на редагування об’єкта.
2. Система перевіряє валідність ключа та токена.
3. Об’єкт оновлюється, якщо всі умови виконані.

Use Case 8: Читання об’єктів через API

Актори:

• Брокер

Передумови:

1. Ключ може бути активним чи деактивованим.

Основний сценарій:

1. Брокер запитує об’єкт через API:
   • з токеном об’єкта отримує повну відповідь;
   • без токена отримує спрощену відповідь.

Use Case 9: Читання об'єктів при деактивованому ключі

Передумови:

1. Ключ деактивовано, але валідний.

Основний сценарій:

1. Брокер підключається до mirror або API.
2. Система дозволяє доступ до даних лише для читання.

Use Case 10: Завантаження документів у Document Service

Передумови:

1. Ключ валідний і активний.

Основний сценарій:

1. Брокер надсилає запит на завантаження документа.
2. Система перевіряє валідність ключа та дозволяє завантаження.

Use Case 11: Перегляд public і private документів

10.1 Public документи

1. Брокер (або будь-який користувач) відкриває публічне посилання.
2. Система надає доступ до документа без ключа чи токена.

10.2 Private документи

1. Брокер надсилає запит із JWT токеном документа.
2. Система перевіряє токен та надає доступ до документа.

Use Case 12: Заборона видалення об’єктів

Основний сценарій:

1. Видалення об’єктів в системі заборонено.
2. Запити на видалення обʼєктів не розроблені

Use Case 13: Перегляд анонімізованих полів об’єкта за токеном

Передумови:

1. Об’єкт містить анонімізовані поля
2. Брокер має дійсний токен об'єкта.

Основний сценарій:

1. Брокер надсилає запит на перегляд об’єкта через API, надаючи токен об’єкта.
2. Система перевіряє валідність токена об’єкта.
   • Якщо токен валідний, система переходить до кроку 3.
   • Якщо токен невалідний, система повертає помилку доступу.
3. Система повертає відповідь із доступними анонімізованими полями об'єкта в деанонімізованому стані.

Результат: Брокер отримує доступ до анонімізованих полів об’єкта, незалежно від статусу свого Авторизаційного ключа.

Ситуації:
1.

• Майданчик_1 публікує Біда з приватними документами
• По запиту, змінюємо Власника для цього Біда з Майданчик_1 на Майданчик_2
• Майданчик_2 тепер має ключ до Біда і може виконувати дії від імені власника Біда.
• Приватні документи і токен доступу до них НЕ змінюється. Новий власник Біда не може отримати доступ до приватних документів.

Можливе рішення: При зміні власника обʼєкта, за наявності приватних документів у обʼєкті, новому власнику потрібно надавати не тільки новий токен доступу до обʼєкта, а також токени до приватних документів. На моменті генерації нового токена, має відбуватись валідація на наявність приватних документів і за їх наявності, витягувати, і 1) перегенерувати ключ 2) залишити поточний і надіслати новому вдаснику, але тоді і "старий" власник буде мати доступ

2.

• Майданчик_1 публікує процедуру
• По запиту процедуру анонімізували
• По запиту змінюємо Власника для цієї процедури з Майданчик_1 на Майданчик_2
• Деанонімізовані поля може бачити тільки новий власник обʼєкта, бо вони доступні тільки за наявності owner token і не залежить від Authorization token

Результат: Майданчик_1 не бачить анонімізовані поля, Майданчик_2 бачить анонімізовані поля як деанонімізовані

Auth Token for Procedure

Дозволи (permissions), які можна надавати до Автризаційного ключа для сервісу Procedure:

• Класифікація по Напряму роботи + типу аукціона. Наприклад, basicSell-english, smallPrivatization-dutch, commercialLease-priorityEnglish

Auth Token for Jobber

Дозволи (permissions), які можна надавати до Автризаційного ключа для сервісу Jobber:

• announcement - можливість виконувати дії над обʼєктом типу announcement
• large_announcement - можливість виконувати дії над обʼєктом типу large_announcement
• legacy_announcement - можливість виконувати дії над обʼєктом типу legacy_announcement
• redemption - можливість виконувати дії над обʼєктом типу redemption
• large_redemption - можливість виконувати дії над обʼєктом типу large_redemption
• legacy_redemption - можливість виконувати дії над обʼєктом типу legacy_redemption

Auth Token for Registry

Дозволи (permissions), які можна надавати до Автризаційного ключа для сервісу Registry:

• object - можливість виконувати дії над обʼєктом типу object
• action - можливість виконувати дії над обʼєктом типу action
• lease_request - можливість виконувати дії над обʼєктом типу lease_request
• asset - можливість виконувати дії над обʼєктом типу asset
• large_asset - можливість виконувати дії над обʼєктом типу large_asset
• legacy_asset - можливість виконувати дії над обʼєктом типу legacy_asset
• execution - можливість виконувати дії над обʼєктом типу execution
• large_execution - можливість виконувати дії над обʼєктом типу large_execution
• legacy_execution - можливість виконувати дії над обʼєктом типу legacy_execution

Relocation

Майданчику видається унікальний Авторизаційний токен, який дає можливість публікувати обʼєкти Relocation в ЦБД

Сервіс Relocation працює з об'єктами через API і надає декілька способів доступу:

1. Публікація об'єктів через API

• Для публікації об'єктів видається Auth Token.
• Цей токен є обов'язковим для автентифікації при роботі з endpoint, який дозволяє створювати об'єкти.

2. Читання об'єктів

• Існує спеціальний endpoint для читання, який не потребує авторизації. Це означає, що доступ до об'єктів на цьому endpoint відкритий для всіх користувачів.

3. Робота через WebSocket

• WebSocket дозволяє отримувати об'єкти в реальному часі (mirror-потік).
• Для підключення до WebSocket потрібен валідний авторизаційний ключ, але він може бути неактивним (наприклад, перестали співпрацювати з Майданчиком А, але можна неативний, валідний ключ використовувати для підключення до потоку).

Ця архітектура дозволяє гнучко працювати з об'єктами:

• Публікація захищена токеном для забезпечення безпеки.
• Читання — відкритий доступ для швидкого отримання даних.
• WebSocket забезпечує підписку на зміни з мінімальними вимогами до автентифікації.

Relocation User Stories

Survey

Для читання даних сервісу survey необхідно використовувати Авторизаційний ключ з правами на вказаний сервіс.

У клієнта (наприклад, BI) має бути валідний ТА активний авторизаційний ключ, для того, щоб була можливість по API за допомогою GET запиту отримати обʼєкти.

Mirror-потік для сервісу Survey відсутній

Survey User Stories