본문으로 건너뛰기

Auth Operation 도메인 요구사항

범위: 인증(Authentication) / 토큰(Token) / 세션(Session)
비범위(별도 도메인): 운영자/서비스 계정 생성·승인·상태 전이(Operation User), Role 프로비저닝(IAM)

1. 기능 요구사항​

1.1 사용자 인증 (로그인)​

  • AUT-OPS-FR-BE-011: 시스템은 이메일과 비밀번호로 로그인할 수 있어야 한다. (Operation User)
  • AUT-OPS-FR-BE-012: 시스템은 인증 성공 시 액세스 토큰과 리프레시 토큰을 발급해야 한다.
    • Operation User: 이메일+비밀번호 인증 성공
    • Service Account: API Key 인증 성공
  • AUT-OPS-FR-BE-013: 시스템은 로그인 실패 시도를 기록하고 관리해야 한다.
  • AUT-OPS-FR-BE-014: 시스템은 5회 연속 로그인 실패 시 계정을 1분간 잠가야 한다.
  • AUT-OPS-FR-BE-015: 시스템은 계정이 잠긴 상태에서 로그인 시도 시 특정 에러를 반환해야 한다.
  • AUT-OPS-FR-BE-016: 시스템은 비밀번호 검증 시 클라이언트에서 받은 해싱된 비밀번호에 SERVER_PEPPER를 결합하고 bcrypt로 검증해야 한다.
  • AUT-OPS-FR-BE-017: 시스템은 로그인 성공 시 로그인 시도 횟수를 0으로 초기화해야 한다.
  • AUT-OPS-FR-BE-018: 시스템은 리프레시 토큰을 데이터베이스에 저장해야 한다.

1.2 토큰 관리​

  • AUT-OPS-FR-BE-019: 시스템은 JWT 토큰 기반 인증을 구현해야 한다.
  • AUT-OPS-FR-BE-020: 시스템은 토큰 페이로드에 토큰 타입(type), 사용자 ID(sub), 만료/발급 시간(exp/iat), 토큰 ID(jti)를 포함해야 하며, 사용자 타입(userType)을 포함하여 OPERATION_USER와 SERVICE_ACCOUNT를 구분할 수 있어야 한다.
  • AUT-OPS-FR-BE-021: 시스템은 토큰 검증 시 iss, aud, sub, type, exp, iat의 유효성을 검증해야 한다. uci(사용자 사이클 ID) 및 deviceId는 값이 있는 경우에만 토큰 페이로드에 포함해야 하며, 누락되었다는 이유만으로 토큰을 무효화해서는 안 된다.
  • AUT-OPS-FR-BE-022: 시스템은 인증 성공 시 발급하는 액세스 토큰에 Role 기반 권한 부여 결과(roles, permissions) 및 동의 항목(agreements)을 포함할 수 있어야 한다.
    • agreements는 Principal 유형/정책에 따라 포함되지 않을 수 있다.
  • AUT-OPS-FR-BE-023: 시스템은 Service Account 인증 수단으로 API Key(sklive 또는 sktest 접두사)를 지원해야 하며, SHA-256 해시로 저장된 키를 조회하여 활성/만료 상태를 확인할 수 있어야 한다.
  • AUT-OPS-FR-BE-024: 시스템은 토큰 검증 시 토큰이 Service Account 토큰임을 userType으로 확인해야 한다.
    • (revocation 정책을 운영하는 경우) 토큰 원문을 SHA-256 해싱한 값 또는 jti 기반으로 revoke 여부를 확인하여 revoke된 토큰을 거부해야 한다.

1.3 세션 관리​

  • AUT-OPS-FR-BE-033: 시스템은 세션 타임아웃을 30분으로 설정해야 한다.
  • AUT-OPS-FR-BE-034: 시스템은 만료된 세션을 자동으로 정리해야 한다.
  • AUT-OPS-FR-BE-035: 시스템은 동일 사용자의 단일 접속만 허용한다.
    • 단일 접속의 기준(예: 동일 사용자에 대해 유효한 리프레시 토큰 1개만 허용)은 구현 정책으로 명시해야 한다.

1.4 자격 증명 관리 (비밀번호 변경/초기화/재설정)​

1.4.1 비밀번호 변경 (사용자 본인)​

  • AUT-OPS-FR-BE-025: 시스템은 사용자가 본인의 이메일, 현재 비밀번호, 새 비밀번호를 입력하여 비밀번호를 변경할 수 있어야 한다.
  • AUT-OPS-FR-BE-026: 시스템은 비밀번호 변경 시 현재 비밀번호를 검증하여 본인 확인을 수행해야 한다. (계정 식별은 이메일 기준)

1.4.2 관리자에 의한 강제 비밀번호 초기화​

  • AUT-OPS-FR-BE-027: 시스템은 관리자가 계정 ID 또는 이메일로 사용자의 비밀번호를 강제 초기화할 수 있어야 한다.
  • AUT-OPS-FR-BE-028: 시스템은 강제 비밀번호 초기화 시 무작위로 생성된 안전한 비밀번호를 자동으로 생성해야 한다.
  • AUT-OPS-FR-BE-029: 시스템은 비밀번호 업데이트와 이메일 전송을 단일 트랜잭션으로 처리해야 한다. 이메일 전송 실패 시 비밀번호 변경도 롤백되어야 한다.
  • AUT-OPS-FR-BE-030: 시스템은 강제 초기화된 비밀번호를 사용자의 이메일로 전송해야 한다.

1.4.3 보안 코드를 통한 비밀번호 재설정​

  • AUT-OPS-FR-BE-031: 시스템은 사용자가 이메일을 입력하여 비밀번호 재설정 보안 코드를 요청할 수 있어야 한다.
  • AUT-OPS-FR-BE-032: 시스템은 6자리 숫자로 구성된 무작위 보안 코드를 생성해야 한다.
  • AUT-OPS-FR-BE-036: 시스템은 생성된 보안 코드가 중복되지 않도록 검증해야 한다. 중복 시 재생성해야 한다.
  • AUT-OPS-FR-BE-037: 시스템은 보안 코드를 캐시(Redis 등)에 임시 저장하고 만료 시간을 설정해야 한다.
  • AUT-OPS-FR-BE-038: 시스템은 생성된 보안 코드를 사용자의 이메일로 전송해야 한다.
  • AUT-OPS-FR-BE-039: 시스템은 사용자가 이메일과 보안 코드를 입력하여 검증을 요청할 수 있어야 한다.
  • AUT-OPS-FR-BE-040: 시스템은 보안 코드가 유효하고 입력된 이메일과 일치하는지 검증해야 한다.
  • AUT-OPS-FR-BE-041: 시스템은 검증 성공 시 30분 유효기간의 임시 JWT 액세스 토큰을 발급해야 한다.
  • AUT-OPS-FR-BE-042: 시스템은 토큰에 계정 ID와 토큰 타입(access)을 포함해야 한다.
  • AUT-OPS-FR-BE-043: 시스템은 발급받은 임시 토큰과 새 비밀번호로 비밀번호를 재설정할 수 있어야 한다.
  • AUT-OPS-FR-BE-044: 시스템은 임시 토큰의 유효성을 검증하고 만료 여부를 확인해야 한다.
  • AUT-OPS-FR-BE-045: 시스템은 새 비밀번호가 기존 비밀번호와 동일한지 검증해야 한다. 동일한 경우 재설정을 거부해야 한다.

2. 비기능 요구사항​

2.1 보안​

  • AUT-OPS-NFR-001: 시스템은 토큰 검증 실패 시 UNAUTHORIZED 에러를 반환해야 한다.
  • AUT-OPS-NFR-002: 시스템은 모든 요청에 대해 토큰 디코딩 및 검증 인터셉터를 적용해야 한다.
  • AUT-OPS-NFR-003: 시스템은 비밀번호 비교 시 타이밍 공격을 방지하기 위해 constant-time 비교를 수행해야 한다.

변경 이력​

버전날짜작성자변경 내용
0.58.02025-12-16mook@weltcorp.com문서 최초 작성
0.62.02025-12-29jeff@weltcorp.comAuth 범위(인증/토큰/세션)로 재정렬, 계정/프로비저닝 요구사항은 Operation User/IAM으로 분리