Function Definition

기능 매트릭스·오류 코드·기본 정책

액터 (actor) 는 4종이다: End User (최종 사용자), RP Backend (연동 서버, Java client library 사용), Browser SDK (JS SDK), SnowPass Admin (운영 관리자).

Feature Matrix (기능 매트릭스)

User Lifecycle (사용자 수명주기)

ID	기능	액터	Endpoint	설명
U-01	사용자 등록/보장	RP Backend	`POST /v1/users`	external user id (= RP 가 생성한 System User ID, UUID) 기준 idempotent upsert. `loginId`(사용자 ID, max 16)·`email` 부가 속성 포함
U-02	MFA 상태 조회	RP Backend	`GET /v1/users/{id}`	hasPasskey / hasTotp / 잠금 상태 / 남은 recovery code 수
U-03	사용자 삭제	RP Backend	`DELETE /v1/users/{id}`	credential 연쇄 삭제 (회원 탈퇴 연동)

PassKey (WebAuthn)

ID	기능	액터	Endpoint	설명
P-01	등록 토큰 발급	RP Backend	`POST /v1/register/token` (factor=PASSKEY)	300초 1회용 `sprt_*`
P-02	등록 options	Browser SDK	`POST /p1/passkey/register/options`	challenge + excludeCredentials 포함 creation options
P-03	등록 검증·저장	Browser SDK	`POST /p1/passkey/register/verify`	attestation 검증, credential 저장, result token 반환
P-04	인증 토큰 발급	RP Backend	`POST /v1/auth/token` (factor=PASSKEY)	미등록 시 `FACTOR_NOT_ENROLLED` 404
P-05	인증 options	Browser SDK	`POST /p1/passkey/auth/options`	allowCredentials 포함 request options
P-06	인증 검증	Browser SDK	`POST /p1/passkey/auth/verify`	assertion 검증, signature counter·last_used 갱신
P-07	다중 기기 등록	End User	P-01~03 반복	기기별 passkey. excludeCredentials 로 중복 방지
P-08	AAGUID 매핑	Server 내부	—	passkey provider 이름 표시 (1Password, Google Password Manager 등)

TOTP

ID	기능	액터	Endpoint	설명
T-01	등록 토큰 발급	RP Backend	`POST /v1/register/token` (factor=TOTP)
T-02	등록 정보 조회	Browser SDK	`POST /p1/totp/register/options`	secret(Base32) + `otpauth://` URI + QR PNG base64. secret 은 확정 전 ceremony payload 에만 암호화 보관
T-03	등록 확인	Browser SDK	`POST /p1/totp/register/verify`	코드 확인 성공 시 credential 영속화 + recovery code 10개 원자적 발급
T-04	인증	Browser SDK	`POST /p1/totp/auth/verify`	±1 step 창, timestep replay 차단 (`CODE_REPLAYED`), 5회 실패 lockout

Recovery & Helpdesk (복구·헬프데스크)

ID	기능	액터	Endpoint	설명
R-01	recovery code 재발급	RP Backend	`POST /v1/users/{id}/recovery-codes`	미사용분 폐기 후 10개 신규. 평문은 응답 1회만
R-02	recovery code 인증	RP Backend	`POST /v1/recovery/verify`	1회용, factor=RECOVERY result token
R-03	bypass code 발급	RP Backend / Admin	`POST /v1/users/{id}/bypass-code`, admin API	TTL 기본 15분, 1회용 (헬프데스크 시나리오)
R-04	bypass code 인증	RP Backend	`POST /v1/bypass/verify`	factor=BYPASS
R-05	MFA 초기화	RP Backend / Admin	`POST /v1/users/{id}/mfa/reset`, admin API	전체 credential·recovery 폐기 + 잠금 해제 → 재등록 유도

Credential Management (credential 관리)

ID	기능	액터	Endpoint	설명
C-01	목록 조회	RP Backend	`GET /v1/users/{id}/credentials`	nickname·provider·등록/최근 사용 시각·backup 상태
C-02	별칭 변경	RP Backend	`PATCH /v1/users/{id}/credentials/{cid}`	사용자 self-service 용
C-03	passkey 삭제	RP Backend	`DELETE /v1/users/{id}/credentials/{cid}`	last-credential guard: 마지막 credential 이면 409 `LAST_CREDENTIAL` (`?force=true` 로 우회)
C-04	TOTP 해지	RP Backend	`DELETE /v1/users/{id}/totp`	동일 guard

Verification (검증)

ID	기능	액터	Endpoint	설명
V-01	result token 검증	RP Backend	`POST /v1/auth/verify`	서명·만료·aud(테넌트)·jti 1회용 검증
V-02	JWKS 공개	누구나	`GET /.well-known/jwks.json`	오프라인 JWT 검증용 공개키

Admin Console (관리 콘솔)

ID	기능	Endpoint	설명
A-01	관리자 로그인	`POST /admin/api/login`	세션 쿠키. 초기 계정 부팅 시 생성
A-02	대시보드	`GET /admin/api/stats/dashboard`	테넌트/사용자/credential 수, 24h 성공·실패, 최근 이벤트
A-03	테넌트 등록	`POST /admin/api/tenants`	api secret 은 응답에서 1회만 노출
A-04	테넌트 수정	`PATCH /admin/api/tenants/{id}`	origins/rpId 변경 시 RelyingParty 캐시 무효화
A-05	secret rotate	`POST /admin/api/tenants/{id}/rotate-secret`	기존 secret 즉시 무효화
A-06	사용자 검색/상세	`GET .../users`, `GET /admin/api/users/{id}`	credential·잠금·recovery 현황
A-07	credential 폐기	`DELETE /admin/api/users/{id}/credentials/{cid}`, `.../totp`	분실·도난 대응
A-08	MFA 초기화 / 잠금 해제 / bypass 발급	`POST .../mfa-reset`, `.../unlock`, `.../bypass-code`	헬프데스크 작업
A-09	감사 로그 조회	`GET /admin/api/audit`	테넌트/사용자/이벤트/기간 필터 + 페이징

Error Codes (오류 코드)

응답 형식: {"error": {"code": "...", "message": "..."}}

코드	HTTP	의미
INVALID_API_KEY / INVALID_API_SECRET	401	API 자격 증명 오류
TOKEN_INVALID / TOKEN_EXPIRED / TOKEN_CONSUMED	400	ceremony/result token 오류 (없음·타입 불일치 / 만료 / 재사용)
USER_NOT_FOUND / FACTOR_NOT_ENROLLED	404	사용자 없음 / 해당 factor 미등록
USER_LOCKED	429	lockout 상태 (locked_until 포함)
CODE_INVALID / CODE_REPLAYED	400	코드 불일치 / TOTP 재사용 차단
CREDENTIAL_NOT_FOUND	404	credential 없음
LAST_CREDENTIAL	409	마지막 credential 삭제 시도
CEREMONY_FAILED	400	WebAuthn 검증 실패 (서명·origin·rpId 등)
ORIGIN_NOT_ALLOWED	403	테넌트 allowed_origins 밖의 Origin
ADMIN_UNAUTHORIZED	401	관리자 세션 없음

Policy Defaults (기본 정책)

정책	기본값	설정 키
등록 ceremony TTL	300초	`snowpass.register-ceremony-ttl-seconds`
인증 ceremony TTL	180초	`snowpass.auth-ceremony-ttl-seconds`
result token TTL	120초	`snowpass.result-token-ttl-seconds`
lockout 임계/기간	5회 / 5분	`snowpass.lockout.*`
TOTP 파라미터	SHA-1 / 6자리 / 30초 / ±1 step	고정 (Authenticator 앱 호환성)
recovery code	10개, 10자 (혼동 문자 제외 알파벳)	고정
userVerification	preferred	PasskeyService (테넌트별 정책화는 로드맵)

Out of Scope (v1 제외, 로드맵)

Conditional UI (자동완성 passkey), WebAuthn Signal API
attestation 정책 엔진 / FIDO MDS 연동 (기기 통제 요구 시)
위험 신호 기반 recovery 게이트, webhook 이벤트 스트림
관리자 RBAC 세분화 (현재 단일 ADMIN role)
RSA Authentication Manager 연동 (RADIUS/REST)

Architecture

SnowPass 컴포넌트 구조·멀티테넌트·토큰 모델·보안 통제

Service Scenarios

상태 다이어그램으로 정의한 주요 수명주기와 시나리오 워크스루

On this page

Feature Matrix (기능 매트릭스)User Lifecycle (사용자 수명주기)PassKey (WebAuthn)TOTP Recovery & Helpdesk (복구·헬프데스크)Credential Management (credential 관리)Verification (검증)Admin Console (관리 콘솔)Error Codes (오류 코드)Policy Defaults (기본 정책)Out of Scope (v1 제외, 로드맵)