Перейти до основного вмісту

Підключені застосунки та 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 у таємниці.

  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-запитом з автентифікацією. Ваш застосунок отримує B1 JWT користувача (зазвичай через кнопку в сесії користувача в 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 або 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": "..." }

    Токен оновлення спливає через 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 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/connectionsJWTСписок власних активних з'єднань користувача (з назвою клієнта та scope)
DELETE /membership/oauth/connections/:idJWTВідкликання з'єднання за ідентифікатором 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/clientsServer.AdminСписок усіх OAuth-клієнтів
GET /membership/oauth/clients/clientId/:clientId—Отримати клієнта за публічним ідентифікатором (секрет приховано)
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 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, де наведено наскрізний приклад.