baron-sso/docs/rp-iam-integration-guide.md

외부 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합니다.

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를 제공하지 않은 것이므로 요청을 거부해야 합니다.

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