# 외부 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]
```

## 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 처리해야 합니다.