다크모드
IAM·권한 용어 정본
정본 출처 —
docs/decisions/IAM-ARCHITECTURE-REVIEW-2026-07-25.md(rev.5). 이 페이지는 결정 문서의 용어를 직원·개발자용으로 요약한 것이며, 서술이 충돌하면 결정 문서가 우선합니다.
직원과 개발자가 같은 단어를 같은 뜻으로 쓰기 위한 페이지입니다. 화면·문서·코드 리뷰에서 여기 없는 용어나 아래 표의 구용어가 보이면 정본 용어로 교정합니다.
A. 테넌시 계층
Leysys internal operations (`ops-center` surface — 고객 IAM 밖)
└─ Organization 고객 조직 · 계약 · 청구 · 조직 정책의 경계 = 테넌트 루트
├─ Organization Unit HR 조직도(부서·본부). 기본적으로 인가 경계 아님
└─ Workspace 현장 · 오피스 · 사업장 등 운영 경계| 용어 | 한국어 UI | 한 줄 정의 |
|---|---|---|
| Organization | 조직 | 계약·청구·조직 정책·데이터 소유의 경계이자 테넌트 루트 |
| Organization Unit | 조직도(부서) | HR 조직 구조. 기본적으로 인가 경계가 아닙니다 |
| Workspace | 워크스페이스 | 업무·장부·운영의 경계 |
대원칙 — Organization Role은 Workspace에 같은 등급으로 투영.organization.owner → workspace.owner, admin → admin, manager → manager, viewer → viewer로 산하 모든 Workspace에 적용됩니다. Workspace에 직접 부여한 Role은 해당 Workspace에서만 효력이 있고 Organization으로 역상속하지 않습니다.
B. 주체·식별·로그인
| 용어 | 한국어 UI | 한 줄 정의 | 구용어/금지 혼용어 |
|---|---|---|---|
| Principal | 사용자 / 시스템 주체 | 인증되어 권한을 부여받는 사람 또는 시스템. 불변 ID이며 재할당하지 않습니다 | account, user record |
| Organization Username | 아이디 | 조직 코드 범위에서 사람이 입력하는 계정 이름 | 로그인 ID, signInId |
| Workspace Username | 아이디 | 워크스페이스 코드 범위에서 사람이 입력하는 계정 이름 | 로그인 ID, signInId |
| SignIn Identifier | — | 이메일과 username을 함께 처리하는 추상 인증 경계. 특정 요청에서는 타입별 필드를 우선합니다 | loginId, signInId |
| SignIn Context | 로그인 문맥 | organization / workspace. 고객 인증 정책·발견 표면·세션 정책의 경계 | realm(내부 문서에서만 병용) |
| Organization Code | 조직 코드 | org- + 소문자 Crockford Base32 10자. 공개 식별자이며 비밀·인증 요소가 아닙니다 | 고객사코드 |
| Workspace Code | 워크스페이스 코드 | ws- + 소문자 Crockford Base32 10자. 공개 식별자이며 비밀·인증 요소가 아닙니다 | — |
| SignIn Identifier Key | — | 서버가 code와 username을 조합해 만드는 내부 조회 key. 사용자가 직접 입력하지 않습니다 | sign_in_name |
고객 로그인 흐름은 3개입니다.
- Organization Owner — 이메일: 인증 후 active
organization.owner를 재검증하고, Owner인 Organization이 여러 개면 조직 선택 화면이 열립니다. - Organization 최고관리자/중간관리자/조회자 — 조직 코드 + 아이디: 요청은
organizationCode와organizationUsername을 분리해 보냅니다. - Workspace — 워크스페이스 코드 + 아이디: 요청은
workspaceCode와workspaceUsername을 분리해 보내며 Organization Membership을 요구하지 않습니다. 이메일 로그인은 지원하지 않습니다.
Organization 이메일은 Role key가 아닌 인증 방법이지만, 제품 정책상 active organization.owner에게만 허용됩니다. 이메일 인증 성공이 Owner Role을 만들지 않으며, 서버가 active Membership과 organization.owner Role Assignment를 다시 검증합니다. Leysys 본사는 별도 ops-center staff surface와 인증 영역을 사용하며 고객 IAM에 platform 또는 superadmin Role은 없습니다.
C. 소속·접근
| 용어 | 한국어 UI | 한 줄 정의 | 구용어/금지 혼용어 |
|---|---|---|---|
| Organization Affiliation | 조직 귀속 | Principal ↔ Organization의 프로필·좌석·수명주기 귀속. 접근권을 만들지 않습니다 | 조직 권한, 조직 계정 |
| Organization Membership | 조직 소속 | Principal ↔ Organization의 접근 관계 | 계정, 권한 |
| Workspace Membership | 워크스페이스 배정 | Principal ↔ Workspace의 접근 관계. Organization Membership을 요구하지 않습니다 | 공용 워크스페이스 계정 |
| Access Invitation | 초대 | 초대는 접근권이 아닙니다. 수락 시 한 트랜잭션으로 Membership이 생성됩니다 | — |
| Organization Owner | 조직 소유자 | Organization은 항상 유효한 Owner를 1명 이상 유지합니다 | — |
Membership 상태 기계 — 초대와 Membership은 별도 엔티티입니다.
access_invitation.pending ──accept(단일 트랜잭션)──▶ membership.active
│
├──revoke──▶ revoked
└──expire──▶ expired
membership.active ──suspend──▶ suspended ──resume──▶ active
├──expire(기간만료)──▶ expired
└──terminate────────▶ terminatedexpired/terminated는 종단 상태입니다. 재개는 새 Membership 행 생성으로만 가능하며, 옛 Role Assignment는 새 Membership에서 부활하지 않습니다.
세 가지 소속 형태
| 형태 | affiliation | org membership | workspace membership | 예시 |
|---|---|---|---|---|
| 조직 사용자 | 있음 | 있음 | 0개 이상 | 본사 업무 사용자, 경리, 감사 |
| 조직+현장 겸직 | 있음 | 있음 | 1개 이상 | 본사 회계가 3개 현장 담당 |
| 현장 전용 | 있음(권한 없음) | 없음 | 1개 이상 | 현장직, 협력업체, 경비원, 외부 회계 |
D. 역할·권한
| 용어 | 한국어 UI | 한 줄 정의 | 구용어/금지 혼용어 |
|---|---|---|---|
| Role | 역할 | Organization 또는 Workspace 범위의 누적 access tier이자 업무 권한 상한선입니다 | 직급, 등급 |
| Permission | 권한 | {scope}.{domain}.{resource}.{operation} 키의 행위 허용. 키는 불변이며 의미가 바뀌면 새 키를 만듭니다 | 기능, 메뉴권한 |
| Role Assignment | 역할 부여 | 특정 Membership ID를 참조하는 부여. Membership이 끝나면 함께 효력을 잃습니다 | 권한부여 |
- 역할 축 단순화 — 초기 access Role은 두 scope의 동일한 4단계만 사용합니다. 직무별 사용자 Permission grant는 두지 않습니다.
- Organization→Workspace 투영 — 별도 opt-in 없이 같은 등급으로 적용됩니다. Workspace 직접 Role은 투영 Role보다 엄격히 높은 경우에만 저장할 수 있고, 그 Workspace에서 높은 등급이 효과 Role이 됩니다. 같거나 낮은 중복 부여는 거부합니다. Organization Role 승격으로 기존 직접 Role이 같거나 낮아지면 해당 직접 Role과 더 이상 필요 없는 Workspace Workspace Username을 원자적으로 폐기하며, 나중에 Organization Role을 낮춰도 자동 복원하지 않습니다.
- 사용자별 Permission 부여 없음 — 초기 allow 판정은 8개 Role의 계층, scope-aware helper, 도메인 RPC가 소유합니다. 물리
permissions/role_permissions카탈로그는 두지 않으며, 직무별 세분화는 실제 요구와 grant/revoke/audit 계약이 함께 확정될 때 별도 결정으로 도입합니다. - default-deny · Hard Deny 우선 — 명시적으로 허용된 것만 허용되며, 규제·SoD·인증 보증 같은 contextual policy의 Hard Deny가 Allow보다 우선합니다.
기본 Role 카탈로그
| 범위 | Role key | 한국어 UI | 핵심 책임 |
|---|---|---|---|
| Organization | organization.owner | 소유자 | 소유권·계약·결제, Owner 관리, 소유권 이전·조직 종료 |
| Organization | organization.admin | 최고관리자 | 조직 설정·구성원·Owner 아래 Role·Workspace 관리 |
| Organization | organization.manager | 중간관리자 | 조직 범위의 일상 업무 데이터·비민감 운영 상태 생성·편집·처리 |
| Organization | organization.viewer | 조회자 | 허용된 조직 정보와 산하 Workspace 업무 데이터 조회 |
| Workspace | workspace.owner | 소유자 | Workspace 최고 권한, Owner 관리·이전, 종료 절차 시작 |
| Workspace | workspace.admin | 최고관리자 | Workspace 설정·구성원·Owner 아래 Role 관리 |
| Workspace | workspace.manager | 중간관리자 | 활성 상품의 일상 업무 데이터·비민감 운영 상태 생성·편집·처리 |
| Workspace | workspace.viewer | 조회자 | 허용된 Workspace 설정·업무 데이터 조회 |
두 scope 모두 owner > admin > manager > viewer 누적 계층입니다. Owner는 Admin을, Admin은 Manager를, Manager는 Viewer Permission을 포함합니다.
owner: 소유권·Owner 지정·이전·종료 같은 최종 책임을 가집니다. Organization Owner는 계약·결제도 관리합니다.admin(최고관리자): 설정·구성원·Owner 아래 Role을 관리하지만 소유권·Owner·계약·결제·종료를 변경하지 않습니다.manager(중간관리자): 일상 업무 데이터와 비민감 운영 상태를 처리하지만 IAM·보안·소유권·계약·결제· 생명주기를 관리하지 않습니다. 고위험 승인·반출·마감은 도메인 정책이 추가로 제한합니다.viewer: 허용된 데이터만 조회하고 mutation을 수행하지 않습니다.
조회자는 모든 업무 테이블의 전 행을 읽는 역할이 아닙니다. 타인의 근태·스케줄·예외는 중간관리자 이상에게만, 법적 고용계약은 소유자·최고관리자에게만 열립니다. 정확한 본인 정보 조회 예외도 현재 로그인 세션과 활성 Workspace 배정을 확인합니다.
기본 Role은 테넌트 공유 데이터 권한의 상한선입니다. 초기 모델에는 별도 Functional Permission grant를 두지 않습니다. 직원·고객 포털의 본인 신청처럼 자기 소유 리소스에 대한 self-service와 현재 pending 단계에 명시된 workflow assignee의 결정은 별도의 주체·배정 권한으로 판정합니다. 이 예외도 정확한 로그인 세션과 활성 관계를 요구하며 타인의 공유 데이터 수정으로 확장되지 않습니다.
operator | auditor | contract_admin | accountant | editor | maintainer는 초기 기본 Role이 아닙니다. 직무별 차이는 현재 도메인 정책으로 제한하며, 별도 Functional Permission은 grant/revoke/audit 요구가 확정된 뒤 도입합니다. 감사 로그 열람은 별도 auditor Role 없이 Organization Owner/Admin에게 Organization 전체를, Workspace Owner/Admin에게 자기 Workspace의 로컬 이벤트만 허용합니다.
Organization Owner를 최고관리자·중간관리자·조회자로 변경하려면 먼저 해당 계정에 active Organization Username이 있어야 합니다. 없으면 변경이 거부됩니다. Owner로 승격하면 기존 Organization Username은 만료되고 이메일 로그인만 사용합니다.
식별자 구분자 규칙 — 서로 다른 종류를 같은 어휘로 오인하지 않습니다.
- Role key는 권한 namespace라서
{scope}.{level}의 dot을 사용합니다. 예:organization.owner,workspace.manager. - 로그인 응답 kind는 권한 Role이 아닌 API discriminator라서 kebab-case를 사용합니다. 예:
organization-member,workspace-member. - SQL relation·column·enum segment는 snake_case를 사용합니다.
- 공개 Organization/Workspace Code의
org-/ws-하이픈은 code prefix입니다.
E. 상품 × 권한
| 용어 | 한국어 UI | 한 줄 정의 |
|---|---|---|
| Product Subscription | 상품 구독 | Organization 단위의 계약 상태 |
| Product Activation | 상품 활성화 | 특정 Workspace에서 상품이 운영 가능한 상태 |
| Retention Right | 보존 접근권 | 구독 종료 후 한시적으로 유지되는 조회·반출 권리. Membership·Role·Scope 검사를 우회하지 않습니다 |
| Compliance Constraint | 규제 제약 | 법·계약이 강제하는 금지/의무(마감, 보존, 파기) |
상품과 권한의 결합은 Role key나 감사 행위 어휘에 넣지 않습니다. Organization 계약 항목과 Workspace의 유효 상품 활성화 판정이 상품 게이트의 정본입니다.
F. 판정·보안
| 용어 | 한국어 UI | 한 줄 정의 |
|---|---|---|
| Authorization Epoch | (비노출) | 신원·소속·역할·정책·상품 객체의 판정 버전. 변경 시 증가하며 판정 캐시가 검증합니다. 사용자에게 노출하지 않습니다 |
| Authentication Assurance | 인증 보증 수준 | 인증 강도·수단·시각·step-up 충족 상태. 권한을 만들지 않지만 민감 행위를 제한합니다 |
Active Context는 권한 근거가 아닙니다. UI에서 현재 선택한 조직/워크스페이스는 화면 상태일 뿐이며, API는 요청 대상 리소스로부터 scope를 도출합니다.
G. 구용어/폐기 용어
| 구용어/금지 혼용어 | 정본 용어 | 혼동 주의 |
|---|---|---|
| entitlement | Product Activation | SCIM User.entitlements와 동음이의 충돌이 있어 사용자 권한 의미로 쓰지 않습니다 |
고객 Role의 platform / superadmin | — | Leysys 본사 접근은 고객 Role이 아니라 별도 ops-center staff surface·인증 영역을 사용합니다 |
IAM Role의 operator / auditor / contract_admin / accountant | owner / admin / manager / viewer | 초기 기본 Role은 두 scope에서 동일한 4단계 계층만 사용합니다. 직무 차이는 도메인 정책으로 제한하고 사용자별 Functional Permission은 후속 결정으로 둡니다 |
IAM Role의 editor / maintainer | manager | 일상 업무 데이터·비민감 운영 상태 변경은 중간관리자 책임으로 통일합니다. 고위험 행위는 서버 도메인 정책이 추가로 제한합니다 |
| resident | — | 입주민·투숙객은 고객사의 데이터 주체이지 Leyve Principal이 아니며, B2C 접근은 별도 identity 도메인입니다 |
| workforce 인증 모델 | Organization/Workspace scoped SignIn | workforce_identities 기반 인증 계약은 2026-07-25 폐기됐습니다. 단, HR 원장 workforce_employees 등 인사 도메인 테이블은 별개로 현행 유효합니다 |
| workplace | — | 근로계약서의 "근무장소" 텍스트 필드일 뿐이며 IAM의 Workspace와 무관합니다 |
로그인 화면·운영 절차는 Organization·Workspace 로그인과 관리를 참고하세요.