Подключённые приложения и 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 можно хранить в тайне.
-
Авторизация
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) и передаёт его как часть шага согласия. -
Обмен кода на токены
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"
} -
Обновление, когда токен доступа вот-вот истечёт:
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.
-
Запросите код устройства
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 } -
Покажите пользователю
user_codeиverification_uri. -
Опрашивайте
/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 -
После одобрения сохраните
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/connections | JWT | Список активных подключений вызывающего (с названием клиента и областями) |
DELETE /membership/oauth/connections/:id | JWT | Отозвать подключение по 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/clients | Server.Admin | Список всех клиентов OAuth |
GET /membership/oauth/clients/clientId/:clientId | — | Получить клиента по его публичному id (секрет скрыт) |
POST /membership/oauth/clients | Server.Admin | Создать или обновить клиента |
DELETE /membership/oauth/clients/:id | Server.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 пакета и Вебхуки для сквозного примера.