Додатки OAuth і MCP в акаунті

Матеріал з Planfix

Розділ Додатки OAuth та MCP об'єднує налаштування підключення зовнішніх додатків до акаунта Planfix.

Відкрийте Управління акаунтом → API → Додатки OAuth та MCP. Розділ доступний адміністру акаунта та технічному адміністру.

У ньому знаходяться три блоки:

  • MCP — адреса MCP-сервера та коротка інструкція з підключення;
  • Додатки цього акаунта — OAuth-додатки, створені спеціально для поточного акаунта;
  • Сторонні додатки — загальна політика та додатки, явно дозволені в акаунті.

MCP

У цьому блоці показаний єдиний MCP URL продукту: 


https://mcp.planfix.com/uk/mcp


Зазвичай користувачу достатньо додати цей URL в сумісний MCP-клієнт і пройти OAuth-вхід. Назва акаунта вказується не в URL, а обирається на сторінці Planfix. Покрокова інструкція наведена в статті MCP.

Додатки цього акаунта

Створюйте додаток акаунта, якщо інтеграція призначена лише для поточного акаунта і зовнішньому клієнту потрібен заздалегідь відомий client_id.

Додаток акаунта:

  • не може підключатися до інших акаунтів;
  • доступний в акаунті-власнику незалежно від політики сторонніх додатків;
  • використовує глобальні OAuth endpoint;
  • може працювати з REST API або MCP у межах обраних scope.

Створення додатку

  1. Натисніть Створити додаток.
  2. Вкажіть назву та зрозумілий опис призначення.
  3. Оберіть тип OAuth-клієнта.
  4. Додайте Redirect URI клієнта.
  5. Оберіть мінімально необхідні рівні доступу.
  6. Збережіть додаток і скопіюйте видані облікові дані.
Тип клієнта Коли обирати
Публічний Мобільний, десктопний або браузерний додаток, а також локальний MCP-клієнт. Секрет не видається; захист потоку забезпечується PKCE.
Конфіденційний Серверний додаток, здатний надійно зберігати client secret. Секрет не можна поміщати в клієнтський код, мобільний додаток або розповсюджуваний конфігураційний файл.

Client secret показується після створення конфіденційного додатка. Збережіть його в захищеному сховищі.

Redirect URI і права

Для звичайних веб-додатків використовуйте https. Адреси з http допустимі лише для loopback-хостів, наприклад localhost і 127.0.0.1.

Оберіть лише ті scope, які потрібні інтеграції. Scope обмежують доступ додатка, але не розширюють права підключеного користувача.

При зміні Redirect URI або набору scope версія дозволів додатка змінюється, а раніше видані токени перестають відповідати додатку. Користувачам доведеться підключитися заново.

Керування додатком

У картці додатка можна:

  • змінити назву, опис, Redirect URI і scope;
  • відключити і знову увімкнути додаток;
  • замінити client secret у конфіденційному клієнті.

Після заміни старий client secret одразу перестає працювати. Скопіюйте новий секрет і оновіть серверну конфігурацію інтеграції.

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

Сторонні додатки

До сторонніх належать додатки партнерів, опубліковані додатки та MCP-клієнти, зареєстровані через CIMD або DCR.

Політика сторонніх додатків

Політика Результат
Дозволяти опубліковані додатки Опубліковані Planfix додатки доступні без окремого дозволу. Приватні партнерські додатки і автоматично зареєстровані MCP-клієнти вимагають явного дозволу адміністратора.
Тільки дозволені додатки Будь-який сторонній додаток працює тільки після явного дозволу адміністратора.
Заборонити сторонні додатки Сторонні OAuth- і MCP-додатки заблоковані. Додатки, створені самим акаунтом, продовжують працювати.

Для акаунтів з підвищеними вимогами до безпеки рекомендується режим Тільки дозволені додатки.

Дозвіл додатка

Запит може з'явитися двома способами:

  • користувач починає OAuth-підключення і отримує повідомлення про необхідність дозволу;
  • партнер надсилає адміністратору пряме посилання на додаток.

Перед дозволом перевірте:

  • назву, опис і власника додатка;
  • Redirect URI або домен повернення;
  • запитувані scope;
  • необхідність інтеграції для співробітників акаунта.

Дозвіл адміністратора діє для акаунта, але не підключає автоматично всіх користувачів. Кожен співробітник окремо входить в Planfix і підтверджує доступ від свого імені. Якщо підключення виконує адміністратор, кнопка Дозволити і підключити виконує обидві дії.

Якщо розробник змінить Redirect URI або scope стороннього додатка, знадобиться дозволити нову версію.

Відклик дозволу

Щоб заблокувати додаток для акаунта, знайдіть його в списку дозволених і відкличіть доступ. Пов'язані OAuth-токени користувачів цього акаунта будуть відкликані.

При політиці Дозволяти опубліковані додатки відклик явного дозволу не блокує опублікований додаток, тому що він усе ще дозволений загальною політикою. Щоб заборонити його, оберіть Тільки дозволені додатки або Заборонити сторонні додатки.

Особисті підключення користувачів

Дозвіл додатка для акаунта і підключення конкретного користувача — різні рівні контролю.

Співробітник може переглянути і відкликати власні OAuth-підключення:

  1. Відкрийте свою картку користувача.
  2. Перейдіть у розділ Керування сесіями.
  3. Знайдіть додаток; MCP-підключення позначені як MCP.
  4. Видаліть сесію.

Після видалення пов'язані токени перестають працювати. Для відновлення доступу користувач має пройти OAuth-авторизацію заново.

Рекомендації адміністру

  • Використовуйте режим Тільки дозволені додатки, якщо кожну інтеграцію потрібно перевіряти окремо.
  • Перевіряйте власника і Redirect URI, а не тільки назву додатка.
  • Дозволяйте мінімальний набір scope, особливо права зміни та видалення даних.
  • Періодично переглядайте список сторонніх додатків і видаляйте неактивні.
  • Для локальних і десктопних клієнтів використовуйте публічний тип, для серверних — конфіденційний.
  • При підозрі на компрометацію конфіденційного додатка негайно замініть секрет і перепідключіть інтеграцію за потреби.

Перейти