IAM·권한 용어 정본
정본 출처 — leysys-design
ACCESS-ROLE-SYSTEM-2026-10-03(공통 역할 체계)과docs/decisions/IAM-ARCHITECTURE-REVIEW-2026-07-25.md(rev.6), 채택 기록docs/decisions/ACCESS-ROLE-SYSTEM-ADOPTION-2026-10-04.md. 이 페이지는 결정 문서의 용어를 직원·개발자용으로 요약한 것이며, 서술이 충돌하면 결정 문서가 우선합니다.
직원과 개발자가 같은 단어를 같은 뜻으로 쓰기 위한 페이지입니다. 화면·문서·코드 리뷰에서 여기 없는 용어나 아래 표의 구용어가 보이면 정본 용어로 교정합니다.
A. 테넌시 계층
Leysys internal operations (`ops-center` surface — 고객 IAM 밖)
└─ Organization 고객 조직 · 계약 · 청구 · 조직 정책의 경계 = 테넌트 루트
├─ Organization Unit HR 조직도(부서·본부). 기본적으로 인가 경계 아님
└─ Workspace 현장 · 오피스 · 사업장 등 운영 경계| 용어 | 한국어 UI | 한 줄 정의 |
|---|---|---|
| Organization | 조직 | 계약·청구·조직 정책·데이터 소유의 경계이자 테넌트 루트 |
| Organization Unit | 조직도(부서) | HR 조직 구조. 기본적으로 인가 경계가 아닙니다 |
| Workspace | 현장 | 업무·장부·운영의 경계 |
대원칙 — 조직 역할은 공개 현장에만 같은 값으로 상속. 조직과 워크스페이스는 같은 역할 값 admin(관리자) · editor(편집자) · viewer(조회자)를 씁니다. 조직 역할은 공개 현장(Workspace)에 같은 값으로 적용됩니다. 비공개 현장은 직접 부여한 역할만 적용하며, 조직 관리자도 사유를 입력해 명시적으로 참여해야 합니다. 직접 역할은 해당 현장에서만 효력이 있고 조직으로 역상속하지 않습니다. 조직 소유는 역할이 아니므로 상속하지 않습니다.
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개입니다.
- 조직 소유자 — 이메일: 인증 후 활성 조직 소유 지정과 조직 관리자 역할을 재검증하고, 조직 소유자인 조직이 여러 개면 조직 선택 화면이 열립니다.
- 조직 관리자·편집자·조회자 — 조직 코드 + 아이디: 요청은
organizationCode와organizationUsername을 분리해 보냅니다. - Workspace — 워크스페이스 코드 + 아이디: 요청은
workspaceCode와workspaceUsername을 분리해 보내며 Organization Membership을 요구하지 않습니다. 이메일 로그인은 지원하지 않습니다.
조직 이메일은 역할이 아닌 인증 방법이지만, 제품 정책상 조직 소유자에게만 허용됩니다. 이메일 인증 성공이 조직 소유를 만들지 않으며, 서버가 활성 Membership, 관리자 역할, 활성 조직 소유 지정을 다시 검증합니다. 조직 소유에서 나온 동작(계약·결제, 조직 소유자 지정·회수·이전, 조직 종료)은 조직 소유자 이메일 세션에서만 씁니다. Leysys 본사는 별도 ops-center staff surface와 인증 영역을 사용하며 고객 IAM에 platform 또는 superadmin 역할은 없습니다.
C. 소속·접근
| 용어 | 한국어 UI | 한 줄 정의 | 구용어/금지 혼용어 |
|---|---|---|---|
| Organization Affiliation | 조직 귀속 | Principal ↔ Organization의 프로필·좌석·수명주기 귀속. 접근권을 만들지 않습니다 | 조직 권한, 조직 계정 |
| Organization Membership | 조직 소속 | Principal ↔ Organization의 접근 관계 | 계정, 권한 |
| Workspace Membership | 워크스페이스 배정 | Principal ↔ Workspace의 접근 관계. Organization Membership을 요구하지 않습니다 | 공용 워크스페이스 계정 |
| Access Invitation | 초대 | 초대는 접근권이 아닙니다. 수락 시 한 트랜잭션으로 Membership이 생성됩니다 | — |
| 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 | 역할 | 조직 또는 워크스페이스 범위의 누적 접근 수준. 값은 admin · editor · viewer입니다 | 직급, 등급, 권한 |
| Permission | 권한 | {domain}.{resource}.{action} 키의 행위 허용(판정 결과). 키는 불변이며 의미가 바뀌면 새 키를 만듭니다 | 기능, 메뉴권한 |
| Role Assignment | 역할 부여 | 특정 Membership ID를 참조하는 부여. Membership이 끝나면 함께 효력을 잃습니다 | 권한부여 |
| Ownership | 조직 소유 | 조직 소유자 지정(관계). 상태는 초대 중 · 활성 · 종료(회수 · 이전 · 만료 · 나감)입니다 | owner 역할 |
역할 값과 라벨 — 조직과 워크스페이스가 같은 세 값을 씁니다. 순서는 표·선택·범례 모두 위 등급부터입니다.
| 값 | 한국어 UI | 한 줄 설명 |
|---|---|---|
admin | 관리자 | 사람·역할·설정·워크스페이스를 관리하고 모든 업무를 합니다. |
editor | 편집자 | 업무 데이터를 생성·편집·삭제합니다. 삭제는 복구할 수 있습니다. 사람·역할·설정은 바꾸지 않습니다. |
viewer | 조회자 | 업무 데이터를 조회합니다. 민감한 정보는 제품이 가리고, 생성·편집·삭제는 하지 않습니다. |
| 관계 | 한국어 UI | 하는 일 |
|---|---|---|
organization.owner | 조직 소유자 | 계약·결제의 최종 통제, 조직 소유자 지정·회수·이전, 조직 종료를 맡습니다. |
- 누적 계층 — 관리자는 편집자의, 편집자는 조회자의 권한을 모두 가집니다. 등급은 위 등급부터 나열한 배열 하나(
ACCESS_ROLES)에서 계산합니다. - 조직 소유는 역할이 아닙니다 — 조직 소유자는 조직 관리자 역할을 함께 가지며, 관리자는 조직 소유자의 관리자 역할을 낮추거나 회수하지 못합니다. 조직 소유자를 관리자 아래로 낮추려면 먼저 조직 소유 지정을 회수합니다. 유효 조직 소유자를 0명으로 만드는 변경(정지 등)은 막힙니다. 조직 소유 지정은 검증된 이메일 계정에만 합니다.
- 워크스페이스 소유는 없습니다 — 이전의 워크스페이스 소유자는 워크스페이스 관리자로 옮겼습니다. 워크스페이스 관리자의 부여·회수는 조직 관리자만 하고, 워크스페이스 관리자는 그 워크스페이스의 편집자·조회자만 다룹니다.
- 직접 역할 — 공개 현장의 직접 역할은 조직에서 상속한 역할보다 높을 때만 저장할 수 있고, 그 현장에서 높은 쪽이 유효 역할이 됩니다. 같거나 낮은 중복 부여는 거부합니다. 조직 역할을 올려 기존 직접 역할이 같거나 낮아지면 그 직접 역할을 정리하며, 나중에 조직 역할을 낮춰도 자동 복원하지 않습니다. 비공개 현장은 조직 역할을 상속하지 않으며 직접 역할로만 판정합니다. 일반 역할 변경으로 자기 역할은 바꾸지 못합니다.
- 사용자별 권한 부여 없음 — 역할 → 권한 키, 조직 소유 → 권한 키 대응은 제품마다 한 곳의 정적 표로 둡니다. 서버 판정이 정본이고 화면은 같은 표로 숨김·비활성만 보입니다. 직무별 세분화(추가 역할)는 실제 요구가 있을 때만 공통 결정 문서에 등록해 도입합니다.
- default-deny · Hard Deny 우선 — 명시적으로 허용된 것만 허용되며, 규제·SoD·인증 보증 같은 contextual policy의 Hard Deny가 Allow보다 우선합니다.
권한 키 — 형식은 {domain}.{resource}.{action}이고 모든 마디는 snake_case입니다. 동사는 read · create · update · delete · export · send · approve · grant · revoke만 씁니다. 범위 접두어는 붙이지 않습니다.
신규 조직 종료는 organization.organization.update와 종료 명령으로 기록하며, 기존 delete 권한 표기가 영구삭제 구현을 뜻하지 않습니다. 이 프로토타입은 기존 계약·가격·청구 이력을 삭제하지 않습니다. 예: access.role.grant, billing.contract.update, organization.setting.update, property.unit.create. 초대는 access.role.grant, 정지·복구는 access.role.update, 회수는 access.role.revoke, 조직 소유 지정·회수는 access.ownership.grant · access.ownership.revoke입니다.
조회자는 모든 업무 테이블의 전 행을 읽는 역할이 아닙니다. 타인의 근태·스케줄·예외는 편집자 이상에게만, 법적 고용계약은 관리자에게만 열립니다. 정확한 본인 정보 조회 예외도 현재 로그인 세션과 활성 워크스페이스 배정을 확인합니다. 감사 로그 열람은 별도 감사자 역할 없이 조직 관리자에게 조직 전체를, 워크스페이스 관리자에게 자기 워크스페이스의 로컬 이벤트만 허용합니다.
직원·고객 포털의 본인 신청처럼 자기 소유 리소스에 대한 self-service와 현재 pending 단계에 명시된 workflow assignee의 결정은 별도의 주체·배정 권한으로 판정합니다. 이 예외도 정확한 로그인 세션과 활성 관계를 요구하며 타인의 공유 데이터 수정으로 확장되지 않습니다.
허용되지 않을 때 — 그 역할로 쓸 수 없는 메뉴·동작은 숨깁니다. 상태 때문에 막힌 동작(유효 조직 소유자를 0명으로 만드는 변경 등)은 비활성 + 이유로 보입니다. 권한 없는 화면 주소로 직접 들어오면 다른 화면으로 보내지 않고 그 자리에서 「접근 권한이 없습니다」(403)를 보입니다. 이용하지 않는 모듈은 모듈 안내, 없는 주소는 404입니다.
행위 주체 — 역할과 사건의 주체를 다른 말로 씁니다. 사건 필드는 {동사}edAt · {동사}edBy이고 {동사}edBy는 주체 참조({ kind: person | organization | software | unknown, id, name })입니다. 화면 라벨은 「편집 주체」처럼 「{동사} 주체」이고, 여러 종류의 사건을 한 목록에 담는 기록은 「행위 주체」입니다. 「편집자」는 역할 라벨이므로 행위 주체에 쓰지 않습니다. 주체를 모르면 「알 수 없음」이며 「시스템」으로 채우지 않습니다. updatedAt은 「마지막 업데이트」, editedAt은 「마지막 편집」입니다.
식별자 구분자 규칙 — 서로 다른 종류를 같은 어휘로 오인하지 않습니다.
- 역할 값은 소문자 한 단어(
admin,editor,viewer)이고 범위는 역할 부여 표가 정합니다. 범위 참조 (organization.admin,workspace.editor)와 조직 소유 관계 참조(organization.owner)는 문서·감사 payload· 테스트에서만 쓰고 저장 값으로 쓰지 않습니다. - 권한 키는
{domain}.{resource}.{action}의 dot을 사용합니다. 예:access.role.grant. - 로그인 응답 kind는 역할이 아닌 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 | admin / editor / viewer | 기본 역할은 두 범위에서 같은 3단계만 사용합니다. 직무 차이는 도메인 정책으로 제한하고 추가 역할은 공통 결정 문서 등록 뒤에만 둡니다 |
역할 값 owner · 라벨 「소유자」(역할) | 관리자 역할 + 조직 소유자(관계) | 조직 소유는 역할이 아닙니다. 워크스페이스 소유(workspace.owner)는 없앴고 직접 부여된 값은 워크스페이스 관리자로 옮겼습니다 |
역할 값 manager · 라벨 「최고관리자」 · 「중간관리자」 | admin 관리자 · editor 편집자 | 관리자가 가장 높은 역할이므로 「최고」를 붙이지 않습니다. 편집자는 사람을 관리하지 않습니다. maintainer도 편집자로 통일합니다 |
권한 키 {scope}.{domain}.{resource}.{operation} | {domain}.{resource}.{action} | 범위 접두어를 붙이지 않고 동사는 닫힌 목록만 씁니다(2026-10-04 이행) |
행위 주체 라벨 「편집자」 · 「작업자」, 필드 lastEditorId | 「편집 주체」, lastEditedBy(주체 참조) | 「편집자」는 역할 라벨입니다. 행위 주체는 「{동사} 주체」로 씁니다 |
| resident | — | 입주민·투숙객은 고객사의 데이터 주체이지 Leyve Principal이 아니며, B2C 접근은 별도 identity 도메인입니다 |
| workforce 인증 모델 | Organization/Workspace scoped SignIn | workforce_identities 기반 인증 계약은 2026-07-25 폐기됐습니다. 단, HR 원장 workforce_employees 등 인사 도메인 테이블은 별개로 현행 유효합니다 |
| workplace | — | 근로계약서의 "근무장소" 텍스트 필드일 뿐이며 IAM의 Workspace와 무관합니다 |
로그인 화면·운영 절차는 Organization·Workspace 로그인과 관리를 참고하세요.