Підключені застосунки та OAuth
B1 API підтримує OAuth 2.0, тож сторонній застосунок може запитати в кожного адміністратора церкви дозвіл на доступ до її даних. При цьому церкві не потрібно передавати пароль або ключ API. Connected App — це OAuth-токен, який адміністратор церкви вже схвалив. Відкликання такого токена припиняє доступ сторонього застосунку одним кліком. Цей спосіб підходить для багатоорендних SaaS-коннекторів. Для інтеграції з однією церквою краще використовувати ключі API.
Перш ніж почати
- OAuth-клієнт має бути зареєстрований, перш ніж церкви зможуть надати йому доступ. Це робить адміністратор сервера B1 або сам клієнт через динамічну реєстрацію
- Усі кінцеві точки OAuth розташовані в модулі Membership:
/membership/oauth/... - Токени доступу є JWT. Вони містять дозволи користувача, відфільтровані за наданими областями доступу (scopes)
Основні поняття
| Термін | Значення |
|---|---|
| OAuth-клієнт | Сам сторонній застосунок. Ідентифікується за client_id і захищається client_secret. Реєструється один раз у B1 і використовується всіма церквами, які його встановлюють. |
| Connected App | Конкретна пара (клієнт, адміністратор церкви), для якої адміністратор надав клієнту доступ. Кожен Connected App прив'язаний до OAuth-токена оновлення. |
| Токен доступу | Короткоживучий JWT (≈ 7 днів), який клієнт використовує для викликів API. Має таку саму структуру, як JWT користувача: Authorization: Bearer <jwt>. |
| Токен оновлення | Довгоживучий непрозорий рядок (≈ 90 днів), за допомогою якого клієнт отримує нові токени доступу. |
| Scope | Обмежує те, що може робити токен доступу. Див. каталог 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-запитом з автентифікацією. Ваш застосунок отримує B1 JWT користувача (зазвичай через кнопку в сесії користувача в 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 або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": "..." }Токен оновлення спливає через 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 backoff.
Токен оновлення
Його завжди можна використати як окремий запит, якщо у вас є refresh_token:
POST /membership/oauth/token
{ "grant_type": "refresh_token", "refresh_token": "...", "client_id": "..." }
У відповідь повертаються новий access_token і новий refresh_token. Публічні клієнти (без client_secret) можуть не надсилати client_secret під час оновлення. Це зручно для мобільних і настільних OAuth-застосунків, які не можуть зберігати секрет.
Токени оновлення ротуються, але старий токен не видаляється одразу. Якщо клієнт не отримав відповіді на оновлення (наприклад, телевізор втратив живлення або Wi-Fi під час запиту), він може повторити запит зі збереженим попереднім refresh_token протягом до 7 днів. Повтор вдається, лише доки новий токен ще не використано. Тоді невикористаний новий токен видаляється, і видається нова пара. Якщо новий токен уже сам був оновлений, старий токен повертає invalid_grant. Відкликання з'єднання також відкликає всі ротовані токени, які ще перебувають у цьому вікні сумісності. Список підключених застосунків показує кожне з'єднання один раз.
Структура токена
Токен доступу є JWT, виданим B1. Він має таку саму структуру, як токен, який користувач отримує від POST /membership/users/login: та сама модульна claim із дозволами і та сама поведінка checkAccess у кожному контролері. Винятком є те, що масив дозволів під час видачі фільтрується за наданими scope. Токен доступу з обмеженими scope не може робити нічого такого, чого не може зробити ключ API з подібними scope. Окремого «шляху OAuth» в жодному контролері немає: actionWrapper не визначає, чи є власником токена людина, ключ API чи OAuth-клієнт.
Підключені застосунки (для користувачів)
З точки зору адміністратора церкви «Connected Apps» — це список застосунків, яким надано доступ до його церкви. Кожен рядок є чинною парою (OAuthClient, OAuthToken).
У B1Admin: Settings → Developer → Connected Apps відображає:
- назву клієнта
- scope, які схвалив адміністратор
- дату надання доступу
- кнопку Revoke
| Метод і шлях | Автентифікація | Призначення |
|---|---|---|
GET /membership/oauth/connections | JWT | Список власних активних з'єднань користувача (з назвою клієнта та scope) |
DELETE /membership/oauth/connections/:id | JWT | Відкликання з'єднання за ідентифікатором OAuth-токена. Токен перестає працювати з наступним запитом |
Список автоматично виключає прострочені токени.
Scope і згода
Рядки scope такі самі, як у каталозі ключів API. Найкращі практики для клієнтів:
- Запитуйте найвужчі scope, які підходять. Церкви помічають, якщо ви запитуєте
donations:write, коли вам потрібно лише читати дані про людей. - Використовуйте токен оновлення разом із короткоживучими токенами доступу. Довгоживучі токени доступу важче швидко відкликати.
- Завжди показуйте користувачеві надані scope у власному інтерфейсі, щоб він міг перевірити, на що саме погодився.
Керування OAuth-клієнтами
OAuth-клієнти (самі сторонні застосунки) реєструються глобально. Конфіденційний клієнт із client_secret створює адміністратор сервера B1. Щоб отримати такого клієнта, зверніться до команди ChurchApps за парою client_id / client_secret і зареєструйте свої URI перенаправлення. Публічні клієнти, наприклад MCP-коннектори, можуть реєструватися самостійно (див. нижче).
Зареєстровані URI перенаправлення мають точно збігатися з redirect_uri у запиті. Збіг за префіксом або частковий збіг відхиляється.
| Метод і шлях | Дозвіл | Опис |
|---|---|---|
GET /membership/oauth/clients | Server.Admin | Список усіх OAuth-клієнтів |
GET /membership/oauth/clients/clientId/:clientId | — | Отримати клієнта за публічним ідентифікатором (секрет приховано) |
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 Server → OAuth Discovery.
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 пакета та Webhooks, де наведено наскрізний приклад.