공통 계약 (Canonical Contract)

공통 계약 (Canonical Contract)

1) 인증/세션

• Edge 인증은 Pomerium 단일 경로를 사용한다.
• 앱 직접 로그인은 관리자 콘솔(예: Keycloak Admin) 외에는 금지한다.
• 로그인 실패 시 각 솔루션은 직접 에러를 띄우지 않고 포털 로그인 경로로 리다이렉트한다.

2) 주체 식별자

• canonical principal key:
  • subject_key (예: entra:<object-id>)
  • subject_id (FractalOps 내부 안정 ID)
• principal type:
  • human | ai만 허용
• 비정규 별칭(bot, agent, user)은 허용하지 않는다.

3) 권한 표현

• 권한 원천은 /org/... group path + realm role 조합
• 정책 엔진 입력은 canonical 필드만 사용:
  • principalType, groupPath, operation, resourceRef
• operation은 create | delete만 허용

4) 프로비저닝 모드

• scim: 표준 SCIM 지원 솔루션
• jit: 로그인/접근 시점 API 기반 즉시 생성
• poll: 비표준 솔루션 증분 동기화(meta.lastModified 커서)
• project: 프로젝트 단위 권한/리소스 동기화

5) 시크릿/토큰

• 모든 런타임 시크릿은 OpenBao 우선 조회
• env 평문은 bootstrap/운영 전환용 입력으로만 사용
• 토큰 회전은 OpenBao 원문 값을 노출하지 않는 rotation envelope 계약으로 추적한다.
• 회전 envelope은 owner agent, EOS/controller, active generation, consumer, activation step, fingerprint를 기록한다.
• connector audit는 민감 토큰이 raw secret만 갖고 envelope 없이 운용되는 상태를 실패로 처리한다.

6) SSOT 우선순위

1. operation payload / explicit input
2. OpenBao scope secret
3. env file
4. default value (개발모드 한정)

7) 관측/감사

• 모든 동기화/실패는 audit event로 남긴다.
• unresolved 상태(예: githubUserId 누락)는 pending으로 분류하고 reason code를 강제한다.