Appearance
이해하기
MBOX 통합회원의 기능, 도입 절차, 로그인 과정, 제공 정보, 연결과 로그아웃, 보안 및 이용 정책을 설명합니다.
상태 확정 · 최종 확인 2026-09-30
기능 소개
MBOX 통합회원(이하 통합회원)은 머니박스 · 레밋 · 핀모든이 하나의 계정으로 로그인할 수 있도록 제공하는 인증 서비스입니다. OpenID Connect 표준의 Authorization Code 방식을 따르며, PKCE 를 필수로 요구합니다.
연동 서비스에 [MBOX 통합회원으로 로그인] 버튼을 두면, 사용자는 통합회원 화면에서 인증을 마친 뒤 연동 서비스로 돌아갑니다. 연동 서비스는 해당 사용자의 서비스별 회원번호(sub)와 이메일을 전달받습니다.
| 카카오 로그인 | MBOX 통합회원 |
|---|---|
| 카카오계정 | MBOX 통합회원 계정 (이메일 · 비밀번호, 카카오 · Google · Apple) |
| "카카오로 로그인" → 카카오 화면 | "MBOX 통합회원으로 로그인" → 통합회원 화면 |
| 앱별 회원번호 | 서비스별 회원번호(sub) |
| 동의 화면 | 제3자 제공 동의 화면 |
| 서비스 DB 에 카카오 회원번호 저장 | 서비스 DB 에 sub 저장 |
| 자체 로그인과 병행 가능 | 자체 로그인과 병행 가능 |
세 회사는 별도 법인이며 회원 DB 는 통합하지 않습니다. 통합회원은 사용자 인증만 담당하고, 회원 정보 · 본인인증 기록 · 서비스 약관은 각 사가 관리합니다.
| 구분 | 통합회원이 담당 | 연동 서비스가 담당 |
|---|---|---|
| 인증 | 비밀번호 저장 · 검증, 소셜 로그인, 회원가입 · 비밀번호 재설정 화면 | — |
| 세션 | 통합회원 세션(SSO) | 연동 서비스 로그인 상태(세션 · 자체 JWT) |
| 데이터 | 계정(이메일 · 로그인 수단) | 회원 테이블(membership_sub 컬럼 추가), 거래 · 설정 등 |
| 회원가입 | 통합회원 약관 동의 | 이름 · 연락처 · 본인인증 등 서비스에 필요한 정보 수집 |
도입 안내
| 단계 | 내용 | 문서 |
|---|---|---|
| 1. 클라이언트 신청 | 클라이언트를 발급받고 redirect_uri 를 등록합니다 | 설정하기 |
| 2. 연동 개발 | 로그인을 구현하고, sub 로 회원을 조회 · 등록 · 연결합니다 | 활용하기 · REST API |
| 3. 점검 | stage 점검 목록을 확인하고 prod 클라이언트를 발급받습니다 | 문제 해결 |
| 구분 | stage | prod |
|---|---|---|
| 호스트 | https://stage-membership.m-box.com (개방) | https://membership.m-box.com (개방 예정) |
| 디스커버리 | {호스트}/.well-known/openid-configuration | 동일 |
| 사용자 계정 | stage 로그인 화면에서 직접 가입 | 실사용자 |
redirect_uri | http://localhost 허용 | https 만 허용 |
| 데이터 | 초기화될 수 있음 | 보존 |
두 환경은 같은 코드로 동작하며 데이터만 분리되어 있습니다.
로그인
서비스 로그인 과정
MBOX 통합회원 로그인은 인가 코드 받기, 토큰 받기, 회원 확인 및 로그인의 세 단계로 진행됩니다.
| 번호 | 설명 | 참고 |
|---|---|---|
| 1 | 사용자가 연동 서비스의 로그인 버튼을 선택합니다 | 활용하기 › 로그인 버튼 |
| 2 | 연동 서비스가 code_verifier · state · nonce 를 생성하여 세션에 저장하고, 통합회원 인가 주소로 302 리다이렉트합니다 | REST API › 인가 코드 요청 |
| 3 | 브라우저가 통합회원 인가 주소로 이동합니다. 통합회원은 client_id 와 redirect_uri 를 검사하며, 등록되지 않은 값이면 통합회원 오류 화면을 표시합니다 | 문제 해결 › 오류 코드 |
| 4 ~ 5 | 통합회원 세션이 없으면 로그인 화면을 표시합니다. 세션이 있으면 생략합니다(SSO) | — |
| 6 ~ 7 | 이 서비스에 처음 연결하는 사용자에게만 제3자 제공 동의 화면을 표시합니다. 거부하면 error=access_denied 로 리다이렉트됩니다 | 동의 화면 |
| 8 ~ 9 | 통합회원이 redirect_uri?code=…&state=…&iss=… 로 303 리다이렉트합니다. 연동 서비스는 state 를 세션 값과 비교합니다 | — |
| 10 ~ 11 | 연동 서비스 서버가 인가 코드, code_verifier, client_secret 으로 토큰을 요청합니다. 인가 코드는 60초 안에 한 번 사용할 수 있습니다 | REST API › 토큰 요청 |
| 12 | ID 토큰의 서명 · iss · aud · exp · nonce 를 검증한 뒤, sub 로 회원을 조회합니다. 회원이 없으면 가입 또는 기존 회원 연결을 진행합니다 | 활용하기 › 회원 조회와 등록 |
| 13 | 연동 서비스의 로그인 상태(세션 또는 자체 JWT)를 발급합니다. 통합회원 토큰은 브라우저에 전달하지 않습니다 | 활용하기 › 연동 서비스 세션 |
통합회원 세션이 유효하면 로그인 화면 없이 인가 코드가 발급됩니다(SSO).
동의 화면
사용자가 서비스에 처음 로그인하면 제3자 제공 동의를 거쳐 연결이 생성되고, 해당 서비스의 sub 가 발급됩니다.
| 상황 | 표시 화면 |
|---|---|
| 통합회원 세션 없음 | 로그인 화면 |
| 서비스 최초 연결 | 동의 화면 — 제공받는 자(연동 서비스), 제공 항목(이메일, 회원번호), 목적, 보유 기간 |
| 이미 연결된 서비스 | 화면 없이 인가 코드 발급 |
연동 서비스는 통합회원과 다른 법인이므로 동의 화면이 표시되며, 사용자는 동의를 거부할 수 있습니다. 통합회원 운영 법인의 서비스에는 제3자 제공에 해당하지 않으므로 거부 버튼이 없는 안내 화면이 표시됩니다. 두 화면의 항목과 형식은 같으며, 연동 코드에는 차이가 없습니다.
연결과 동의는 클라이언트가 아닌 서비스 단위로 관리됩니다. 같은 서비스에 새 클라이언트(앱 등)를 등록해도 이미 연결된 사용자에게는 동의 화면이 다시 표시되지 않습니다. 사용자가 통합회원 계정 관리에서 연결을 해제하면 다음 로그인 시 다시 표시됩니다.
토큰
| 토큰 | 용도 | 만료 |
|---|---|---|
| ID 토큰 | 사용자 식별. sub · email 클레임을 담은 JWT(RS256) | 10분 |
| 액세스 토큰 | 사용자 정보 조회(/oauth/userinfo) | 10분 |
| 리프레시 토큰 | 액세스 토큰 · ID 토큰 재발급. offline_access 를 prompt=consent 와 함께 요청한 경우에만 발급 | 30일, 사용할 때마다 교체 |
ID 토큰에 필요한 정보가 모두 포함되어 있으므로, 로그인에는 액세스 토큰과 리프레시 토큰이 필요하지 않습니다.
제공 정보
| 클레임 | 설명 | 예시 | 항상 제공 |
|---|---|---|---|
sub | 서비스별 회원번호. 접두어와 32자 16진수, 총 35자. 변경되지 않습니다 | rm_0ec504cc3974f5edd3e1830d8a67941c | 예 |
email | 이메일(소문자) | hong@example.com | 예(email scope 요청 시) |
email_verified | 이메일 소유 확인 여부 | true | 예(email scope 요청 시) |
sub 는 서비스마다 다르게 발급됩니다(pairwise). 같은 사용자라도 레밋과 핀모든이 받는 값은 다르며, 두 서비스의 값을 비교해도 같은 사용자인지 알 수 없습니다. 접두어는 머니박스 mb_, 레밋 rm_, 핀모든 fm_ 입니다. 회원번호는 클라이언트가 아닌 서비스 단위로 발급되므로, 같은 서비스의 웹과 앱에는 같은 값이 발급됩니다.
WARNING
email 은 확인되지 않은 주소일 수 있습니다
통합회원은 이메일 가입 시 인증 코드로, 소셜 가입 시 제공자의 인증 정보나 인증 코드로 주소를 확인한 뒤 계정을 생성합니다. 다만 머니박스에서 전환한 계정은 사용자가 확인 메일의 링크를 선택하기 전까지 email_verified 가 false 입니다.
이메일로 기존 회원을 조회하는 경우 email_verified 가 true 인지 반드시 확인해야 합니다. 확인되지 않은 주소로 조회하면 다른 사용자의 계정에 연결될 수 있습니다. 연락용으로 저장하는 것은 문제없습니다.
이름, 휴대폰 번호, 생년월일, 본인인증 정보는 제공하지 않습니다. 통합회원은 가입 시 이 정보와 본인인증을 수집하지 않으므로, 필요한 경우 연동 서비스의 회원가입 절차에서 직접 수집해야 합니다.
연결
회원가입의 구분
| 구분 | 내용 | 위치 |
|---|---|---|
| 통합회원 가입 | 로그인 수단 생성, 통합회원 약관 동의. 세 서비스 공통, 1회 | 통합회원 화면 |
| 서비스 가입 | 연동 서비스 이용에 필요한 정보(이름 · 연락처 · 본인인증 등) 수집 | 연동 서비스 화면, 토큰 발급 후 |
처음 방문한 사용자는 통합회원에서 계정을 생성한 뒤 연동 서비스로 돌아오며, 이때 연동 서비스 DB 에 없는 sub 가 전달됩니다. 연동 서비스는 회원을 생성하고 서비스 가입 절차를 진행합니다.
기존 회원 여부 확인
연동 서비스에 이미 가입한 회원은 사용자 본인이 한 번 연결해야 합니다. 통합회원은 연동 서비스의 회원 DB 를 알지 못하며, 법인 간 개인정보 제공 제한으로 회원 명단을 전달받을 수 없습니다. 연결 방법은 활용하기 › 기존 회원 연결을 참고하시기 바랍니다.
통합회원은 계정을 사후에 병합하지 않습니다. 가입 시 이메일을 기준으로 하나의 계정으로 관리하므로, 탈퇴 후 재가입한 경우를 제외하면 한 사용자에게 sub 가 둘 이상 발급되지 않습니다.
계정 상태 변경
| 사용자 계정 변경 | sub | 연동 서비스에서 확인되는 결과 | 처리 |
|---|---|---|---|
| 이메일 변경 | 유지 | 다음 로그인 시 email 변경 | 로그인 시 email 갱신 |
| 비밀번호 변경, 로그인 수단 추가 · 해제 | 유지 | 변화 없음 | 없음 |
| 다른 서비스 연결 · 해제 | 유지 | 변화 없음 | 없음 |
| 이 서비스 연결 해제(동의 철회) | 유지 | 토큰 갱신 시 invalid_grant. 재로그인 시 동의 화면 후 같은 sub | 재로그인 안내 |
| 비밀번호 재설정 | 유지 | 통합회원 세션과 리프레시 토큰 폐기. 토큰 갱신 시 invalid_grant | 재로그인 안내 |
| 계정 정지 | 유지 | 로그인 시 access_denied, 토큰 갱신 시 invalid_grant | 재로그인 안내 |
| 탈퇴 | 소멸 | 토큰 갱신 시 invalid_grant. 재가입 시 새 sub(새 회원으로 인식) | 연결 해제 처리. 회원 정보는 연동 서비스 정책에 따름 |
사용자는 통합회원 계정 관리 화면(/account)에서 비밀번호 변경 · 재설정, 서비스 연결 해제, 탈퇴를 직접 수행합니다. 간편 로그인(카카오 · Google · Apple)으로만 가입한 사용자도 같은 간편 로그인으로 계정 관리 화면에 로그인할 수 있습니다. 통합회원은 이를 연동 서비스에 별도로 통지하지 않으며(웹훅 미제공), 연동 서비스는 위 표의 응답으로 확인합니다.
로그아웃
| 방식 | 동작 |
|---|---|
| 연동 서비스 로그아웃 | 연동 서비스 세션만 삭제합니다. 통합회원 세션은 유지되어 다른 서비스의 SSO 에 영향이 없습니다 |
| 통합회원 로그아웃 | 브라우저를 /oauth/logout 으로 이동시킵니다. 사용자가 확인 화면에서 로그아웃을 선택하면 통합회원 세션이 종료되어 모든 서비스에서 다시 로그인해야 합니다. 요청한 서비스의 액세스 · 리프레시 토큰은 폐기됩니다 |
다른 서비스로 로그아웃을 전파하지 않습니다(백채널 로그아웃 미제공). 각 서비스의 세션은 각 서비스가 종료합니다. 구현 방법은 활용하기 › 로그아웃을 참고하시기 바랍니다.
보안
| 항목 | 내용 |
|---|---|
| PKCE | 필수(S256). 인가 코드가 유출되어도 code_verifier 없이는 토큰을 발급받을 수 없습니다 |
state | 필수. 콜백에서 요청 시 값과 비교하여 CSRF 를 방지합니다. 서버가 누락을 검사하지 않으므로 연동 서비스에서 검증해야 합니다 |
nonce | 필수. ID 토큰의 nonce 와 비교하여 재사용을 방지합니다. 서버가 누락을 검사하지 않으므로 연동 서비스에서 검증해야 합니다 |
iss (콜백) | 콜백에 발급자가 함께 전달됩니다(RFC 9207). 디스커버리의 issuer 와 비교합니다 |
| 클라이언트 시크릿 | 서버에만 보관합니다. 앱 · 브라우저 코드에 포함하지 않습니다 |
| 토큰 저장 | 통합회원 토큰은 프런트엔드에 저장하지 않습니다. 로그인 상태는 연동 서비스 세션으로 관리합니다 |
redirect_uri | 등록된 값과 정확히 일치해야 합니다 |
| 브라우저 직접 호출 | 토큰 · 사용자 정보 엔드포인트는 서버 간 호출 전용이며 CORS 를 허용하지 않습니다 |
이용 정책
- 통합회원이 제공한
sub와 이메일은 회원 식별과 연락 목적으로만 사용해야 합니다. 다른 회사와 대조하거나 제3자에게 제공할 수 없습니다. - 연동 서비스의 개인정보 처리방침에 주식회사 머니박스로부터의 제공 사실을 반영해야 합니다. — 설정하기 › 개인정보 처리방침
- 회원 명단을 통합회원에 전달하여 계정을 미리 생성할 수 없습니다. 사용자 본인이 가입하고 동의해야 합니다.
- 회원 식별에는
sub만 사용해야 합니다. 이메일은 변경되거나 확인되지 않은 값일 수 있습니다. - 사용자가 연결을 해제하거나 탈퇴한 경우, 해당 회원의 처리는 연동 서비스 정책에 따릅니다.
- 자체 로그인 유지 여부는 연동 서비스가 결정합니다.
제공 API
| 기능 | 메서드 | URL |
|---|---|---|
| 디스커버리 | GET | /.well-known/openid-configuration |
| JWKS | GET | /oauth/jwks |
| 인가 코드 요청 | GET | /oauth/authorize |
| 토큰 요청 | POST | /oauth/token |
| 토큰 갱신 | POST | /oauth/token |
| 사용자 정보 조회 | GET | /oauth/userinfo |
| 토큰 폐기 | POST | /oauth/revoke |
| 로그아웃 | GET | /oauth/logout |
문의: 머니박스 개발실 유원영 · yoo.wonyoung@m-box.com