baron-sso/docs/wiki-ory-ssot-cache-policy-update-2026-06-10.md

# Wiki Ory SSOT 및 Redis Cache 정책 업데이트 초안

작성일: 2026-06-10

## 목적

Wiki에 남아 있는 Backend DB 원장화 기준과 claim output 원장화 기준을 폐기하고 다음 정책으로 통일합니다.

- 인증 identity 원장: Ory Kratos
- 권한/관계 원장: Ory Keto
- OAuth/OIDC 원장: Ory Hydra
- Backend DB: Ory에 저장되지 않거나 Ory API로 필요한 방식의 조회가 불가능한 데이터의 read model
- Redis: Ory 또는 허용된 read model의 성능 cache/mirror
- Front/API 전송: Ory에서 Redis cache로 웜업된 데이터를 Backend가 cursor 기반 API로 제공

## Wiki 검색 결과

Gitea Wiki를 조회한 결과, 다음 페이지는 현재 정책과 충돌하는 문구가 있어 업데이트가 필요합니다.

| Wiki page | 확인된 문제 | 권장 조치 |
| --- | --- | --- |
| `Data SoT Architecture Policy` | Backend DB 중심 admin list read path와 async write-behind를 기본 write path로 설명합니다. | 아래 대체 본문으로 교체합니다. |
| `[Architecture] Kratos SoT Consolidation` | 관리 read-model의 원장을 Backend DB로 설명하고 Kratos 데이터를 DB에 복제한다고 설명합니다. | 아래 대체 본문으로 교체합니다. |
| `tenant-policy.-` | Wiki page 조회 이름이 불안정해 직접 본문 확인은 실패했습니다. 로컬 `docs/tenant-policy.md`와 같은 내용이면 Backend DB 원장화 문구를 삭제해야 합니다. | `docs/tenant-policy.md` 변경본 기준으로 동기화합니다. |
| `유저-그룹-및-테넌트-통합-권한-정책` | Wiki page 조회 이름이 불안정해 직접 본문 확인은 실패했습니다. 로컬 `docs/tenant-usergroup-policy.md`와 같은 내용이면 Backend DB 주도 consent 문구를 삭제해야 합니다. | `docs/tenant-usergroup-policy.md` 변경본 기준으로 동기화합니다. |

## `Data SoT Architecture Policy` 대체 본문

```md
# Baron SSO Data SoT Architecture Policy

## 1. Core Principle: Ory Stack is the Single Source of Truth

Baron SSO에서 인증 identity, 권한 관계, OAuth/OIDC 위임의 원장은 Ory Stack입니다.

- Identity/profile 인증 원장: Ory Kratos
- Authorization/ReBAC 원장: Ory Keto
- OAuth/OIDC client, consent, token state 원장: Ory Hydra

Backend DB는 Ory를 대체하는 원장이 아닙니다. Ory에 저장되지 않거나 Ory API로 필요한 방식의 조회가 불가능한 업무 데이터의 read model, 감사 로그, 처리 상태, 성능 cache 보조 데이터만 허용합니다.

Ory에서 Redis cache로 웜업된 데이터는 Backend가 cursor 기반 API로 front 또는 외부 API에 제공합니다. frontend는 Redis나 Backend DB 복제본을 원장처럼 직접 소비하지 않습니다.

## 2. Component Policies

### 2.1 Identity & User Profile

- Ory Kratos identity가 subject, credentials, recovery/verification address, 인증 식별자의 원장입니다.
- Kratos identity 변경은 Backend의 중앙 `IdentityWriteService`를 경유해야 합니다.
- Redis identity mirror는 빠른 단건/목록/검색 조회를 위한 cache입니다. stale 가능성을 API 응답에 드러내야 합니다.
- Backend DB `users`는 Ory에 저장되지 않거나 Ory에서 필요한 방식으로 조회할 수 없는 Baron 운영 데이터의 read model입니다.

### 2.2 Permissions & Relationships

- 권한 판단과 관계 tuple의 원장은 Ory Keto입니다.
- Backend DB는 relation command outbox, 처리 상태, 조직 표시/검색에 필요한 read model을 보관할 수 있습니다.
- 보안상 중요한 권한 판정은 Backend DB metadata나 token claim만으로 수행하지 않고 Keto check를 거쳐야 합니다.

### 2.3 OAuth2 Clients & Sessions

- OAuth2 client, consent, token state의 프로토콜 원장은 Ory Hydra입니다.
- `client_consents` 같은 Backend read model은 Hydra가 제공하지 않는 조회 축을 보완하기 위한 모델입니다.
- client secret 원문처럼 Hydra가 해시만 보관하는 값은 재발급/운영 목적의 별도 보관 정책과 감사 로그를 가져야 합니다.

## 3. Data Flow & Synchronization Strategy

### 3.1 Write Path

1. 클라이언트 또는 운영 도구가 Backend API/CLI를 호출합니다.
2. Backend가 중앙 service를 통해 Ory API를 동기 호출합니다.
3. Ory write 성공 후 Ory ID로 재조회합니다.
4. Redis mirror를 갱신하거나 갱신 실패 시 `stale`/`failed` 상태를 기록합니다.
5. Ory에 저장되지 않거나 조회 불가능한 read model만 Backend DB에 갱신합니다.

### 3.2 Read Path

- Self context: Ory session/token 또는 Ory API를 기준으로 검증합니다.
- Admin/list context: Backend가 Redis mirror와 허용된 read model을 조합해 cursor 기반 API로 제공합니다.
- API response는 `identityTotal`, read model count, mirror status를 구분해야 합니다.

### 3.3 Conflict Resolution

불일치가 발견되면 Ory Stack의 데이터를 기준으로 Redis mirror와 Backend read model을 보정합니다. Backend read model이나 token claim assembly 결과를 Ory보다 우선하는 근거로 사용하지 않습니다.
```

## `[Architecture] Kratos SoT Consolidation` 대체 본문

```md
# [Architecture] Kratos SoT Consolidation & Redis Cache Strategy

이 문서는 Kratos identity SSOT와 Redis cache 전략을 정의합니다.

## 1. Identity Source

- 원장: Ory Kratos identity
- 중앙 write path: Backend `IdentityWriteService`
- Redis: identity mirror/cache
- Backend DB: Ory에 저장되지 않거나 Ory API로 필요한 조회가 불가능한 Baron 운영 데이터의 read model

`role`, `tenant_id`, 조직 표시 metadata를 Kratos traits에 무제한 추가하거나 Backend DB를 별도 identity 원장으로 삼지 않습니다.

## 2. Redis Cache Strategy

Redis는 성능 cache입니다. Ory에서 Redis cache로 웜업된 데이터는 Backend가 cursor 기반 API로 front 또는 외부 API에 제공합니다.

- `identity:mirror:{identityID}`: Kratos identity summary 단건 cache
- `identity:index:*`: Backend cursor API용 identity 목록/검색 index
- `identity:mirror:state`: mirror 상태, count, last error

Cache miss가 발생한 단건 조회는 Kratos `GetIdentity`로 fallback하고, 성공 시 Redis를 갱신합니다. 목록 조회는 mirror 상태가 `ready`가 아니면 API 응답에 경고 상태를 포함합니다.

## 3. Write Path Guard

Kratos identity 변경은 `IdentityWriteService` 경유를 강제합니다.

- `backend/internal/handler/dev_handler.go`: RP custom claim 관련 잔여 Kratos traits sync도 중앙 service를 경유합니다.
- `backend/cmd/adminctl/worksmobile_sync.go`: WORKS 기준 Baron 보정도 중앙 service를 경유합니다.
- Kratos Admin API나 Kratos DB 직접 수정은 maintenance guard와 mirror stale 표시 없이 금지합니다.

## 4. Read Path Guard

Admin/list 화면과 조직도/picker는 Backend cursor API 또는 Redis orgchart snapshot API를 사용합니다. `limit=5000&offset=0` 같은 단일 대량 offset 조회는 신규 구현에서 금지합니다.

## 5. Allowed Backend Data

Backend DB에 허용되는 데이터는 다음 범위입니다.

- Ory에 저장되지 않는 외부 연동 상태
- Ory API로 필요한 조회 축이 제공되지 않는 운영 read model
- 감사 로그와 처리 상태
- token/userinfo claim assembly에 필요한 RP 범위 metadata

이 데이터는 Ory SSOT를 대체하지 않습니다.
```