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)

서비스가 바라보는 사용자의 실체입니다.

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 매핑이 가능합니다.

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)

인증 성공: 백엔드가 IDP(Descope) 토큰을 검증하고 Provider Sub(예: U12345)를 획득.
조회 (Lookup): federated_identities 테이블에서 (provider='descope', provider_sub='U12345') 조회.
분기 처리:
- Case A (기존 회원): 매핑된 user_id 획득. users 테이블의 정보(이메일, 이름)를 IDP 토큰 정보로 업데이트(Sync).
- Case B (신규 회원): 새로운 UUID v7 생성 -> users Insert -> federated_identities Insert.
세션 발급: 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 우선: 사용자는 비밀번호 입력 없이 계속 이용 가능.
재설정 유도: 비밀번호 사용 필수 시, "보안 정책 변경" 안내와 함께 리셋 링크 발송.

3.4 KiB Raw Blame History