Пријавите се на главни садржај

Повезане апликације и 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 у тајности.

  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": "...". Јавни клијент шаље верификатор и изоставља 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 док не истекне.

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/connectionsJWTЛиста сопствених активних веза позиваоца (уз назив клијента и опсеге)
DELETE /membership/oauth/connections/:idJWTОпозива везу по ID-у OAuth токена. Токен престаје да ради при следећем захтеву.

Листа аутоматски искључује истекле токене.

Опсези и сагласност​

Ниске опсега су исти каталог као код API кључева. Најбоље праксе за клијенте:

  • Затражите најуже опсеге који функционишу. Цркве примете ако тражите donations:write када вам је потребно само читање података о људима.
  • Користите refresh токен и краткотрајне приступне токене. Дугорочне приступне токене теже је брзо опозвати.
  • Увек приказујте одобрене опсеге назад кориснику у сопственом интерфејсу, како би могао да провери на шта је пристао.

Управљање 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—Преузимање клијента по његовом јавном ID-у (тајна је редигована)
POST /membership/oauth/clientsServer.AdminКреирање или ажурирање клијента
DELETE /membership/oauth/clients/:idServer.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–10 https URL-ова, или 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-ове за пример од почетка до краја.