HBSA240_External Integrations (연동 자격증명)
(Hereby) 시스템 관리 > [[HBSA200]] > External Integrations
| 앱 | System Admin (포트 4100) |
| 부모 화면 | [[HBSA200]] |
| 대상 사용자 | 플랫폼 운영자(OPERATOR) |
| 프로토타입 | TBU |
| 관련 정책 | [[POL_권한(RBAC)]] |
| Status | draft (코드 기반 — 라이브 실사 불가: dev 라우트 AccessDenied 격리, 2026-08-25 확인) |
| Owner | 카나 |
개요
조직별 외부 연동 자격증명(대표: hereby Sign API 키·시크릿·웹훅 상태 시크릿)을 관리한다. redesign에서 암호화 키를 API만 보유 — 콘솔은 시크릿 원문을 TLS로 보내기만 하고 응답은 항상 마스킹값(AK_liv...7890)만 받는다. 웹훅 시크릿 생성 시에만 원문이 1회 반환된다.
문서 히스토리
| 날짜 | 작성자 | 팀 | 변경 내용 |
|---|---|---|---|
| 2026-08-25 | 카나 | 콸 | 최초 작성 (redesign PR #583 코드 census 기반, 라이브 미실사) |
Data I/O
Client → Server
| 액션 | 콘솔 REST | systemProcedure |
|---|---|---|
| 목록 | GET /api/integrations (fan-out, provider 필터) | systemIntegrationCredentials |
| 생성 | POST /api/integrations | systemCreateIntegrationCredential |
| 수정 | PUT /api/integrations/:id | systemUpdateIntegrationCredential |
| 웹훅 시크릿 생성 | POST .../webhook-secret | systemGenerateIntegrationWebhookSecret |
| 웹훅 시크릿 폐기 | POST .../webhook-secret/revoke | systemRevokeIntegrationWebhookSecret |
| 삭제 | DELETE /api/integrations/:id | systemDeleteIntegrationCredential |
Server → Client
| 변수 | 소스 | 비고 |
|---|---|---|
integrations[] | systemIntegrationCredentials | organization/name/provider/openApiUrl/maskedApiKey/maskedApiSecret/webhookSecretStatus/status/lastUsedAt/updatedAt |
generatedWebhookSecret | generate 응답 | 원문 1회만 |
코드 근거: tabs/integrations.html, server/routes/integrations.ts.
화면 플로우
메인 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 화면 진입 조건 | - | activeTab === 'integrations' | - | |
| 01 | 초기 상태 | Output | "External Integrations: {n}" + "refresh" + "+ Add Credential" | - | |
| 10 | 자격증명 테이블 | List | [List] 컬럼 organization/name/external type/open api url/api key/api secret/status secret/status/last used/updated/actions | integrations | key/secret은 마스킹만 |
| 11 | ㄴ status secret | Badge | active=green ACTIVE / else gray INACTIVE | webhookSecretStatus | 읽기 배지 |
| 12 | ㄴ status | Toggle | ACTIVE/INACTIVE 배지 클릭 → toggleIntegration(item) | systemUpdateIntegrationCredential | |
| 13 | ㄴ actions | Button | "edit" → 모달 / "delete" → ask "Delete this credential?"(danger) → deleteIntegration() | systemDeleteIntegrationCredential | |
| 10-E | ㄴ Empty | Text | "No external integration credentials configured." | - | |
| 20 | 값 없음 처리 | - | organizationName 없으면 "—", 타임스탬프 formatTimestamp | - |
서브 화면 / 모달 사양표
Credential 모달 (Add / Edit)
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 노출 조건 | - | showIntegrationForm. 타이틀 create "Add External Credential" / edit "Edit External Credential" | - | |
| 10 | ORGANIZATION | Dropdown/Output | create: "select..." + 전 조직 / edit: 읽기 표시 | organizationId | edit 시 변경 불가 |
| 20 | NAME | Input Box | "NAME *"(placeholder "hereby production", max 100) | name | |
| 30 | EXTERNAL TYPE | Dropdown | integrationProviders 목록 | provider | 값 목록 TBU(app.ts) |
| 40 | OPEN API URL | Input Box | "OPEN API URL *"(placeholder "{hereby Sign endpoint}/api/contract") 안내 "hereby Sign 엔드포인트 + /api/contract 형태로 입력하세요." | openApiUrl | |
| 50 | STATUS | Dropdown | active/inactive | status | |
| 60 | API KEY | Input Box | "API KEY *". create 필수, edit "leave blank to keep current key" + 현재 마스킹 표시 | apiKey (원문 TLS) | |
| 70 | API SECRET | Input Box | "API SECRET *". create 필수, edit "leave blank to keep current secret" + 현재 마스킹 표시 | apiSecret (원문 TLS) | |
| 80 | STATUS SECRET(edit 전용) | Button | "Generate"/"Regenerate" → generateIntegrationWebhookSecret() / "Revoke" → ask "Revoke this status secret? Sign webhook calls using it will be rejected."(danger) | systemGenerate/RevokeIntegrationWebhookSecret | 안내 "생성한 Status Secret을 hereby Sign Admin의 비밀키에 입력하세요." |
| 81 | ㄴ 생성 원문 | Output | 생성 시 amber 박스: "Copy this secret now and save it in hereby Sign Admin. It will not be shown again." + Copy 버튼(성공 "Copied") | generatedWebhookSecret | 원문 1회만 |
| 90 | 제출 | Button | "Save" → saveIntegration(). 에러 red 배너(integrationFormError) | - |
권한 / 상태 요약
| 시나리오 | 트리거 | 결과 | 비고 |
|---|---|---|---|
case01 [생성] | Add | DB에 ciphertext(v1:…) 저장, 응답 마스킹 | audit input apiKey=[REDACTED] |
case02 [웹훅 생성] | Generate | 원문 1회 표시 후 마스킹 | 재표시 불가 |
case03 [잘못된 provider] | 검증 | 400 |
OQ
integrationProviders값/라벨 목록 =src/app.ts미확인 TBU- webhookSecretStatus vs status 의미 구분 세부 = TBU