forked from baron/baron-sso
65 lines
3.4 KiB
Markdown
65 lines
3.4 KiB
Markdown
# Shadow Account Policy (Identity Sovereignty)
|
|
|
|
## 1. 개요 (Overview)
|
|
Baron SSO는 외부 IDP(Descope 등)에 의존하지 않고, **식별자 주권(Identity Sovereignty)**을 갖기 위해 **Shadow Account (그림자 계정)** 모델을 채택합니다.
|
|
외부 IDP는 단지 "인증 수단"일 뿐이며, 서비스 내부의 모든 비즈니스 로직, 로그, RP 연동은 Baron SSO가 발급한 고유 식별자(`Baron ID`)를 기준으로 수행됩니다.
|
|
|
|
## 2. 식별자 정책 (Identifier Policy)
|
|
|
|
### 2.1. Baron ID (Internal User ID)
|
|
- **Format**: **UUID v7** (Time-ordered 128-bit)
|
|
- **특징**: 생성 시간 순 정렬 가능, DB 인덱싱 효율 최적화, 외부 시스템 충돌 없음.
|
|
- **용도**: `users` 테이블 PK, `audit_logs`의 Actor ID, RP에 전달되는 `sub` 값.
|
|
- **원칙**: **불변(Immutable)**. 사용자가 이메일이나 연동 IDP를 변경해도 Baron ID는 변하지 않아야 합니다.
|
|
|
|
### 2.2. Audit Log ID
|
|
- **Format**: **Snowflake** (64-bit Integer)
|
|
- **용도**: 감사 로그의 Primary Key.
|
|
- **이유**: 초당 대량으로 발생하는 로그 데이터의 적재 성능과 ClickHouse 압축 효율을 위해 정수형 ID 사용.
|
|
|
|
## 3. 데이터 모델 (Shadow Schema)
|
|
|
|
### 3.1. Users Table (Core)
|
|
서비스가 바라보는 사용자의 실체입니다.
|
|
```sql
|
|
CREATE TABLE users (
|
|
id UUID PRIMARY KEY, -- Baron ID (UUID v7)
|
|
email VARCHAR(255), -- 검색 및 알림용 (Unique X, 여러 계정 가능성)
|
|
name VARCHAR(100),
|
|
status VARCHAR(20), -- 'active', 'blocked'
|
|
created_at TIMESTAMPTZ,
|
|
last_login_at TIMESTAMPTZ
|
|
);
|
|
```
|
|
|
|
### 3.2. Federated Identities Table (Mapping)
|
|
외부 IDP 계정과 Baron 계정을 연결하는 매핑 테이블입니다. N:1 매핑이 가능합니다.
|
|
```sql
|
|
CREATE TABLE federated_identities (
|
|
provider VARCHAR(50), -- 'descope', 'google', 'legacy_db'
|
|
provider_sub VARCHAR(255), -- IDP의 원천 User ID
|
|
user_id UUID REFERENCES users(id),
|
|
created_at TIMESTAMPTZ,
|
|
PRIMARY KEY (provider, provider_sub)
|
|
);
|
|
```
|
|
|
|
## 4. 동기화 및 로그인 흐름 (Sync Flow)
|
|
|
|
1. **인증 성공**: 백엔드가 IDP(Descope) 토큰을 검증하고 `Provider Sub`(예: `U12345`)를 획득.
|
|
2. **조회 (Lookup)**: `federated_identities` 테이블에서 `(provider='descope', provider_sub='U12345')` 조회.
|
|
3. **분기 처리**:
|
|
- **Case A (기존 회원)**: 매핑된 `user_id` 획득. `users` 테이블의 정보(이메일, 이름)를 IDP 토큰 정보로 **업데이트(Sync)**.
|
|
- **Case B (신규 회원)**: 새로운 `UUID v7` 생성 -> `users` Insert -> `federated_identities` Insert.
|
|
4. **세션 발급**: Baron ID(`user_id`)를 Payload로 담은 Baron 자체 세션/토큰을 발급하여 클라이언트에 전달.
|
|
|
|
## 5. IDP 마이그레이션 전략 (Migration Strategy)
|
|
|
|
### 5.1. 식별자 유지
|
|
IDP가 `Descope`에서 `Keycloak`으로 바뀌더라도, 백엔드는 새로운 IDP의 `sub`를 기존 사용자의 `Baron ID`와 매핑(`federated_identities` 추가)하기만 하면 됩니다. RP와 클라이언트는 아무런 변화를 감지하지 못합니다.
|
|
|
|
### 5.2. 비밀번호 처리 (Password Handling)
|
|
- 해시된 비밀번호는 이관하지 않습니다 (불가능/비효율).
|
|
- **Magic Link / Passwordless 우선**: 사용자는 비밀번호 입력 없이 계속 이용 가능.
|
|
- **재설정 유도**: 비밀번호 사용 필수 시, "보안 정책 변경" 안내와 함께 리셋 링크 발송.
|