baron_qa_write/docs/sso_guides/directory-api.md

Directory API Guide

정책 정본은 Integration Credential 및 Directory API 정책이다. 정확한 schema는 Backend OpenAPI를 따른다.

Credential 준비

1. AdminFront의 API Key 관리에서 Directory 연동 credential을 발급한다.
2. exact OperationID와 concrete Tenant subtree scope를 선택한다.
3. 만료일과 발급 사유를 기록한다.
4. secret은 발급 시 한 번만 안전하게 전달하고 log나 issue에 남기지 않는다.
5. 교체 후 이전 secret이 무효인지 확인한다.

/admin/*에 integration credential을 사용하지 않는다. interactive cookie/token과 한 요청에 혼합하지 않는다.

사용자 생성

요청 필드, credential 발급, idempotency, 오류 처리와 검증 절차는 외부 사용자 계정 생성 상세 가이드를 따른다.

• Endpoint: POST /api/v1/integrations/directory/users
• OperationID: directory.user.create
• credential scope 안의 concrete Tenant를 지정한다.
• identity, status, 허용 profile field만 보낸다.
• System Role, raw Keto relation, protected subtree를 payload로 주입하지 않는다.
• Idempotency-Key를 logical create 요청에 결속한다.

timeout 뒤 같은 payload와 idempotency key로 재시도한다. 다른 payload를 같은 key로 보내지 않는다.

Membership 변경

• Endpoint: PATCH /api/v1/integrations/directory/users/{userId}/memberships
• source와 destination이 credential scope에 포함되는지 확인한다.
• add와 remove 대상을 exact UUID로 전달한다.
• representative Tenant 변경이나 계정 삭제를 Membership 변경에 섞지 않는다.

오류 처리

• 401: secret, 만료, revoke 상태 확인
• 403: OperationID, exposure, Tenant scope 확인
• 409: idempotency fingerprint 또는 Membership invariant 확인
• 422: field와 business validation 확인
• 503: 원장/readiness 장애이므로 사용자를 없다고 처리하지 않음

오류 뒤 새 사용자를 임의 생성하기 전에 기존 idempotency 결과와 대상 identity를 조회한다.

운영 종료

1. acceptance용 임시 사용자와 Membership을 명시적으로 정리한다.
2. 임시 credential을 revoke한다.
3. revoked secret으로 호출이 거부되는지 확인한다.
4. audit에서 OperationID, actor, Tenant, 결과가 기록되고 secret이 없는지 확인한다.

조직 조회 연동은 Org Context API Guide를 따른다.

한맥가족의 기존 사용자 사번·이름·전화번호 수정은 별도 내부 인사 사용자 정보 수정 가이드를 따릅니다. 일반 Directory 키의 접근 범위는 바뀌지 않습니다.