Повезане апликације и OAuth
B1 API подржава OAuth 2.0 да би апликација треће стране могла да затражи од сваког администратора цркве дозволу за приступ њиховим подацима, без да црква икада дели лозинку или API кључ. Повезана апликација је OAuth токен који је администратор цркве одобрио; опозивање га одмах прекида приступ апликације треће стране, једним кликом. Користите овај пут за мултитенант SaaS конекторе. За интеграцију за једну цркву препоручујемо API кључеве.
Пре почетка
- OAuth клијент мора бити регистрован пре него што цркве могу да му дају приступ, и то или од стране администратора B1 сервера, или од самог клијента путем динамичке регистрације
- Све OAuth крајње тачке налазе се у модулу Membership:
/membership/oauth/... - Приступни токени су JWT-ови; они садрже дозволе корисника филтриране према одобреним опсezима
Концепти
| Термин | Значење |
|---|---|
| OAuth клијент | Сама апликација треће стране, идентификована помоћу client_id и заштићена помоћу client_secret. Региструје се једном код B1 и дели се са свим црквама које га инсталирају. |
| Повезана апликација | Специфичан пар (клијент, администратор цркве) у којем је администратор дао приступ клијенту. Свака повезана апликација подржана је OAuth refresh токеном. |
| Приступни токен | Краткотрајан JWT (≈ 7 дана) који клијент користи за API позиве. Исти облик као кориснички JWT: Authorization: Bearer <jwt>. |
| Refresh токен | Дугорочан непрозиран низ (≈ 90 дана) који клијент користи за издавање нових приступних токена. |
| Опсег | Сужава оно што приступни токен може да уради. Погледајте каталог опсега. |
Токови одобравања
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": "...". Јавни клијент шаље верификатор и изоставља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док не истекне.
B1 SDK укључује B1OAuthClient.awaitDeviceToken(...), који за вас покреће петљу провере са исправним backoff-ом у складу са RFC-ом.
Refresh токен
Доступно је и као самостални захтев када имате 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 и региструјте своје URI-је за преусмеравање. Јавни клијенти, као што су MCP конектори, могу сами да се региструју (доле).
Регистровани 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, да се сам региструје. Оглашава се у документу /.well-known/oauth-authorization-server API-ја. Погледајте 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–10httpsURL-ова, или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 пакета и Webhook-ове за пример од почетка до краја.