Перейти к содержимому

OAuth-приложения для партнеров

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

Если интеграция предназначена только для одного аккаунта, проще создать приложение, принадлежащее аккаунту.

Создание приложения

  1. Откройте аккаунт партнёра.
  2. Перейдите в раздел OAuth-приложения.
  3. Выберите Создать приложение.
  4. Укажите название и описание, которые будут видны пользователям и администраторам.
  5. Выберите тип OAuth-клиента.
  6. Добавьте URI перенаправления.
  7. Выберите минимально необходимые области доступа REST API.
  8. Сохраните приложение и скопируйте его учётные данные.

Новое приложение является приватным, и для его подключения в каждом аккаунте требуется явное одобрение.

Тип OAuth-клиента

Тип Приложения Учётные данные
Публичный Мобильные, настольные и браузерные приложения, а также локальные MCP-клиенты. Только client_id. Секрет клиента отсутствует; использование PKCE S256 обязательно.
Конфиденциальный Серверные приложения, в которых секрет можно хранить вне устройства пользователя и клиентского кода. client_id и client_secret.

Тип OAuth-клиента не зависит от того, опубликовано приложение или нет. Например, приватное мобильное приложение — это публичный OAuth-клиент без секрета.

URI перенаправления

Укажите все URL, на которые Planfix может перенаправить пользователя после входа.

  • Для веб-сервиса используйте https.
  • http разрешён только для адресов обратной петли, например localhost и 127.0.0.1.
  • Клиент может использовать динамический порт для адреса обратной петли, но схема, хост, путь и строка запроса должны совпадать.
  • Не используйте подстановочные символы, фрагменты URL или URI перенаправления, которые вам не принадлежат.

Области доступа

Области доступа определяют максимальный уровень разрешений приложения. Запрашивайте только необходимые уровни доступа из списка областей доступа REST API.

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

Изменение URI перенаправления или областей доступа создаёт новую версию, требующую одобрения. Ранее подключённые аккаунты должны проверить и одобрить новую версию, а пользователям необходимо подключиться повторно.

Подключение аккаунта клиента

Приватное приложение, принадлежащее партнёру, должно быть явно одобрено администратором в каждом аккаунте.

  1. Откройте приложение в аккаунте партнёра.
  2. В разделе со ссылкой для одобрения укажите название аккаунта клиента.
  3. Скопируйте сгенерированную ссылку и отправьте её администратору этого аккаунта.
  4. Попросите администратора проверить владельца, URI перенаправления и области доступа, а затем одобрить приложение.
  5. После одобрения пользователи аккаунта смогут пройти авторизацию OAuth. Каждый пользователь отдельно даёт согласие от своего имени.

Ссылка открывает раздел Управление аккаунтом → API → OAuth- и MCP-приложения и показывает запрашиваемое приложение.

Администратор, который также подключает приложение, может выбрать Одобрить и подключить.

Приватные и опубликованные приложения

Статус Как приложение допускается в аккаунт
Приватное Всегда требуется явное одобрение администратора каждого аккаунта.
Опубликованное Доступно без отдельного одобрения, если в политике аккаунта выбрано Разрешить опубликованные приложения. Если выбрана политика Только одобренные приложения, одобрение по-прежнему требуется.

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

Адреса подключений

Используйте глобальные конечные точки OAuth:

Назначение Адрес
Авторизация https://auth.planfix.com/oauth/authorize
Токен https://auth.planfix.com/oauth/token
Информация о пользователе https://auth.planfix.com/oauth/userinfo
MCP https://mcp.planfix.com/mcp

Не добавляйте название аккаунта в глобальный URL. Пользователь выбирает аккаунт на странице Planfix. Полное описание протокола, включая resource, PKCE, обновление токенов и отзыв разрешений, приведено в OAuth 2.0 для приложений.

Управление приложением

Партнёр может:

  • изменить название и описание;
  • изменить URI перенаправления и области доступа;
  • отключить и повторно включить приложение;
  • сменить секрет клиента конфиденциального приложения;
  • сгенерировать ссылку для одобрения приложения в конкретном аккаунте.

После смены секрета клиента старый секрет сразу перестаёт работать. Обновите секрет на сервере интеграции и никогда не отправляйте его пользователям.

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

Рекомендации перед запуском

  • Используйте Authorization Code с PKCE S256 и проверяйте state.
  • Запрашивайте только необходимые области доступа.
  • После входа показывайте пользователю выбранный аккаунт.
  • Обрабатывайте смену токенов обновления: после успешного обновления предыдущий токен обновления становится недействительным.
  • Не записывайте в журналы токены, коды авторизации, code_verifier или секреты клиентов.
  • Опишите, как пользователи могут отключить интеграцию и запросить удаление своих данных.
  • Проверьте сценарии отзыва одобрения, отключения приложения и повторного подключения.

Перейти

Источник — https://planfix.com/ru/help/OAuth-приложения_для_партнеров