Перейти к основному содержимому

Аутентификация и права доступа

API ChurchApps использует аутентификацию на основе JWT. Пользователи входят в систему и получают токен, который содержит их личность, принадлежность к церкви и права доступа. На этой странице описаны процесс аутентификации, модель прав и поддержка OAuth.

Процесс входа​

Стандартный вход​

POST /membership/users/login

Auth: Public

Принимает один из трёх типов учётных данных:

ПолеОписание
email + passwordСтандартный вход по email и паролю
jwtПовторная аутентификация с существующим JWT
authGuidОдноразовая ссылка для входа (используется в письмах с приветствием и сбросом пароля)

Ответ:

{
"user": {
"id": "abc-123",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@example.com"
},
"churches": [
{
"church": { "id": "church-1", "name": "First Church", "subDomain": "firstchurch" },
"person": { "id": "person-1", "membershipStatus": "Member" },
"groups": [{ "id": "group-1", "name": "Choir", "leader": false }],
"apis": [
{
"keyName": "MembershipApi",
"permissions": [
{ "contentType": "People", "action": "View" },
{ "contentType": "People", "action": "Edit" }
]
}
]
}
],
"token": "<jwt-token>"
}

Поле token — это JWT, который нужно передавать в заголовке Authorization: Bearer <token> в последующих запросах.

Двухфакторный вход​

Пользователи могут включить двухфакторный вход через приложение-аутентификатор (TOTP). Для таких пользователей вход по email + password, authGuid или SSO не возвращает токен. Вместо этого сервер отвечает запросом подтверждения:

{ "mfaRequired": true, "mfaToken": "<challenge-token>" }

Токен подтверждения действителен 5 минут. Отправьте его обратно на тот же эндпоинт вместе с кодом:

{ "mfaToken": "<challenge-token>", "mfaCode": "123456" }

В поле mfaCode можно передать текущий 6-значный код из приложения-аутентификатора или один из десяти одноразовых резервных кодов пользователя. Неверный код возвращает Invalid code, а повторные ошибки ограничиваются по каждой учётной записи. Повторный вход по jwt никогда не требует подтверждения, поэтому существующие сеансы продолжают обновляться. Объект user в ответе на вход содержит поле mfaEnabled.

Эндпоинты самообслуживания (только для вошедшего пользователя, по пути /membership/users/mfa):

ЭндпоинтОписание
GET /status{ enabled, backupCodesLeft }
POST /setupНачинает настройку; возвращает { secret, otpauthUrl } для QR-кода
POST /enableТело { code }; включает вход и возвращает { backupCodes } один раз
POST /disableТело { code } (код из приложения или резервный код); отключает вход
POST /reset/:userIdТолько Server.Admin; отключает вход для другого пользователя

Секреты хранятся в зашифрованном виде, а резервные коды — в виде хешей. Включение, отключение и сброс записываются в журнал аудита.

Содержимое токена​

JWT содержит:

  • id — ID пользователя
  • churchId — текущая выбранная церковь
  • personId — запись человека для выбранной церкви
  • Массивы прав для каждого API

Выбор церкви​

Пользователь может состоять в нескольких церквях. Ответ на вход содержит все церкви с их правами. Чтобы переключиться на другую церковь, клиент формирует новый JWT, привязанный к другой церкви, на основе данных из ответа на вход.

Регистрация пользователей​

Регистрация нового пользователя​

POST /membership/users/register

Auth: Public

{
"email": "jane@example.com",
"firstName": "Jane",
"lastName": "Doe",
"appName": "B1 Admin",
"appUrl": "https://app.b1.church"
}

Создаёт пользователя с временным паролем и отправляет приветственное письмо со ссылкой для входа. Первому пользователю, зарегистрированному на новом экземпляре, автоматически предоставляется доступ администратора сервера.

Принимаются два необязательных поля-ловушки для ботов: website (скрытое поле-приманка, которое реальные пользователи оставляют пустым) и fillMs (сколько миллисекунд форма была открыта). Если заполнено website или fillMs меньше 2000, учётная запись не создаётся, но эндпоинт всё равно возвращает обычный ответ 200, чтобы боты не могли понять, что их отклонили. Клиенты, которые не передают оба поля, регистрируются обычным образом.

Регистрация новой церкви​

POST /membership/churches/add

Auth: JWT

После регистрации пользователя вызовите этот эндпоинт, чтобы создать церковь и связать с ней пользователя.

Управление паролями​

МетодПутьAuthОписание
POST/membership/users/forgotPublicОтправить письмо со сбросом пароля. Тело: { "userEmail": "...", "appName": "...", "appUrl": "..." }
POST/membership/users/setPasswordGuidPublicЗадать новый пароль по auth GUID из письма для сброса. Тело: { "authGuid": "...", "newPassword": "..." }
POST/membership/users/updatePasswordJWTСменить пароль текущего пользователя. Тело: { "newPassword": "..." }

Модель прав доступа​

Права организованы по модулям и назначаются пользователям через роли. У каждого права есть content type (тип содержимого) и action (действие).

Справочник прав​

Раздел в интерфейсеContent TypeActionОписание
AttendanceAttendanceCheckinРегистрация участников на службах
AttendanceEditРедактирование записей посещаемости
ServicesEditУправление службами и временами служений
AttendanceViewПросмотр записей посещаемости
AttendanceView SummaryПросмотр сводок и отчётов по посещаемости
DonationsDonationsEditСоздание и редактирование записей о пожертвованиях
SettingsEditРедактирование настроек пожертвований и платежей
DonationsView SummaryПросмотр сводных отчётов по пожертвованиям
DonationsViewПросмотр отдельных записей о пожертвованиях
People and GroupsFormsAdminПолное администрирование форм
FormsEditРедактирование определений форм
PlansEditРедактирование планов служения
Group MembersEditДобавление и удаление участников групп
GroupsEditСоздание и редактирование групп
HouseholdsEditРедактирование назначений домохозяйств
PeopleEditРедактирование любой записи о человеке
PeopleEdit SelfРедактирование только собственной записи
RolesEditУправление ролями и назначениями пользователей
Group MembersViewПросмотр списков участников групп
PeopleView MembersПросмотр только участников (не гостей)
PeopleViewПросмотр всех людей
RolesViewПросмотр ролей и назначений
SettingsEditРедактирование настроек церкви
ContentContentEditРедактирование страниц, разделов, элементов
SettingsEditРедактирование настроек контента
StreamingServicesEditУправление конфигурацией служб трансляций
ChatHostВедение и модерация чат-сессий
MessagingTextingSendОтправка SMS-сообщений

Как проверяются права​

В контроллерах права проверяются методом au.checkAccess():

// Требуется конкретное право
if (!au.checkAccess(Permissions.people.edit)) return this.json({}, 401);

// Или внутри actionWrapper — CRUD-система проверяет автоматически
crudSettings: {
permissions: {
view: Permissions.people.view,
edit: Permissions.people.edit
}
}

Server Admin​

Право Server.Admin даёт полный доступ ко всем церквям. Оно назначается первому зарегистрированному пользователю и может быть передано другим через роль администратора сервера.

OAuth 2.0​

API поддерживает OAuth 2.0 для сторонних интеграций. Доступны два типа грантов.

Authorization Code Flow​

  1. Авторизация: POST /membership/oauth/authorize (требуется JWT)

    • Тело: { "client_id": "...", "redirect_uri": "...", "response_type": "code", "scope": "...", "state": "...", "code_challenge": "...", "code_challenge_method": "S256" }
    • code_challenge / code_challenge_method (PKCE, только S256) обязательны для публичных клиентов без секрета
    • Возвращает: { "code": "...", "state": "..." }
  2. Обмен кода на токен: POST /membership/oauth/token (Public)

    • Тело: { "grant_type": "authorization_code", "code": "...", "client_id": "...", "client_secret": "...", "redirect_uri": "...", "code_verifier": "..." }
    • Передавайте code_verifier, если на шаге авторизации использовался code_challenge; публичные клиенты не передают client_secret. Принимаются тела в формате JSON или form-encoded
    • Возвращает: { "access_token": "...", "token_type": "Bearer", "expires_in": 43200, "refresh_token": "...", "scope": "..." }
  3. Обновление токена: POST /membership/oauth/token (Public)

    • Тело: { "grant_type": "refresh_token", "refresh_token": "...", "client_id": "...", "client_secret": "..." }

Срок действия access-токенов — 12 часов.

Device Code Flow (RFC 8628)​

Для устройств без браузера (приложения для телевизоров, киоски):

  1. Запрос кода устройства: POST /membership/oauth/device/authorize (Public)

    • Тело: { "client_id": "...", "scope": "..." }
    • Возвращает: { "device_code": "...", "user_code": "ABCD-1234", "verification_uri": "https://app.b1.church/device", "expires_in": 900, "interval": 5 }
  2. Пользователь вводит код на странице verification URI и подтверждает или отклоняет запрос

  3. Опрос для получения токена: POST /membership/oauth/token (Public)

    • Тело: { "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "...", "client_id": "..." }
    • Возвращает authorization_pending, пока запрос не подтверждён, затем возвращает access-токен

Управление OAuth-клиентами​

МетодПутьAuthПраваОписание
GET/membership/oauth/clientsJWTServer.AdminСписок всех OAuth-клиентов
GET/membership/oauth/clients/:idJWTServer.AdminПолучить клиента по ID
GET/membership/oauth/clients/clientId/:clientIdJWT—Получить клиента по client ID (секрет скрыт)
POST/membership/oauth/clientsJWTServer.AdminСоздать или обновить клиента
DELETE/membership/oauth/clients/:idJWTServer.AdminУдалить клиента
POST/membership/oauth/registerPublic—Динамическая регистрация клиента (RFC 7591) для публичных клиентов, например MCP-коннекторов. См. Connected Apps

Эндпоинты подтверждения устройств​

МетодПутьAuthОписание
GET/membership/oauth/device/pending/:userCodeJWTПолучить сведения об ожидающем коде устройства для интерфейса подтверждения
POST/membership/oauth/device/approveJWTПодтвердить авторизацию устройства. Тело: { "user_code": "...", "church_id": "..." }
POST/membership/oauth/device/denyJWTОтклонить авторизацию устройства. Тело: { "user_code": "..." }

Публичные и аутентифицированные эндпоинты​

API использует две обёртки функций, которые определяют требования к аутентификации:

  • actionWrapper — требует действительный JWT. Объект аутентифицированного пользователя (au) доступен с churchId, userId и проверками прав.
  • actionWrapperAnon — аутентификация не требуется. Используется для входа, регистрации, публичных запросов контента и приёмников вебхуков.

В таблицах эндпоинтов этой документации они обозначены в колонке Auth как JWT и Public соответственно.

Связанные страницы​