본문으로 건너뛰기

Auth 도메인 비즈니스 규칙

1. 인증 규칙​

1.1 로그인 규칙​

  • 사용자는 이메일과 비밀번호로 로그인
  • OAuth 제공자를 통한 소셜 로그인 지원 (GesundheitsID)
  • 2단계 인증(2FA) 지원
    • PIN code
    • 생체인증 (FaceID, TouchID)

1.2 PIN code 규칙​

  • PIN code는 6자리 숫자로 구성
  • 연속된 숫자 3개 이상 사용 불가 (예: 123, 789)
  • 동일한 숫자 3개 이상 연속 사용 불가 (예: 111, 999)
  • 5회 연속 오입력 시 2FA 재설정 필요
  • 180일 주기로 변경 권장
  • PIN code는 서버로 전송되지 않으며, 모바일 기기 내부에서만 처리됨
  • PIN code는 모바일 기기에 저장된 암호화된 사용자 인증 정보(ID/PW)를 복호화하는 키로 사용됨
  • 모바일 기기에서는 PIN code를 직접 저장하지 않고, PIN code로부터 생성된 암호화 키만 안전하게 저장함
  • ISO27001, GDPR, DiGA 규제 준수를 위해 PIN code 관련 정보는 서버에 저장하지 않음
  • 앱 재설치 시 PIN code와 암호화된 인증 정보가 사라지므로 이메일/비밀번호를 통한 재로그인 및 PIN code 재설정이 필요함

1.3 비밀번호 규칙​

  • 최소 8자, 최대 16자
  • 영문자(대문자, 소문자), 숫자, 특수문자 3가지 모두 포함
  • 연속된 문자 3개 이상 사용 불가
  • 이전에 사용한 비밀번호 5개는 재사용 불가
  • 다음 문자는 비밀번호에 사용 불가:
    • 공백 문자(스페이스)
    • HTML 또는 SQL 인젝션 관련 문자: <, >, ", ', \

1.4 계정 잠금 규칙​

  • 5회 연속 로그인 실패 시 계정 잠금
  • 잠금 기간은 1분 (이후 재시도 허용)

1.5 토큰 관리 규칙​

  • 액세스 토큰 유효 기간: 30분 (단, DEV 환경에서는 5분)
  • 리프레시 토큰 유효 기간: 14일
  • 동시 활성 토큰은 사용자당 최대 1개 (단일 디바이스 로그인 정책)
  • 토큰 블랙리스트 관리
    • 로그아웃 시 해당 특정 토큰(JTI)을 즉시 블랙리스트에 추가 (사용자 계정 차단 아님)
    • 새 디바이스 로그인 시 이전 디바이스의 특정 토큰을 블랙리스트에 추가
    • 블랙리스트된 토큰은 모든 API 요청에서 거부 (새 토큰 발급은 정상 진행)
    • 블랙리스트 TTL은 토큰 만료 시간과 동일하게 설정하여 자동 정리
    • 사용자는 언제든 재로그인하여 새로운 유효한 토큰을 발급받을 수 있음
  • Mobile 요구사항 (클라이언트 측 처리)
    • 비활성 상태 30분 이내에는 간편인증/로그인 없이 사용 가능
    • 비활성 상태 30분 ~ 4시간 이내에는 간편인증(PIN code, 생체인증)으로 사용 가능
    • 비활성 상태 4시간 이후 자동 로그아웃
      • 로컬 토큰 삭제하여 다시 로그인 하도록 유도
  • 게스트 토큰 추가 규칙
    • 게스트 Access Token 유효 기간은 최대 15분, Refresh Token은 12시간을 초과할 수 없음
    • 게스트 토큰은 발급된 디바이스(App Token)와 반드시 바인딩되어야 하며, 다른 디바이스에서 사용 시 거부
    • Step-up 인증이 완료되면 기존 게스트 토큰과 Refresh Token은 즉시 블랙리스트 처리

1.6 Access Code 검증 규칙​

  • 시스템은 회원 가입 시 사용자의 Access Code 유효성을 검증해야 함
  • 동일한 디바이스 ID에 대해 Access Code 검증 시도는 시간당 최대 10회까지만 허용됨
  • 10회 시도 실패 시, 해당 디바이스 ID는 1시간 동안 추가적인 Access Code 검증 요청이 거부되어야 함
  • 이 실패 횟수는 Redis를 사용하여 추적 및 관리함 (예: access_code_attempt:<hashed_device_id> 키 사용, 1시간 TTL 설정)

1.7 게스트 온보딩 및 Step-up 규칙​

  • 게스트 온보딩 시 필수 약관에 모두 동의해야 하며, 동의하지 않은 경우 계정을 생성할 수 없음
  • 게스트 온보딩은 App Token 검증과 디바이스 무결성 검사를 통과한 클라이언트에서만 허용
  • Step-up 인증은 게스트 토큰을 발급받은 동일 디바이스에서만 진행 가능
  • Step-up 인증 실패가 연속 3회를 초과하면 계정을 일시 잠금하고 추가 조치 안내
  • Step-up 완료 시 identityLevel을 registered 이상으로 승격하고, 승격 이벤트를 User/IAM/Plan/Group 도메인에 발행

2. 권한 관리 규칙​

2.1 역할 관리 규칙​

  • 기본 역할: ADMIN, USER, GUEST
  • 사용자는 여러 역할 보유 가능
  • ADMIN 역할은 시스템에서 1명 이상 필수
  • 역할 삭제 시 해당 역할의 모든 권한도 삭제

2.2 권한 관리 규칙​

  • 권한은 리소스와 작업의 조합
  • 기본 작업: CREATE, READ, UPDATE, DELETE, EXECUTE
  • 권한 상속 지원 (상위 권한이 하위 권한 포함)
  • 권한 변경 시 즉시 적용

2.3 접근 제어 규칙​

  • 리소스 접근 시 권한 검사 필수
  • 권한 없는 접근 시도 시 감사 로그 기록
  • IP 기반 접근 제한 지원
  • 시간 기반 접근 제한 지원

3. 보안 정책 규칙​

3.1 토큰 관리 규칙​

  • JWT 토큰 사용
  • 토큰 서명에 RSA 키 사용
  • 키 교체 주기: 90일
  • 토큰 페이로드에 최소 정보만 포함
  • 토큰에 민감한 개인정보를 포함해서는 안 됨

3.2 감사 로그 규칙​

  • 모든 인증 시도 기록
  • 권한 변경 이력 기록
  • 보안 정책 변경 이력 기록
  • 로그 보관 기간: 1년

3.3 보안 헤더 규칙​

  • HTTPS 필수
  • HSTS 헤더 사용
  • CSP 헤더 설정
  • X-Frame-Options 설정

3.4 데이터 보호 규칙​

  • 비밀번호는 bcrypt로 해시
  • 개인정보는 암호화 저장
  • 토큰은 서버 측에서만 생성
  • 민감 정보는 로그에 기록 금지

4. 통합 규칙​

4.1 OAuth 통합 규칙​

  • 지원 제공자: GesundheitsID
  • 제공자별 설정 관리
  • 사용자 프로필 동기화
  • 토큰 갱신 자동화

4.2 알림 규칙​

  • 로그인 시도 알림 (선택적)
  • 비밀번호 변경 알림 (필수)
  • 보안 정책 변경 알림 (관리자)
  • 계정 잠금 알림 (필수)

5. 예외 처리 규칙​

5.1 인증 예외​

  • 잘못된 인증 정보: 401 Unauthorized
  • 권한 없음: 403 Forbidden
  • 계정 잠금: 423 Locked
  • 토큰 만료: 401 Unauthorized

5.2 입력 검증 예외​

  • 잘못된 이메일 형식: 400 Bad Request
  • 약한 비밀번호: 400 Bad Request
  • 중복된 사용자: 409 Conflict
  • 잘못된 토큰 형식: 400 Bad Request

5.3 시스템 예외​

  • 데이터베이스 오류: 500 Internal Server Error
  • 캐시 서버 오류: 500 Internal Server Error
  • 외부 서비스 오류: 502 Bad Gateway
  • 타임아웃: 504 Gateway Timeout

6. 앱 토큰 규칙​

6.1 토큰 생성 규칙​

  1. 앱 식별

    • 앱 ID는 필수이며 유효해야 함
    • 앱은 활성 상태여야 함

  2. 권한 범위

    • 최소 하나 이상의 권한이 지정되어야 함
    • 권한은 미리 정의된 값만 사용 가능
    • 권한 조합의 유효성 검증 필요

  3. 디바이스 ID

    • 디바이스 ID는 SHA-256 알고리즘으로 해싱되어야 함
    • 디바이스 ID 해싱 시 앱 시크릿을 솔트로 사용해야 함
    • 디바이스 정보는 UUID, 플랫폼, 버전, 타임스탬프를 포함해야 함
    • 디바이스 정보 검증 실패 시 토큰 발급 거부
    • 원본 디바이스 정보는 노출되지 않아야 함

  4. 유효 기간

    • 만료 시간은 현재 시간보다 미래여야 함
    • 최대 유효 기간은 24시간으로 제한
    • 갱신 불가능 (만료 시 재발급 필요)

6.2 토큰 검증 규칙​

  1. 형식 검증

    • 토큰이 유효한 형식이어야 함
    • 서명이 유효해야 함
    • 필수 클레임이 모두 존재해야 함

  2. 상태 검증

    • 토큰이 만료되지 않았어야 함
    • 토큰이 취소되지 않았어야 함
    • 앱이 활성 상태여야 함

  3. 권한 검증

    • 요청된 API에 필요한 권한이 토큰에 포함되어야 함
    • 권한의 계층 구조 고려
    • 권한 조합의 유효성 검증

6.3 토큰 관리 규칙​

  1. 토큰 조회

    • 앱 토큰 정보는 관리자 권한으로만 조회 가능
    • 조회 시 토큰 자체는 마스킹 처리
    • 마지막 사용 시간 기록

  2. 토큰 취소

    • 관리자 권한으로 토큰 취소 가능
    • 취소된 토큰은 즉시 무효화
    • 취소 이력 기록

6.4 보안 규칙​

  1. 디바이스 ID 보안

    • 디바이스 ID는 항상 암호화된 상태로 전송
    • 복호화는 서버 측에서만 수행
    • 복호화된 디바이스 ID는 로그에 기록하지 않음

  2. 디바이스 ID 보안

    • 디바이스 ID는 항상 해싱된 상태로 전송 및 저장
    • 해싱은 SHA-256 알고리즘 사용
    • 앱 시크릿을 솔트로 사용하여 해시 보안 강화
    • 원본 디바이스 정보는 로그에 기록하지 않음

  3. 토큰 사용 제한

    • 동일 앱 ID에 대한 토큰 발급 횟수 제한
    • 비정상적인 토큰 사용 패턴 감지
    • 의심스러운 활동 시 토큰 자동 취소

  4. 앱 무결성 검증

    • 토큰 발급 전 앱 무결성 검증 필수
    • 시간 기반 챌린지-응답 메커니즘 사용
    • 챌린지는 일회용이며 5분 내 응답 필요
    • 무결성 검증 실패 시 토큰 발급 거부
    • 반복적인 검증 실패 시 디바이스 블랙리스트 추가

7. GesundheitsID 규칙​

7.1 GesundheitsID 연결 규칙​

  1. 연결 조건

    • 사용자는 유효한 GesundheitsID를 보유해야 함
    • 하나의 계정에는 하나의 GesundheitsID만 연결 가능
    • 이미 다른 계정에 연결된 GesundheitsID는 사용 불가

  2. 연결 프로세스

    • 사용자는 반드시 기존 인증 방식으로 로그인된 상태여야 함
    • GesundheitsID 연결 전 사용자 본인 확인 필요
    • 연결 시 GesundheitsID 유효성 검증 수행
    • 연결 완료 후 사용자에게 알림 제공

  3. 연결 해제

    • 연결 해제는 기존 인증 방식으로 로그인된 상태에서만 가능
    • 연결 해제 시 사용자 재인증 필요
    • 연결 해제 즉시 GesundheitsID 로그인 불가
    • 연결 해제 시 관련 정보 보관 기간은 30일

7.2 GesundheitsID 로그인 규칙​

  1. 인증 프로세스

    • GesundheitsID 인증은 공식 API를 통해서만 수행
    • 인증 요청은 HTTPS로만 전송
    • 인증 응답은 서명 검증 후 처리
    • 제3자 인증 위임 불가

  2. 토큰 관리

    • GesundheitsID 토큰은 별도로 암호화하여 저장
    • 토큰 유효 기간은 GesundheitsID 정책 준수
    • 토큰 갱신은 백그라운드로 자동 처리
    • 토큰 오류 발생 시 재인증 요구

  3. 보안 요구사항

    • PKCE(Proof Key for Code Exchange) 사용 필수
    • 사용자 정보는 필요한 범위로만 요청
    • OAuth 상태 파라미터 검증 필수
    • 인증 실패 로그 기록 및 모니터링

7.3 GesundheitsID 정보 관리 규칙​

  1. 정보 접근

    • GesundheitsID 관련 정보는 암호화하여 저장
    • 정보 접근은 필요한 경우에만 허용
    • 접근 이력 기록 및 정기 감사
    • 사용자 요청 시 정보 제공 가능

  2. 정보 갱신

    • 사용자 정보는 주기적으로 갱신
    • 갱신 주기는 최소 30일
    • 갱신 실패 시 사용자에게 알림
    • 장기간 갱신 실패 시 재연결 요구

8. 다국어 지원 규칙​

8.1 이메일 인증 다국어 지원​

  1. 지원 언어

    • 기본 언어: 독일어(de)
    • 추가 지원 언어: 영어(en), 한국어(ko)
    • 필요에 따라 더 많은 언어 지원 확장 가능

  2. 언어 선택 메커니즘

    • 클라이언트 요청의 Accept-Language 헤더를 기반으로 언어 결정
    • 헤더가 없거나 지원하지 않는 언어인 경우 기본 언어(독일어) 사용
    • 헤더에 품질 값(q 매개변수)이 있는 경우 이를 고려해 최적의 언어 선택

  3. 이메일 템플릿 규칙

    • 모든 템플릿은 지원하는 각 언어별로 유지 관리
    • 이메일 제목과 본문 모두 선택된 언어로 제공
    • 공통 레이아웃과 스타일은 언어에 관계없이 일관되게 유지
    • 날짜, 시간, 숫자 형식은 해당 언어/지역의 표준을 따름

  4. 인증 코드 표현

    • 인증 코드는 언어에 관계없이 항상 동일한 형식(6자리 숫자)
    • 인증 코드 표시 방식은 가독성을 위해 언어별로 최적화 가능
    • 코드 만료 시간은 수신자의 언어로 표시 (예: "5분", "5 minutes", "5 Minuten")

8.2 API 다국어 지원​

  1. 글로벌 언어 지원 원칙

    • 모든 API는 다국어 지원을 기본 원칙으로 함
    • 기본 언어: 독일어(de)
    • 추가 지원 언어: 영어(en), 한국어(ko)
    • 필요에 따라 지원 언어 확장 가능

  2. 언어 결정 메커니즘

    • 모든 API 요청은 Accept-Language 헤더를 통해 클라이언트의 언어 선호도 분석
    • 헤더가 없거나 지원하지 않는 언어인 경우 기본 언어(독일어) 사용
    • 헤더에 여러 언어가 지정된 경우, 우선순위(q 매개변수)에 따라 지원 가능한 최적 언어 선택
    • 언어 코드는 ISO 639-1 표준(2자리 코드)을 따름

  3. 응답 메시지 처리

    • 오류 메시지, 상태 메시지, 안내 메시지 등 모든 응답 텍스트는 선택된 언어로 제공
    • 메시지 템플릿은 언어별로 관리하며 동적 값 삽입 지원
    • 기술적 로그 메시지나 디버깅 정보는 언어 변환 대상에서 제외

  4. 메타데이터 및 에러 코드

    • API 응답의 메타데이터 구조는 언어와 관계없이 일관되게 유지
    • 에러 코드는 언어와 독립적인 고유 식별자로 제공
    • 에러 설명만 선택된 언어로 제공

  5. 콘텐츠 국제화

    • 날짜, 시간, 숫자, 통화 등의 형식은 선택된 언어/지역 표준을 따름
    • 문화적 맥락이 필요한 콘텐츠는 언어별로 적절히 현지화

  6. 개발 및 유지보수 규칙

    • 모든 다국어 텍스트는 코드에서 분리하여 별도 리소스로 관리
    • 언어 리소스 업데이트는 코드 변경 없이 가능해야 함
    • 새로운 텍스트 추가 시 지원하는 모든 언어에 대한 번역 필수
    • 번역 누락 시 기본 언어(독일어) 텍스트로 대체

9. 이메일 인증 규칙​

9.1 이메일 인증 코드 발송 규칙​

  • 이메일 인증 코드는 6자리 숫자로 구성
  • 코드 유효 시간은 5분
  • 동일 이메일 주소에 대해 10분 내 최대 5회까지만 발송 가능
  • 동일 IP 주소에 대해 1분 내 최대 60회까지만 발송 가능
  • 발송 제한 초과 시 429 Too Many Requests 응답 반환

9.2 이메일 인증 코드 재발송 규칙 (Exponential Backoff)​

  • 동일 이메일 주소에 대한 재발송은 지수 백오프 패턴을 따름:
    • 1차 재발송: 10초 대기 후 가능
    • 2차 재발송: 30초 대기 후 가능
    • 3차 재발송: 90초 대기 후 가능
    • 4차 재발송: 300초(5분) 대기 후 가능
    • 5차 재발송: 900초(15분) 대기 후 가능
    • 6차 재발송: 1800초(30분) 대기 후 가능
    • 이후: 최대 86400초(24시간)까지 점진적 증가
  • 재발송도 전체 발송 제한(10분 내 5회) 횟수에 포함됨
  • 재발송 버튼은 계산된 대기시간 경과 후 활성화
  • 24시간 후 대기시간은 초기값(10초)으로 리셋

9.3 이메일 인증 코드 검증 규칙​

  • 동일 이메일 및 requestId에 대해 최대 10회까지만 검증 시도 허용
  • 10회 검증 실패 시 해당 인증 코드 무효화
  • 검증 실패 시 해당 이메일 주소는 1시간 동안 잠금 상태
  • 잠못된 코드 입력 시 남은 시도 횟수 표시
  • 시도 횟수 초과 시 잠금 해제까지 남은 시간 표시

9.4 이메일 인증 보안 규칙​

  • 모든 이메일 인증 시도는 로그에 기록
  • 비정상적인 패턴(과도한 재발송, 무차별 대입 공격 등) 감지 시 자동 차단
  • 이메일 주소별 일일 인증 시도 제한: 최대 20회
  • IP 주소별 일일 인증 시도 제한: 최대 200회

10. 사용자 유형 분리 규칙​

10.1 사용자 유형 정의​

  • 사용자는 권한 관리와 데이터 분리를 위해 다음 유형으로 구분됩니다:
    • PATIENT: 환자(고객) - private 스키마
    • OPERATION_USER: 내부 운영자 - operation 스키마
    • SERVICE_ACCOUNT: 서비스 계정 - operation 스키마
  • 내부 운영자(OPERATION_USER)는 그룹과 역할을 통해 세부 권한이 관리됩니다 (IAM 도메인).

10.2 데이터 저장 규칙​

  • 고객(환자) 사용자 데이터는 private 스키마에 저장됩니다.
  • 내부 운영자, 의료진 등의 사용자 데이터는 operation 스키마에 저장됩니다.
  • 유형별로 다른 스키마를 사용하더라도 데이터 구조는 동일하게 유지됩니다.
  • 토큰, 세션 등의 관련 데이터도 사용자 유형에 따라 적절한 스키마에 저장됩니다:
    • 고객(환자) 관련: private.refresh_tokens, private.sessions, private.app_tokens
    • 내부 운영자 관련: operation.refresh_tokens, operation.sessions, operation.app_tokens

10.3 접근 제어 규칙​

  • 내부 운영자 인증 관련 API는 일반 사용자(PATIENT)가 접근할 수 없습니다.
  • 내부 운영자 등록은 SYSTEM_ADMIN 권한을 가진 사용자만 수행할 수 있습니다.
  • 내부 운영자 삭제도 SYSTEM_ADMIN 권한을 가진 사용자만 수행할 수 있습니다.
  • 내부 운영자 토큰 및 세션 관리는 해당 운영자 자신 또는 SYSTEM_ADMIN 권한을 가진 사용자만 수행할 수 있습니다.

10.4 내부 운영자 인증 규칙​

  • 내부 운영자 로그인 시에도 앱 인증(App Token)이 필요합니다.
  • 내부 운영자 인증은 일반 사용자와 동일한 보안 정책을 따르나, 추가적인 보안 요구사항이 적용될 수 있습니다.
  • 내부 운영자 계정은 비활성화 기간이 길어질 경우(예: 90일) 자동으로 잠금 상태로 전환될 수 있습니다.
  • 내부 운영자 계정은 역할(Role) 기반 접근 제어를 적용하며, 역할은 IAM 도메인에서 관리됩니다.
  • 내부 운영자의 권한은 사용자 유형과 할당된 역할의 조합으로 결정됩니다.

10.5 사용자 유형 전환 규칙​

  • 사용자 유형 변경 시 데이터 마이그레이션 프로세스가 필요합니다.
  • 사용자 유형 변경은 SYSTEM_ADMIN 권한을 가진 사용자만 수행할 수 있습니다.
  • 유형 변경 시 기존 인증 정보(토큰, 세션)는 모두 폐기되며, 재로그인이 필요합니다.
  • 유형 변경 이력은 감사 로그에 기록되어야 합니다.

10.6 MAO 티어/동의/라우팅 연계 규칙​

  • 토큰 클레임에 tier(anonymous/guest/member), consent_version, allowed_domains, data_persistence를 포함하며 누락 시 tier=anonymous, allowed_domains=[], data_persistence=none으로 강등 평가한다.
  • anonymous/guest 토큰은 개인화 컨텍스트 금지, FAQ/정보성 에이전트만 허용한다(allowed_domains 기본값: anonymous=["faq","docs-public","agent-help-public"], guest=["faq","docs-public","agent-help-public","sleep-education"]). 익명 토큰 발급은 유효한 appToken 인증 시에만 허용하며 기본 클레임을 강제한다.
  • guest→member 승격 시 기존 토큰을 즉시 폐기(블랙리스트)하고 재발급 전 동의/허용 도메인/보존 정책을 재평가한다.
  • MAO/Chat은 tier 미제공 시 anonymous로 간주하며, 컨텍스트 어셈블러는 NOT_READY 상태로 폴백한다.
  • TTL/보존을 준수한다: Access token anonymous/guest 15분, member 30분; Refresh token member 7일(anonymous/guest 없음); 컨텍스트/대화 guest 3일(1~7일 범위), anonymous 없음, member 규제 준수(예: 90일); 그룹 멤버십 anonymous 1일, guest 7일, member 영속.

11. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-03-25bok@weltcorp.com최초 작성
0.2.02025-04-29bok@weltcorp.com약관 관리 규칙을 Term 도메인으로 이동
0.3.02025-04-29bok@weltcorp.com동의(Consent) 관리 규칙을 Consent 도메인으로 이동
0.4.02025-05-01bok@weltcorp.com다국어 지원 규칙 추가 (이메일 인증)
0.5.02025-05-01bok@weltcorp.com모든 API에 대한 다국어 지원 규칙 추가
0.6.02025-05-07bok@weltcorp.com사용자 유형 분리 규칙 추가 (환자와 내부 운영자)
0.7.02025-08-06bok@weltcorp.com이메일 인증 규칙 추가 (Exponential Backoff 재발송 제한, 검증 제한, 보안 규칙)
0.8.02025-08-06bok@weltcorp.com이메일 인증 규칙 추가 (재발송 제한, 검증 제한, 보안 규칙)
0.9.02025-08-11bok@weltcorp.comJWT stateless 인증 방식에 맞게 세션 관리 규칙을 토큰 관리 규칙으로 변경, 토큰 블랙리스트 관리 규칙 추가, 사용자당 1개 디바이스 정책으로 일관성 확보
1.0.02025-11-26bok@weltcorp.comMAO 라우팅을 위한 tier/consent/allowed_domains/data_persistence 클레임과 anonymous/guest 제약, 승격 시 토큰 폐기 규칙 추가
1.1.02025-11-26bok@weltcorp.comallowed_domains 기본값, TTL/보존 수치, anonymous 강등/FAQ 스코프 제한을 확정 반영
1.2.02025-11-26bok@weltcorp.com익명 토큰 발급을 appToken 인증으로 제한하고 기본 클레임 강제 규칙 반영