forked from baron/baron-sso
306 lines
14 KiB
Markdown
306 lines
14 KiB
Markdown
# 외부 RP Ory IAM 연동 가이드 초안
|
|
|
|
본 문서는 외부 RP가 자체 IAM을 만들지 않고 Baron SSO/Ory Stack/Keto 기반 공용 IAM을 연동하기 위한 초안입니다.
|
|
|
|
## 공개 Manifest
|
|
|
|
- HTML: `/.well-known/baron-rp-manifest`
|
|
- JSON: `/.well-known/baron-rp-manifest.json`
|
|
- JSON Schema: `/.well-known/baron-rp-manifest.schema.json`
|
|
|
|
RP는 JSON manifest를 우선 기준으로 삼고, HTML 페이지는 사람이 확인하는 규격 문서로 사용합니다.
|
|
|
|
## Identity Contract
|
|
|
|
RP는 raw `kratos_identity_id`를 비즈니스 키로 저장하거나 파싱하지 않습니다. `X-Baron-External-Key`는 RP가 생성하거나 제출하는 값이 아니라, Baron이 인증된 subject를 기준으로 발급 또는 조회해서 RP 요청 직전에 주입하는 Baron-issued alias입니다.
|
|
|
|
- `X-Baron-Subject`: Keto 권한 판정 subject입니다. 예: `User:<baron_identity_id>`
|
|
- `X-Baron-External-Key`: RP의 local user insert/upsert에 쓰는 opaque external key입니다. RP는 이 값을 해석하지 않고 전체 문자열 그대로 저장합니다.
|
|
- `X-Baron-Client-ID`: 현재 요청이 속한 RP client id입니다.
|
|
|
|
RP의 local user key는 `provider + external_key` 조합으로 저장합니다. 이메일은 변경될 수 있으므로 stable primary key로 사용하지 않습니다.
|
|
|
|
정리하면 “RP가 알고 저장할 수 있는 값”은 Baron이 주입한 canonical external alias뿐입니다. RP가 alias를 직접 만들거나 raw `kratos_identity_id`에서 alias를 계산하면 안 됩니다. 최초 로그인 또는 최초 접근 시 RP가 사용자를 생성해야 한다면, Baron이 이미 주입한 `X-Baron-External-Key`를 사용해 insert/upsert합니다.
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[User authenticates through Baron SSO] --> B[Baron resolves internal identity]
|
|
B --> C[Baron derives or loads Baron-issued alias]
|
|
C --> D[Baron injects X-Baron-External-Key]
|
|
D --> E[Baron injects X-Baron-Subject]
|
|
E --> I[RP receives trusted headers from Baron gateway]
|
|
I --> F[RP upserts local user with provider + X-Baron-External-Key]
|
|
F --> G[RP stores the full external key as opaque value]
|
|
G --> H[RP never parses or stores raw kratos_identity_id]
|
|
```
|
|
|
|
## OIDC Tenant Claim Contract
|
|
|
|
Baron은 기본적으로 대표소속 tenant와 전체 소속 tenant 목록을 식별할 수 있도록 `tenant_id`, `joined_tenants`를 ID token claim에 포함할 수 있습니다. RP가 OIDC scope 또는 client metadata 정책을 통해 `tenant` claim을 요청하면 Baron은 여기에 더해 tenant별 상세 정보를 포함합니다. 이 claim은 RP가 UI 표시, 조직 맥락 선택, RP 내부 권한 매핑을 시작하기 위한 입력이며, 최종 권한 판정은 Baron gateway/Keto check 또는 Baron이 발급한 trusted header를 기준으로 해야 합니다.
|
|
|
|
기본 claim 구조는 다음과 같습니다.
|
|
|
|
```json
|
|
{
|
|
"tenant_id": "01970f0a-5c28-74d8-a73a-f6e9e9a7b210",
|
|
"joined_tenants": [
|
|
"01970f0a-5c28-74d8-a73a-f6e9e9a7b210",
|
|
"01970f0b-3448-7bb8-bdc7-16b6a1d2e661"
|
|
]
|
|
}
|
|
```
|
|
|
|
`tenant` claim을 요청하면 상세 claim 구조는 다음과 같습니다.
|
|
|
|
```json
|
|
{
|
|
"tenant_id": "01970f0a-5c28-74d8-a73a-f6e9e9a7b210",
|
|
"joined_tenants": [
|
|
"01970f0a-5c28-74d8-a73a-f6e9e9a7b210",
|
|
"01970f0b-3448-7bb8-bdc7-16b6a1d2e661"
|
|
],
|
|
"lead_tenants": ["01970f0a-5c28-74d8-a73a-f6e9e9a7b210"],
|
|
"tenants": {
|
|
"01970f0a-5c28-74d8-a73a-f6e9e9a7b210": {
|
|
"id": "01970f0a-5c28-74d8-a73a-f6e9e9a7b210",
|
|
"slug": "tech-planning",
|
|
"name": "기술기획팀",
|
|
"type": "USER_GROUP",
|
|
"lead": true,
|
|
"representative": true,
|
|
"isPrimary": true,
|
|
"grade": "책임",
|
|
"jobTitle": "기술기획",
|
|
"position": "팀장",
|
|
"parentTenantId": "01970f08-91da-7286-bd19-882fb98d1f2c",
|
|
"ancestors": [
|
|
{
|
|
"id": "01970f08-91da-7286-bd19-882fb98d1f2c",
|
|
"slug": "hanmac",
|
|
"name": "한맥기술",
|
|
"type": "COMPANY",
|
|
"parentTenantId": "01970f07-4f01-7d9a-a71e-b53ad508f345"
|
|
},
|
|
{
|
|
"id": "01970f07-4f01-7d9a-a71e-b53ad508f345",
|
|
"slug": "hanmac-family",
|
|
"name": "한맥가족",
|
|
"type": "COMPANY_GROUP",
|
|
"parentTenantId": null
|
|
}
|
|
]
|
|
},
|
|
"01970f0b-3448-7bb8-bdc7-16b6a1d2e661": {
|
|
"id": "01970f0b-3448-7bb8-bdc7-16b6a1d2e661",
|
|
"slug": "quality",
|
|
"name": "품질관리팀",
|
|
"type": "USER_GROUP",
|
|
"lead": false,
|
|
"representative": false,
|
|
"isPrimary": false,
|
|
"grade": "선임",
|
|
"jobTitle": "품질관리",
|
|
"position": "파트원",
|
|
"parentTenantId": "01970f08-91da-7286-bd19-882fb98d1f2c",
|
|
"ancestors": [
|
|
{
|
|
"id": "01970f08-91da-7286-bd19-882fb98d1f2c",
|
|
"slug": "hanmac",
|
|
"name": "한맥기술",
|
|
"type": "COMPANY",
|
|
"parentTenantId": "01970f07-4f01-7d9a-a71e-b53ad508f345"
|
|
},
|
|
{
|
|
"id": "01970f07-4f01-7d9a-a71e-b53ad508f345",
|
|
"slug": "hanmac-family",
|
|
"name": "한맥가족",
|
|
"type": "COMPANY_GROUP",
|
|
"parentTenantId": null
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
필드 의미는 다음과 같습니다.
|
|
|
|
- `tenant_id`: 기본 claim입니다. 사용자의 대표소속 tenant UUID입니다. 현재 RP/client context tenant가 없더라도 공백으로 내려가지 않습니다.
|
|
- `joined_tenants`: 기본 claim입니다. 사용자가 claim 상에서 소속된 모든 tenant UUID 목록입니다. `additionalAppointments`의 모든 한맥가족 subtree tenant를 포함합니다.
|
|
- `lead_tenants`: `tenant` claim 요청 시 포함됩니다. `lead=true`로 판정된 tenant id 목록입니다.
|
|
- `tenants`: `tenant` claim 요청 시 포함됩니다. tenant UUID를 key로 하는 tenant별 claim map입니다. 멀티 소속이면 소속 tenant마다 하나씩 포함되며, `slug`는 별도 필드로 내려갑니다.
|
|
- `tenants.*.lead`: 해당 tenant에서 lead 권한 또는 조직장 역할이 있으면 `true`입니다. Baron 입력에서는 `lead`, `isLead`, `isOwner`, `isManager`를 수용할 수 있습니다.
|
|
- `tenants.*.representative`: 대표조직이면 `true`입니다. Baron 입력에서는 `representative`, `isPrimary`, `primary`를 수용할 수 있습니다.
|
|
- `tenants.*.grade`: 직급입니다.
|
|
- `tenants.*.jobTitle`: 직무입니다.
|
|
- `tenants.*.position`: 직책입니다.
|
|
- `tenants.*.parentTenantId`: 현재 tenant의 직속 parent tenant UUID입니다. 최상위 root면 `null`입니다.
|
|
- `tenants.*.ancestors`: 직속 상위 tenant부터 `hanmac-family` root까지의 parent chain입니다.
|
|
|
|
대표소속 결정 정책은 다음과 같습니다.
|
|
|
|
- 명시적인 `tenant_id`가 있으면 이를 대표소속으로 사용합니다.
|
|
- 명시적인 대표소속이 없으면 `additionalAppointments`에서 `representative=true`, `isPrimary=true`, `primary=true`인 소속을 사용합니다.
|
|
- 대표 표시가 없으면 가장 먼저 등록된 소속 tenant를 대표소속으로 사용합니다.
|
|
- 생성 시 소속 tenant가 하나도 없으면 Baron이 PERSONAL tenant를 자동 생성하고, 해당 PERSONAL tenant UUID를 `tenant_id`와 `joined_tenants`에 포함합니다.
|
|
- RP/client의 tenant context는 대표소속을 덮어쓰지 않습니다. RP context tenant가 필요한 경우 별도 필드나 RP route context로 다뤄야 합니다.
|
|
|
|
한맥가족(`hanmac-family`) subtree에 속한 tenant claim은 다음 규칙을 따릅니다.
|
|
|
|
- `TenantService.GetTenant` 기준 parent chain이 `hanmac-family` root에 도달한 경우에만 한맥가족 확장 필드를 보강합니다.
|
|
- `additionalAppointments`만 존재하고 tenant별 namespaced traits map이 없어도 `tenant_id` 또는 `additionalAppointments[].tenantId`를 기준으로 `tenants` 항목을 생성할 수 있습니다.
|
|
- 사용자가 여러 tenant에 소속되면 기본 claim인 `joined_tenants`에는 모든 소속 tenant가 포함됩니다.
|
|
- `tenant` claim 요청 시 `tenants`에도 모든 소속 tenant의 상세가 포함되고, `lead_tenants`에는 그중 `lead=true`인 tenant만 포함됩니다.
|
|
- 직급/직무/직책과 대표조직/lead 여부는 사용자 소속 metadata(`additionalAppointments`)를 우선합니다.
|
|
- `ancestors`는 직속 상위 tenant부터 root 방향으로 정렬되며, root가 `hanmac-family`일 때까지만 포함합니다.
|
|
- 기본 tenant와 각 ancestor 객체는 `parentTenantId`를 포함합니다. 이 필드로 parent edge를 바로 그릴 수 있습니다.
|
|
|
|
주의사항:
|
|
|
|
- Tenant tree, 직급, 직무, 직책은 PostgreSQL Business SoT와 tenant/user metadata를 기준으로 합니다. Kratos traits는 인증 식별 정보 중심으로 유지해야 하며, 관계형 데이터의 영구 SoT로 취급하지 않습니다.
|
|
- Token 크기가 커질 수 있으므로 RP가 긴 조직 전체 정보를 필요로 하면 ID token claim보다 userinfo/profile API 또는 Baron backend API 연동을 우선 검토합니다.
|
|
- RP는 `lead_tenants` 또는 `tenants.*.lead`만으로 보안상 중요한 권한을 단독 판정하지 않습니다. 권한 변경/민감 리소스 접근은 Keto 기반 Baron authorization contract를 함께 사용해야 합니다.
|
|
|
|
### Issue #775 구현 결과 예시
|
|
|
|
아래 예시는 #775 구현 후 `tenant_id=01970f0a-5c28-74d8-a73a-f6e9e9a7b210`, 사용자 `additionalAppointments`에 대표 소속 `tech-planning`과 겸직 소속 `quality`가 함께 있고, 두 tenant의 parent chain이 `hanmac -> hanmac-family`로 이어지는 경우 ID token에 내려가는 데이터 형태입니다. 예시의 `id` 값은 UUID 형식의 샘플이며, `slug`와 다릅니다.
|
|
|
|
```json
|
|
{
|
|
"email": "hanmac-user@example.com",
|
|
"name": "한맥 사용자",
|
|
"tenant_id": "01970f0a-5c28-74d8-a73a-f6e9e9a7b210",
|
|
"joined_tenants": [
|
|
"01970f0a-5c28-74d8-a73a-f6e9e9a7b210",
|
|
"01970f0b-3448-7bb8-bdc7-16b6a1d2e661"
|
|
],
|
|
"lead_tenants": [
|
|
"01970f0a-5c28-74d8-a73a-f6e9e9a7b210"
|
|
],
|
|
"tenants": {
|
|
"01970f0a-5c28-74d8-a73a-f6e9e9a7b210": {
|
|
"id": "01970f0a-5c28-74d8-a73a-f6e9e9a7b210",
|
|
"slug": "tech-planning",
|
|
"name": "기술기획팀",
|
|
"type": "USER_GROUP",
|
|
"lead": true,
|
|
"representative": true,
|
|
"isPrimary": true,
|
|
"grade": "책임",
|
|
"jobTitle": "기술기획",
|
|
"position": "팀장",
|
|
"parentTenantId": "01970f08-91da-7286-bd19-882fb98d1f2c",
|
|
"ancestors": [
|
|
{
|
|
"id": "01970f08-91da-7286-bd19-882fb98d1f2c",
|
|
"slug": "hanmac",
|
|
"name": "한맥기술",
|
|
"type": "COMPANY",
|
|
"parentTenantId": "01970f07-4f01-7d9a-a71e-b53ad508f345"
|
|
},
|
|
{
|
|
"id": "01970f07-4f01-7d9a-a71e-b53ad508f345",
|
|
"slug": "hanmac-family",
|
|
"name": "한맥가족",
|
|
"type": "COMPANY_GROUP",
|
|
"parentTenantId": null
|
|
}
|
|
]
|
|
},
|
|
"01970f0b-3448-7bb8-bdc7-16b6a1d2e661": {
|
|
"id": "01970f0b-3448-7bb8-bdc7-16b6a1d2e661",
|
|
"slug": "quality",
|
|
"name": "품질관리팀",
|
|
"type": "USER_GROUP",
|
|
"lead": false,
|
|
"representative": false,
|
|
"isPrimary": false,
|
|
"grade": "선임",
|
|
"jobTitle": "품질관리",
|
|
"position": "파트원",
|
|
"parentTenantId": "01970f08-91da-7286-bd19-882fb98d1f2c",
|
|
"ancestors": [
|
|
{
|
|
"id": "01970f08-91da-7286-bd19-882fb98d1f2c",
|
|
"slug": "hanmac",
|
|
"name": "한맥기술",
|
|
"type": "COMPANY",
|
|
"parentTenantId": "01970f07-4f01-7d9a-a71e-b53ad508f345"
|
|
},
|
|
{
|
|
"id": "01970f07-4f01-7d9a-a71e-b53ad508f345",
|
|
"slug": "hanmac-family",
|
|
"name": "한맥가족",
|
|
"type": "COMPANY_GROUP",
|
|
"parentTenantId": null
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"profile": {
|
|
"emails": [
|
|
"hanmac-user@example.com"
|
|
],
|
|
"names": {
|
|
"name": "한맥 사용자"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
RP 소비 기준:
|
|
|
|
- lead tenant를 빠르게 찾을 때는 `lead_tenants`를 우선 사용합니다.
|
|
- 전체 소속 tenant 목록은 `joined_tenants`로 읽고, 각 소속의 상세 조직 맥락은 `tenants[joined_tenants[n]]`에서 읽습니다.
|
|
- 대표소속의 상세 조직 맥락은 `tenants[tenant_id]`에서 읽습니다.
|
|
- 상위 조직 breadcrumb은 `tenants[tenant_id].ancestors`를 직속 상위부터 root 방향으로 표시합니다.
|
|
- 조직 트리 edge는 기본 tenant와 각 ancestor의 `parentTenantId`를 사용해 그립니다.
|
|
- 대표조직 여부는 `representative`를 우선 사용하고, 기존 primary 표현 호환이 필요하면 `isPrimary`를 함께 읽습니다.
|
|
|
|
## obj_id 조회 흐름
|
|
|
|
`obj_id`는 Keto check의 target object입니다. 명시적으로 전달된 `obj_id`가 있으면 정규화 후 사용하고, 없으면 route context에서 `client_id`, `tenant_id` 순서로 추론합니다. 둘 다 없으면 RP가 명확한 target object를 제공하지 않은 것이므로 요청을 거부해야 합니다.
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[RP request] --> B{obj_id supplied?}
|
|
B -->|yes| C[Normalize object type and obj_id]
|
|
B -->|no| D{Route has client_id?}
|
|
D -->|yes| E[obj_id = RelyingParty:<client_id>]
|
|
D -->|no| F{Route has tenant_id?}
|
|
F -->|yes| G[obj_id = Tenant:<tenant_id>]
|
|
F -->|no| H[Reject: explicit obj_id required]
|
|
C --> I[Check Keto relation]
|
|
E --> I
|
|
G --> I
|
|
I --> J{allowed?}
|
|
J -->|yes| K[Inject trusted Baron headers]
|
|
J -->|no| L[Reject request]
|
|
K --> M[Write audit with obj_id, relation, client_id, X-Request-Id]
|
|
```
|
|
|
|
대표 object 패턴은 다음과 같습니다.
|
|
|
|
- RP 단위: `RelyingParty:<client_id>`
|
|
- Tenant 단위: `Tenant:<tenant_id>`
|
|
- RP 내부 리소스 단위: `Resource:<resource_type>:<resource_id>`
|
|
|
|
## Audit Contract
|
|
|
|
audit 누락 방지는 범위를 나눠서 보장합니다.
|
|
|
|
- Baron이 중개하는 IAM mutation은 `fail_closed_sync`입니다. audit write가 실패하면 원 요청도 실패해야 합니다.
|
|
- audit sink가 없거나 사용할 수 없으면 mutation은 `reject_mutation`으로 처리합니다.
|
|
- allowlist된 read audit은 부하 보호를 위해 best effort로 둘 수 있으나, 권한/설정 변경 command에는 적용하지 않습니다.
|
|
- RP 자체 비즈니스 이벤트는 RP가 동일한 `X-Request-Id`를 correlation key로 사용해 audit을 남겨야 합니다.
|
|
|
|
필수 audit detail 필드는 다음과 같습니다.
|
|
|
|
- `obj_id`
|
|
- `relation`
|
|
- `client_id`
|
|
- `subject`
|
|
- `decision`
|
|
|
|
따라서 “audit 누락 없음”은 Baron-mediated IAM command에 대해 보장합니다. RP 내부에서 직접 발생하는 비즈니스 이벤트까지 포함하려면 RP가 이 audit contract를 구현하고, audit 저장 실패 시 동일하게 fail closed 처리해야 합니다.
|