본문으로 건너뛰기

IAM 도메인 비즈니스 규칙

1. 일반 규칙​

1.1 스키마 정의​

  • IAM 도메인 관련 핵심 데이터(Permission, Role, 정책, 관계 테이블 등)는 iam PostgreSQL 스키마에 저장되어야 합니다.
  • Plan 데이터는 Plan 도메인(plan 스키마)에서 관리되며, IAM 도메인은 이를 참조합니다.
  • Group 데이터는 Group 도메인(group 스키마)에서 관리되며, IAM 도메인은 이를 참조합니다.
  • 사용자 유형에 따라 User 정보는 다른 스키마를 참조합니다:
    • 고객(환자) 사용자: User 도메인(private 스키마)
    • 내부 운영자, 의료진 등: User 도메인(operation 스키마)

1.2 고유성 제약​

  • 권한(Permission) ID는 시스템 전체에서 고유해야 합니다. (requirements.md 3.1)
  • 역할(Role) 이름(name)은 IAM 도메인 내에서 고유해야 합니다. (requirements.md 3.1)
  • 플랜(Plan) 이름은 Plan 도메인에서 관리되며, 그룹(Group) 이름은 Group 도메인에서 관리됩니다.

1.3 감사 로깅​

  • 권한, 역할, 정책(플랜/그룹 포함 간주) 데이터에 대한 모든 접근 및 변경은 감사 로그로 기록되어야 합니다. (requirements.md 2.1)
  • 권한 검증 시도 및 결과는 감사 로그로 기록되어야 합니다. (requirements.md 1.2)
  • 역할 할당 및 해제에 대한 감사 로그를 기록해야 합니다. (requirements.md 1.3)
  • Audit 도메인과의 의존성을 가집니다. (requirements.md 5.1)

2. 권한(Permission) 규칙​

2.1 명명 규칙​

  • 권한 이름(ID)은 {domain}:{resource}:{action} 형식을 따릅니다. (permissions.md 2절)
    • 예: user:account:read, iam:role:create

2.2 권한 관리​

  • 권한은 생성, 조회, 수정, 삭제(CRUD)될 수 있습니다 (주로 System Admin). (requirements.md 1.2)
  • 권한 ID는 생성 후 변경할 수 없습니다. (requirements.md 3.1)
  • 권한은 설명(description) 메타데이터를 가질 수 있습니다. (requirements.md 1.2)
  • 권한 간의 계층 구조나 그룹핑은 선택적으로 지원될 수 있습니다 (현재 모델에서는 미구현). (requirements.md 1.2, 3.1)

2.3 권한 검증​

  • 시스템은 실시간으로 사용자의 특정 권한 보유 여부를 검증할 수 있어야 합니다. (requirements.md 1.2)
  • 요청 컨텍스트(예: 특정 리소스 ID)를 기반으로 권한을 평가할 수 있어야 합니다. (requirements.md 1.2)

3. 역할(Role) 규칙​

3.1 역할 정의​

  • 역할은 특정 기능 또는 책임 단위를 나타내며, 여러 권한(Permission)의 집합으로 구성됩니다. (requirements.md 1.3)

3.2 역할 관리​

  • 역할은 생성, 조회, 수정, 삭제(CRUD)될 수 있습니다. (requirements.md 1.3)
  • 역할은 설명(description) 메타데이터를 가질 수 있습니다. (requirements.md 1.3)
  • 역할은 활성/비활성 상태(isActive)를 가집니다. (requirements.md 1.3)
  • 역할 변경 이력을 관리해야 합니다. (requirements.md 1.3)
  • 역할 계층 구조 내에서 순환 참조는 허용되지 않습니다. (requirements.md 3.1)

3.3 역할-권한 할당​

  • 역할에 여러 권한(Permission)을 할당하거나 해제할 수 있어야 합니다. (requirements.md 1.3)
  • 이 관계는 RolePermission 테이블을 통해 관리됩니다. (domain-model.md 3.7, Prisma Schema)
  • 게스트 전용 역할(role.guest.default)은 민감 권한을 포함할 수 없으며, Step-up 완료 시 즉시 제거되어야 합니다.
  • 게스트 역할에 대한 권한 변경은 Plan/Group의 게스트 정책과 일관되게 유지되어야 하며, 변경 시 관련 캐시를 무효화합니다.

4. 플랜(Plan) 연동 규칙​

4.1 Plan 도메인 의존성​

  • 플랜의 생명주기 관리, 플랜 유형 정의, 플랜별 기능 범위 등은 Plan 도메인에서 관리됩니다.
  • IAM 도메인은 Plan 도메인에서 정의된 플랜 정보를 참조하여 권한 부여를 담당합니다.
  • 플랜 관련 비즈니스 규칙은 Plan 도메인의 business-rules.md를 참조하시기 바랍니다.

4.2 플랜-역할 매핑 관리​

  • IAM 도메인은 플랜과 역할(Role) 간의 매핑 관계를 관리합니다.
  • 플랜에 할당된 역할 정보를 기반으로 사용자 권한을 계산합니다.
  • 플랜-역할 매핑 변경 시 관련 권한 캐시를 무효화합니다.

4.3 플랜 기반 권한 부여​

  • 사용자의 플랜 정보를 기반으로 적절한 역할과 권한을 부여합니다.
  • 플랜 변경 시 해당 사용자들의 권한이 자동으로 업데이트되도록 지원합니다.
  • 플랜-역할 매핑 정보는 성능을 위해 캐싱됩니다.

5. 그룹(Group) 연동 규칙​

5.1 Group 도메인 의존성​

  • 그룹의 생명주기 관리, 그룹 유형 정의, 그룹 계층 구조 등은 Group 도메인에서 관리됩니다.
  • IAM 도메인은 Group 도메인에서 정의된 그룹 정보를 참조하여 권한 부여를 담당합니다.
  • 그룹 관련 비즈니스 규칙은 Group 도메인의 business-rules.md를 참조하시기 바랍니다.

5.2 그룹 기반 권한 부여​

  • IAM 도메인은 그룹을 통한 역할 할당 및 정책 적용을 지원합니다.
  • 그룹에 직접 할당된 역할을 기반으로 사용자에게 권한을 부여합니다.
  • 그룹 변경 시 관련 사용자들의 권한 캐시를 무효화합니다.
  • 그룹은 플랜과 독립적으로 운영되며, 그룹 기반 권한은 조직/기능적 권한을 나타냅니다.

5.3 그룹-사용자 관계 관리​

  • 사용자-그룹 관계 정보를 기반으로 권한을 계산합니다.
  • 그룹 소속 변경 시 해당 사용자의 권한이 자동으로 업데이트되도록 지원합니다.
  • 그룹-역할 매핑 정보는 성능을 위해 캐싱됩니다.

6. 사용자 할당 규칙​

6.1 사용자-그룹 관계 연동​

  • 사용자-그룹 관계 정보는 Group 도메인에서 관리되며, IAM 도메인은 이를 참조합니다.
  • IAM 도메인은 사용자-그룹 관계를 기반으로 권한 계산을 수행합니다.
  • 그룹 할당 변경 시 해당 사용자의 권한 캐시를 무효화합니다.

6.2 권한 계산 연동​

  • 사용자의 그룹 소속 정보와 플랜 할당 정보를 독립적으로 조회합니다.
  • 모든 사용자는 최소 하나 이상의 그룹에 속해야 합니다 (User 도메인 요구사항 참조).
  • 모든 사용자는 정확히 하나의 플랜에 속해야 합니다 (User 도메인 요구사항 참조).
  • 다차원 권한 계산: 그룹 기반 권한과 플랜 기반 권한을 모두 계산한 후 교집합을 구합니다.

7. 접근 제어 결정 규칙​

7.1 다차원 권한 파생 경로​

  • 사용자의 최종 접근 권한은 그룹 권한과 플랜 권한의 교집합으로 결정됩니다. (requirements.md 1.7)
  • 그룹 권한 경로: User → Group → Role → Permission (조직/기능적 권한)
  • 플랜 권한 경로: User → Plan → Role → Permission (서비스 수준 권한)
  • 최종 권한: GroupPermissions ∩ PlanPermissions
  • 이 과정에서 User 도메인, Group 도메인, Plan 도메인의 정보를 참조합니다.
  • 권한 계산 시 Access Token의 identityLevel을 입력으로 받아, guest 수준 토큰에는 게스트 허용 목록만 적용해야 합니다.
  • 게스트 사용자라 하더라도 특정 플랜·그룹 조합으로 인해 권한이 확장되지 않도록 identityLevel 기반 deny 규칙을 우선 적용합니다.

7.2 유효 권한 계산​

  • 시스템은 두 권한 경로를 독립적으로 계산한 후 교집합을 구해야 합니다. (requirements.md 1.7)
  • 특정 사용자의 특정 권한 보유 여부는 두 경로 모두에서 해당 권한을 가져야 true로 판단됩니다.
  • 특정 사용자에 대해 최종적으로 부여된 모든 유효 권한 목록을 조회하는 기능(API)이 제공되어야 합니다 (주로 AuthorizationService). (requirements.md 1.7, domain-model.md 6)
  • 그룹 또는 플랜 변경 시 권한 캐시는 즉시 무효화되어야 합니다.
  • 게스트 토큰은 identityLevel=guest로 표시되며, 게스트 허용 목록 외의 권한이 교집합에 포함되더라도 접근이 거부되어야 합니다.
  • Step-up 완료 시 auth.identity-level.changed 이벤트를 수신하여 해당 사용자의 권한 캐시를 즉시 무효화합니다.

7.7 사용자 데이터 스키마 분리 규칙​

7.7.1 사용자 유형 분류​

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

7.7.2 스키마 분리 원칙​

  • 사용자 유형에 따라 적절한 스키마에서 데이터를 저장하고 조회합니다.
  • 사용자 유형이 변경될 경우 데이터 마이그레이션 프로세스가 필요합니다.
  • 사용자-그룹 관계 테이블도 사용자 유형에 맞는 스키마에 저장됩니다:
    • 고객(환자): private.user_groups
    • 내부 운영자: operation.user_groups

7.7.3 권한 계산​

  • 사용자의 유형과 무관하게 IAM 권한 체계는 동일하게 적용됩니다.
  • 다차원 권한 계산 모델(그룹 권한 ∩ 플랜 권한)은 사용자 유형과 무관하게 일관되게 적용됩니다.
  • 권한 계산 시 사용자 유형에 따라 적절한 스키마에서 사용자-그룹 관계 정보를 조회합니다.
  • 플랜 정보는 사용자 유형과 무관하게 User 도메인에서 직접 관리됩니다.

7.7.4 접근 제어​

  • 내부 운영자는 기본적으로 고객(환자) 사용자와 다른 접근 권한을 가집니다.
  • 시스템 관리자 권한을 가진 내부 운영자는 일반적으로 가장 높은 수준의 시스템 접근 권한을 가집니다.
  • 서비스 계정(SERVICE_ACCOUNT 유형)은 제한된 API 호출 권한만 가집니다.
  • 사용자 유형 간의 권한 계층 구조를 필요에 따라 정의할 수 있습니다.

8. 보안 규칙​

8.1 접근 제어 원칙​

  • 모든 API 요청은 인증 및 인가를 거쳐야 합니다. (requirements.md 2.1)
  • 역할 기반 접근 제어(RBAC)를 지원해야 합니다. (requirements.md 2.1)
  • 최소 권한 원칙을 적용해야 합니다. (requirements.md 2.1)

8.2 데이터 보안​

  • 민감한 권한 또는 정책 관련 정보(필요시)는 암호화하여 저장해야 합니다. (requirements.md 2.1)
  • 권한 데이터의 무결성을 보장해야 합니다. (requirements.md 2.1)

8.3 API 보안​

  • API 입력값 검증을 통해 보안 취약점을 방지해야 합니다. (requirements.md 2.1)
  • 비정상적인 요청 패턴을 방지하기 위해 Rate Limiting을 적용해야 합니다. (requirements.md 2.1, 3.2)
  • 게스트 Step-up 관련 API는 동일 디바이스 확인 및 시도 횟수 제한을 통해 남용을 방지해야 합니다.
  • API 호출에 대한 상세 감사 로그를 기록해야 합니다. (requirements.md 2.1)

9. 성능 규칙​

9.1 응답 시간 목표​

  • 권한 검증 API 평균 응답 시간: < 50ms (requirements.md 2.2)
  • 역할 조회 API 평균 응답 시간: < 100ms (requirements.md 2.2)
  • 유효 권한 계산/조회 API 평균 응답 시간: (명시적 목표는 없으나, 검증 API 수준 또는 약간 더 높게 설정 필요)
  • 할당/관리 API 평균 응답 시간: < 500ms (requirements.md 2.2)

9.2 처리량 목표​

  • 초당 최소 1000건의 권한 검증 요청 처리 가능해야 합니다. (requirements.md 2.2)
  • 초당 최소 100건의 역할/그룹 할당/해제 요청 처리 가능해야 합니다. (requirements.md 2.2)

9.3 캐싱 전략​

  • 권한 평가/검증 결과를 캐싱하여 반복적인 검증 속도를 향상시켜야 합니다. (requirements.md 1.2, 2.2)
  • 역할-권한, 플랜-역할, 사용자-그룹 매핑 정보를 캐싱해야 합니다. (requirements.md 2.2)
  • 캐시 데이터의 일관성을 유지하기 위한 적절한 무효화 전략이 필요합니다. (requirements.md 2.2)

10. 데이터 제약 규칙​

10.1 ID/이름 제약​

  • 권한 ID, 역할 이름, 플랜 이름, 그룹 이름은 고유해야 합니다. (상기 1.2 규칙 참조)
  • 권한 ID는 생성 후 변경 불가합니다. (requirements.md 3.1)

10.2 관계 제약​

  • 역할 계층 구조 내 순환 참조는 허용되지 않습니다. (requirements.md 3.1)
  • 사용자는 하나 이상의 그룹과 정확히 하나의 플랜에 속해야 합니다.
  • 그룹과 플랜은 서로 독립적으로 관리되며, 각각 역할을 직접 할당받습니다.
  • Prisma 스키마의 onDelete: Cascade 규칙에 따라 부모 엔티티 삭제 시 연관된 관계 데이터도 삭제됩니다 (RolePermission, PlanRole, UserGroup). (domain-model.md Prisma Schema)

11. API 호출 제한 규칙​

11.1 사용자 유형별 제한​

  • Service Account는 Rate Limit (예: 분당 1000 요청), 캐시 TTL (예: 5분), 동시 요청 수 (예: 100개), 배치 처리 제한 (예: 1000개) 등의 제한을 가집니다. (requirements.md 3.2)
  • Regular User는 더 엄격한 Rate Limit (예: 분당 100 요청), 캐시 TTL (예: 15분), 동시 요청 수 (예: 10개), 배치 처리 제한 (예: 100개) 등의 제한을 가집니다. (requirements.md 3.2)
  • System Admin/IAM Admin에 대한 구체적인 API 제한은 requirements.md 2.5에 있으나, 필요시 조정 가능합니다.

12. 서비스 간 인증 규칙​

12.1 Service Account 인증 방식 (API Key + JWT 하이브리드)​

  • Service Account는 Google Service Account와 유사한 API Key + JWT 하이브리드 방식을 사용합니다. (requirements.md 1.9)
  • 장기 자격증명: API Key는 Service Account의 장기 보관용 인증 키로, Google Service Account의 Private Key와 동일한 역할을 합니다. (requirements.md 1.9)
  • 단기 접근 토큰: JWT 토큰은 API Key를 사용하여 발급받는 단기 유효 토큰으로, 실제 API 호출에 사용됩니다. (requirements.md 1.9)
  • Service Account는 비밀번호 기반 인증을 사용하지 않습니다. (requirements.md 1.9)
  • JWT 토큰 발급 시 SHA-256 해시 알고리즘을 사용해야 합니다. (requirements.md 1.9)
  • JWT 토큰 서명은 RS256 또는 ES256 알고리즘을 사용해야 합니다. (requirements.md 1.9)

12.2 토큰 관리​

  • Service Account JWT 토큰은 발급, 검증, 무효화 기능을 제공해야 합니다. (requirements.md 1.9)
  • Service Account는 refresh token을 지원하지 않습니다. 토큰 만료 시 API Key를 사용하여 새로운 JWT 토큰을 발급받아야 합니다. (requirements.md 1.9)
  • 토큰 검증은 30ms 이내에 완료되어야 합니다. (requirements.md 1.9)
  • 초당 2000건의 토큰 검증 요청을 처리할 수 있어야 합니다. (requirements.md 1.9)
  • Service Account 토큰 및 권한 정보는 5분간 캐싱되어야 합니다. (requirements.md 1.9)

12.3 보안 규칙​

  • 최소 권한 원칙에 따라 Service Account 권한을 관리해야 합니다. (requirements.md 1.9)
  • Service Account별 Rate Limiting을 적용해야 합니다 (분당 1000 요청). (requirements.md 1.9)
  • 이상 패턴 감지 및 자동 차단 메커니즘을 구현해야 합니다. (requirements.md 1.9)
  • 서비스별 격리 및 네임스페이스를 적용해야 합니다. (requirements.md 1.9)

12.4 생명주기 관리​

  • Service Account는 생성, 활성화, 비활성화, 삭제의 생명주기를 가집니다. (requirements.md 1.9)
  • API 키 재생성 기능을 제공해야 합니다. (requirements.md 1.9)
  • JWT 토큰 전파 및 체이닝을 지원해야 합니다. (requirements.md 1.9)

12.5 MAO 티어/동의/라우팅 규칙​

  • 정책 평가 시 tier(anonymous/guest/member), consent_version, allowed_domains, data_persistence를 필수 입력으로 받고 누락 시 tier=anonymous, allowed_domains=[], data_persistence=none으로 강등한다.
  • 에이전트/툴 리소스 메타데이터에 requiredTier/requiresConsent를 선언하고, 조건 미충족 시 Deny-overrides로 처리한다.
  • guest→member 승격, consent_version 변경 이벤트 발생 시 정책 캐시를 무효화하고 재평가를 강제한다(guest 캐시 TTL 5분, member 15분).
  • anonymous/guest는 개인정보·PHI/PII 접근 리소스를 기본 차단하며 FAQ/정보성 도메인만 허용한다(allowed_domains 기본값: anonymous=["faq","docs-public","agent-help-public"], guest=["faq","docs-public","agent-help-public","sleep-education"]).

13. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-04-17bok@weltcorp.com최초 문서 생성
0.2.02025-05-07bok@weltcorp.com사용자 유형 분리에 따른 스키마 저장 규칙 추가
0.3.02025-06-13bok@weltcorp.com서비스 간 인증 규칙 추가 (12절)
0.4.02025-11-26bok@weltcorp.comMAO 라우팅을 위한 tier/consent/allowed_domains/data_persistence 기반 정책 평가 및 에이전트/툴 requiredTier 규칙 추가
0.5.02025-11-26bok@weltcorp.comallowed_domains 기본값, 캐시 TTL, anonymous 강등/차단 규칙 확정
0.4.02025-07-15bok@weltcorp.comPlan 관련 규칙을 별도 Plan 도메인으로 분리, Plan 도메인 의존성 추가 (4절 수정, 1.1, 1.2, 7.1절 수정)
0.5.02025-07-15bok@weltcorp.comGroup 관련 규칙을 별도 Group 도메인으로 분리, Group 도메인 의존성 추가 (5절, 6절 수정, 1.1, 1.2, 7.1절 추가 수정)
0.6.02025-07-16bok@weltcorp.com다차원 권한 계산 모델 도입: 5.2, 6.2, 7절 전면 수정, 10.2 그룹-플랜 연결 제약 제거, Group-Plan 독립성 확보
0.7.02025-10-27bok@weltcorp.com게스트 identityLevel 기반 권한 제한 및 Step-up 캐시 무효화 규칙 추가 (3.3, 7.1, 7.2, 8.3 보강)