본문으로 건너뛰기

인증 및 권한

ChurchApps API는 JWT 기반 인증을 사용합니다. 사용자는 로그인하여 자신의 신원, 교회 소속, 권한을 담은 토큰을 받습니다. 이 페이지에서는 인증 흐름, 권한 모델, OAuth 지원을 다룹니다.

로그인 흐름​

일반 로그인​

POST /membership/users/login

인증: 공개

다음 세 가지 자격 증명 유형 중 하나를 받습니다.

필드설명
email + password일반 이메일/비밀번호 로그인
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>으로 보내야 합니다.

2단계 로그인​

사용자는 인증 앱(TOTP) 기반 2단계 로그인을 켤 수 있습니다. 이런 사용자의 경우 email + password, authGuid, 또는 SSO 로그인은 토큰을 반환하지 않습니다. 대신 다음과 같은 질문(challenge)으로 응답합니다.

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

질문 토큰은 5분 동안 유효합니다. 같은 엔드포인트에 코드와 함께 이 토큰을 다시 보내세요.

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

mfaCode에는 현재의 6자리 인증 코드 또는 사용자가 가진 10개의 일회용 백업 코드 중 하나를 쓸 수 있습니다. 잘못된 코드는 Invalid code를 반환하며, 반복된 실패는 계정별로 요청 빈도가 제한됩니다. jwt 재로그인은 질문을 받지 않으므로, 기존 세션은 계속 갱신됩니다. 로그인 응답의 user 객체에는 mfaEnabled가 포함됩니다.

셀프 서비스 엔드포인트(로그인한 사용자만, /membership/users/mfa 아래):

엔드포인트설명
GET /status{ enabled, backupCodesLeft }
POST /setup설정을 시작하며, QR 코드용 { secret, otpauthUrl }을 반환
POST /enable본문 { code }. 켜고 { backupCodes }를 한 번만 반환
POST /disable본문 { code }(인증 코드 또는 백업 코드). 끔
POST /reset/:userIdServer.Admin 전용. 다른 사용자의 설정을 끔

비밀 값은 암호화되어 저장되며, 백업 코드는 해시로 저장됩니다. 켜기, 끄기, 초기화는 모두 감사 로그에 기록됩니다.

토큰 내용​

JWT에는 다음 정보가 담깁니다.

  • id — 사용자 ID
  • churchId — 현재 선택된 교회
  • personId — 선택된 교회에서의 교인 기록
  • API별 권한 배열

교회 선택​

사용자는 여러 교회에 속할 수 있습니다. 로그인 응답에는 각 교회와 권한이 모두 포함됩니다. 교회를 바꾸려면 클라이언트가 로그인 응답 데이터에서 다른 교회 범위의 새 JWT를 만듭니다.

사용자 등록​

새 사용자 등록​

POST /membership/users/register

인증: 공개

{
"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

인증: JWT

사용자를 등록한 뒤 이 엔드포인트를 호출하면 교회를 만들고 사용자를 그 교회와 연결합니다.

비밀번호 관리​

메서드경로인증설명
POST/membership/users/forgot공개비밀번호 재설정 이메일 발송. 본문: { "userEmail": "...", "appName": "...", "appUrl": "..." }
POST/membership/users/setPasswordGuid공개재설정 이메일의 인증 GUID로 새 비밀번호 설정. 본문: { "authGuid": "...", "newPassword": "..." }
POST/membership/users/updatePasswordJWT현재 사용자의 비밀번호 변경. 본문: { "newPassword": "..." }

권한 모델​

권한은 모듈별로 구성되며 역할을 통해 사용자에게 할당됩니다. 각 권한에는 콘텐츠 유형과 동작이 있습니다.

권한 참조​

표시 섹션콘텐츠 유형동작설명
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문자 메시지 보내기

권한 확인 방법​

컨트롤러에서는 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 권한은 모든 교회에 대한 전체 접근 권한을 부여합니다. 이 권한은 처음 등록된 사용자에게 할당되며, 서버 관리자 역할을 통해 다른 사용자에게도 부여할 수 있습니다.

OAuth 2.0​

API는 제3자 연동을 위해 OAuth 2.0을 지원합니다. 두 가지 승인 유형을 사용할 수 있습니다.

인가 코드 흐름​

  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 (공개)

    • 본문: { "grant_type": "authorization_code", "code": "...", "client_id": "...", "client_secret": "...", "redirect_uri": "...", "code_verifier": "..." }
    • 인가 단계에서 code_challenge를 사용했다면 code_verifier를 보내세요. 공개 클라이언트는 client_secret을 생략합니다. JSON 또는 폼 인코딩 본문을 모두 받습니다.
    • 반환: { "access_token": "...", "token_type": "Bearer", "expires_in": 43200, "refresh_token": "...", "scope": "..." }
  3. 토큰 갱신: POST /membership/oauth/token (공개)

    • 본문: { "grant_type": "refresh_token", "refresh_token": "...", "client_id": "...", "client_secret": "..." }

액세스 토큰은 12시간 후에 만료됩니다.

기기 코드 흐름 (RFC 8628)​

브라우저가 없는 기기(TV 앱, 키오스크)용입니다.

  1. 기기 코드 요청: POST /membership/oauth/device/authorize (공개)

    • 본문: { "client_id": "...", "scope": "..." }
    • 반환: { "device_code": "...", "user_code": "ABCD-1234", "verification_uri": "https://app.b1.church/device", "expires_in": 900, "interval": 5 }
  2. 사용자가 확인 주소에서 코드를 입력하고 승인하거나 거부합니다.

  3. 토큰 폴링: POST /membership/oauth/token (공개)

    • 본문: { "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "...", "client_id": "..." }
    • 승인되기 전까지 authorization_pending을 반환하고, 승인되면 액세스 토큰을 반환합니다.

OAuth 클라이언트 관리​

메서드경로인증권한설명
GET/membership/oauth/clientsJWTServer.Admin모든 OAuth 클라이언트 목록
GET/membership/oauth/clients/:idJWTServer.AdminID로 클라이언트 가져오기
GET/membership/oauth/clients/clientId/:clientIdJWT—클라이언트 ID로 클라이언트 가져오기(비밀 값은 가려짐)
POST/membership/oauth/clientsJWTServer.Admin클라이언트 생성 또는 업데이트
DELETE/membership/oauth/clients/:idJWTServer.Admin클라이언트 삭제
POST/membership/oauth/register공개—MCP 커넥터 같은 공개 클라이언트를 위한 동적 클라이언트 등록(RFC 7591). 연결된 앱 참고

기기 승인 엔드포인트​

메서드경로인증설명
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 — 인증이 필요 없습니다. 로그인, 등록, 공개 콘텐츠 조회, 웹훅 수신에 사용합니다.

이 문서 전체의 엔드포인트 표에서는 인증 열에 각각 JWT와 공개로 표시합니다.

관련 문서​

  • 모듈 구조 — 컨트롤러, 리포지토리, 모델의 구성 방식
  • 로컬 설정 — 개발을 위해 로컬에서 API 실행하기