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

Подключённые приложения и OAuth

API B1 поддерживает OAuth 2.0, поэтому сторонние приложения могут запрашивать у каждого администратора церкви разрешение на доступ к его данным — без того, чтобы церковь передавала пароль или ключ API. Подключённое приложение (Connected App) — это токен OAuth, который одобрил администратор церкви; его отзыв прекращает доступ стороннего приложения одним нажатием. Этот путь используйте для многопользовательских SaaS-коннекторов. Для интеграции с одной церковью предпочтительнее ключи API.

Прежде чем начать

  • OAuth-клиент должен быть зарегистрирован, прежде чем церкви смогут предоставить ему доступ — либо администратором сервера B1, либо самим клиентом через динамическую регистрацию
  • Все конечные точки OAuth находятся в модуле Membership: /membership/oauth/...
  • Токены доступа — это JWT; они несут права пользователя, отфильтрованные по выданным областям

Понятия​

ТерминЗначение
OAuth-клиентСамо стороннее приложение — идентифицируется client_id, защищается client_secret. Регистрируется один раз в B1 и используется всеми церквями, которые его устанавливают.
Подключённое приложениеКонкретная пара (клиент, администратор церкви), где администратор предоставил клиенту доступ. Каждое подключённое приложение опирается на refresh-токен OAuth.
Токен доступаКороткоживущий JWT (≈ 7 дней), который клиент использует для вызовов API. Той же формы, что и пользовательский JWT — Authorization: Bearer <jwt>.
Refresh-токенДолгоживущая непрозрачная строка (≈ 90 дней), которую клиент использует для выпуска новых токенов доступа.
Область (scope)Ограничивает то, что может делать токен доступа, — см. каталог областей.

Потоки авторизации​

B1 поддерживает три потока OAuth, все определены в RFC 6749 и RFC 8628.

Authorization Code (веб-приложения)​

Используйте, когда у вашего приложения есть серверная часть и client_secret можно хранить в тайне.

  1. Авторизация

    POST /membership/oauth/authorize
    Authorization: Bearer <user JWT>
    Content-Type: application/json

    { "client_id": "...", "redirect_uri": "https://app.example.com/cb",
    "response_type": "code", "scope": "people:read groups:read", "state": "xyz" }

    Публичным клиентам (без client_secret) также нужно отправить "code_challenge": "..." и "code_challenge_method": "S256" (PKCE, RFC 7636). Принимается только S256.

    Возвращает { "code": "...", "state": "xyz" }. Конечная точка кода авторизации намеренно является аутентифицированным POST: ваше приложение получает JWT пользователя B1 (обычно через кнопку, размещённую в сеансе пользователя в B1) и передаёт его как часть шага согласия.

  2. Обмен кода на токены

    POST /membership/oauth/token
    Content-Type: application/json

    { "grant_type": "authorization_code", "code": "...",
    "client_id": "...", "client_secret": "...", "redirect_uri": "..." }

    Если на шаге авторизации был отправлен code_challenge, включите соответствующий "code_verifier": "...". Публичный клиент отправляет verifier и опускает client_secret. Конечная точка токенов принимает тела в формате JSON или form-encoded (application/x-www-form-urlencoded).

    Возвращает ответ с токенами:

    {
    "access_token": "eyJ...",
    "token_type": "Bearer",
    "expires_in": 604800,
    "created_at": 1715000000,
    "refresh_token": "abc123…",
    "scope": "people:read groups:read"
    }
  3. Обновление, когда токен доступа вот-вот истечёт:

    POST /membership/oauth/token
    Content-Type: application/json

    { "grant_type": "refresh_token", "refresh_token": "...",
    "client_id": "...", "client_secret": "..." }

    Refresh-токен истекает после 90 дней неиспользования; если он истёк, администратор церкви должен авторизовать приложение заново.

Device Code (ТВ, киоски, CLI)​

Используйте, когда у устройства нет браузера. Определено в RFC 8628.

  1. Запросите код устройства

    POST /membership/oauth/device/authorize
    Content-Type: application/json

    { "client_id": "...", "scope": "content:read" }

    Возвращает код для пользователя и интервал опроса:

    { "device_code": "...", "user_code": "WXYZ-1234",
    "verification_uri": "https://app.b1.church/device",
    "expires_in": 900, "interval": 5 }
  2. Покажите пользователю user_code и verification_uri.

  3. Опрашивайте /membership/oauth/token с grant_type=urn:ietf:params:oauth:grant-type:device_code и device_code. Стандартные ответы:

    ОшибкаЗначение
    authorization_pendingПользователь ещё не одобрил — продолжайте опрос с рекомендованным интервалом
    expired_tokenКод устройства истёк по expires_in — начните заново
    access_deniedПользователь отклонил запрос
    (нет — 200 OK)Одобрено — тело является B1TokenResponse
  4. После одобрения сохраните refresh_token и используйте access_token, пока он не истечёт.

SDK B1 включает B1OAuthClient.awaitDeviceToken(...), который выполняет цикл опроса за вас с корректной по RFC задержкой.

Refresh Token​

Всегда доступен как отдельный запрос, когда у вас есть refresh_token:

POST /membership/oauth/token
{ "grant_type": "refresh_token", "refresh_token": "...", "client_id": "..." }

Возвращаются новые access_token и refresh_token. Публичные клиенты (без client_secret) могут опускать client_secret при обновлении — это удобно для мобильных и настольных OAuth-приложений, которые не могут хранить секрет.

Refresh-токены ротируются, но старый не отбрасывается сразу. Если клиент не получил ответ на обновление (например, ТВ, которое потеряло питание или Wi-Fi во время запроса), он может повторить запрос с предыдущим refresh_token в течение до 7 дней. Повтор успешен, только пока замещающий токен ещё не использован; неиспользованный замещающий токен тогда отбрасывается и выдаётся новая пара. Как только сам замещающий токен был обновлён, старый токен возвращает invalid_grant. Отзыв подключения также отзывает все ротированные токены, которые ещё находятся в этом льготном окне, а в списке подключённых приложений каждое подключение показано один раз.

Форма токена​

Токен доступа — это JWT, выпущенный B1, идентичный тому, который пользователь получает из POST /membership/users/login: та же модульная заявка о правах и то же поведение checkAccess в каждом контроллере. Исключение: массив прав отфильтрован по выданным областям в момент выпуска. Токен доступа с областями не может делать ничего, чего не может сделать ключ API с похожими областями, и нет отдельного «пути OAuth» ни в одном контроллере: actionWrapper не знает, является ли предъявитель человеком, ключом API или клиентом OAuth.

Подключённые приложения (для пользователя)​

С точки зрения администратора церкви «Подключённые приложения» — это список приложений, которым предоставлен доступ к его церкви. Каждая строка — это живая пара (OAuthClient, OAuthToken).

В B1Admin: Settings → Developer → Connected Apps (Настройки → Разработчик → Подключённые приложения) показывает:

  • Название клиента
  • Области, которые одобрил администратор
  • Дату предоставления доступа
  • Кнопку Revoke (Отозвать)
Метод и путьАвторизацияНазначение
GET /membership/oauth/connectionsJWTСписок активных подключений вызывающего (с названием клиента и областями)
DELETE /membership/oauth/connections/:idJWTОтозвать подключение по id OAuth-токена — токен перестаёт работать при следующем запросе

Список автоматически исключает истёкшие токены.

Области и согласие​

Строки областей — тот же каталог, что и у ключей API. Рекомендации для клиентов:

  • Запрашивайте самые узкие области, которые подходят. Церкви замечают, если вы запрашиваете donations:write, когда вам нужно только читать людей.
  • Используйте refresh-токен плюс короткоживущие токены доступа. Долгоживущие токены доступа труднее быстро отозвать.
  • Всегда показывайте предоставленные области пользователю в вашем собственном интерфейсе, чтобы он мог проверить, на что дал согласие.

Управление клиентами OAuth​

Клиенты OAuth (сами сторонние приложения) регистрируются глобально. Конфиденциальный клиент с client_secret выпускается администратором сервера B1: чтобы получить его, свяжитесь с командой ChurchApps для пары client_id / client_secret и зарегистрируйте свои redirect URI. Публичные клиенты, такие как коннекторы MCP, могут регистрировать себя сами (см. ниже).

Зарегистрированные redirect URI должны точно совпадать с redirect_uri в запросе; префиксное или частичное совпадение отклоняется.

Метод и путьПравоОписание
GET /membership/oauth/clientsServer.AdminСписок всех клиентов OAuth
GET /membership/oauth/clients/clientId/:clientId—Получить клиента по его публичному id (секрет скрыт)
POST /membership/oauth/clientsServer.AdminСоздать или обновить клиента
DELETE /membership/oauth/clients/:idServer.AdminУдалить клиента

Динамическая регистрация клиента​

POST /membership/oauth/register (публичная, RFC 7591) позволяет клиенту, например MCP-коннектору claude.ai, зарегистрировать себя. Она объявлена в документе API /.well-known/oauth-authorization-server — см. Сервер MCP → Обнаружение OAuth.

POST /membership/oauth/register
Content-Type: application/json

{ "client_name": "My AI assistant", "redirect_uris": ["https://assistant.example.com/oauth/callback"], "scope": "people:read" }

Возвращает 201 с client_id, client_id_issued_at, client_name, redirect_uris, grant_types (authorization_code, refresh_token), response_types (code) и token_endpoint_auth_method: "none".

  • Секрет никогда не выдаётся, поэтому клиент должен использовать PKCE при каждой авторизации.
  • redirect_uris должны быть 1–10 URL в схеме https или http на localhost, 127.0.0.1 или [::1].
  • client_name обрезается до 45 символов (по умолчанию «AI assistant»).
  • Ограничено 20 регистрациями в час с одного IP.

На странице согласия B1Admin самозарегистрированный клиент получает уведомление о том, что он зарегистрировал себя сам, что он никогда не может сделать больше, чем собственная учётная запись пользователя в B1, и что его можно отключить в Settings → Developer → Connected Apps.

Поддержка SDK​

Пакет @churchapps/integration-sdk оборачивает каждый поток OAuth типизированными помощниками: B1OAuthClient.exchangeCode(), .refresh(), .startDeviceFlow(), .pollDeviceToken(), .awaitDeviceToken(). См. README пакета и Вебхуки для сквозного примера.