메인 콘텐츠로 건너뛰기
ChainStream은 API 접근을 보호하기 위해 다층 보안 메커니즘을 사용합니다. 이 문서에서는 API 보안 모범 사례, 일반적인 위협 대응, 보안 구성 가이드라인을 다룹니다.
최종 업데이트: 2026년 2월 | 버전: v2.0

인증 보안

액세스 토큰 메커니즘

ChainStream은 OAuth 2.0 기반 인증 메커니즘을 사용합니다. Client ID와 Client Secret으로 JWT 액세스 토큰을 생성하여 API 인증에 사용합니다. 인증 흐름: 인증 정보 사양

액세스 토큰 생성

인증 정보 보안

저장 요구사항
Client Secret은 ChainStream 서비스에 접근하기 위한 핵심 인증 정보입니다. 유출 시 서비스 남용과 재정적 손실이 발생할 수 있습니다.

코드 예시

멀티 앱 관리

환경 및 서비스별로 별도의 App을 생성하는 것을 권장합니다:

전송 보안

TLS 요구사항

인증서 검증

프로덕션 환경에서 인증서 검증을 건너뛰지 마세요. 이는 중간자 공격(MITM) 위험에 노출됩니다.

Webhook 보안

Webhook 메시지는 서명 메커니즘을 사용하여 메시지 출처의 신뢰성을 보장합니다.

서명 검증

Webhook 메시지를 수신하면 Webhook Secret을 사용하여 서명을 검증하여 메시지가 ChainStream에서 발송되었으며 변조되지 않았음을 확인해야 합니다.

검증 예시

Webhook Secret 교체

Webhook Secret을 교체하려면:
1

새 Secret 생성

Dashboard → Webhooks → 엔드포인트 선택 → Secret 교체
2

애플리케이션 설정 업데이트

애플리케이션에서 새 Webhook Secret으로 업데이트
3

서명 검증 확인

새 Secret으로 서명이 올바르게 검증되는지 확인

사용량 모니터링

메트릭스 대시보드

Dashboard의 Metrics 패널에서 API 및 WebSocket 호출 통계를 확인할 수 있습니다:

차트 데이터

Metrics 패널은 다양한 시간 차원의 차트를 제공합니다:
  • 시간별 — 최근 24시간 호출 추이 확인
  • 일별 — 최근 30일 호출 추이 확인
  • 월별 — 월별 역사 통계 확인
확인 경로: Dashboard → Metrics

보안 모니터링

🚧 준비 중 — 보안 모니터링 기능이 개발 중이며 곧 제공될 예정입니다.
제공 예정 기능:
  • 이상 탐지 — 인증 실패 급증, 비정상 지역 등 자동 감지
  • 알림 통지 — 이메일 및 Webhook 알림
  • 자동 보호 — 임시 차단, 요청 제한 등

IP 화이트리스트

🚧 준비 중 — IP 화이트리스트 기능이 개발 중이며 곧 제공될 예정입니다.
제공 예정 기능:
  • 단일 IP 설정 (예: 203.0.113.50)
  • IP 범위 설정 (예: 203.0.113.0/24)
  • 다중 IP (쉼표 구분)

일반적인 공격 대응

중간자 공격

공격 방식: 공격자가 클라이언트와 서버 간 통신을 가로챕니다. 대응 조치:

인젝션 공격

공격 방식: 공격자가 악의적인 입력 데이터를 통해 비인가 작업을 시도합니다. 대응 조치:

인증 정보 유출 대응

Client Secret 유출이 의심되면 즉시 다음 단계를 실행하세요:
1

즉시 App 삭제

Dashboard → Apps → App 선택 → 삭제
2

새 App 생성

Dashboard → Apps → 새 App 생성
3

애플리케이션 설정 업데이트

이전 인증 정보를 사용하는 모든 애플리케이션에서 새 Client ID와 Secret으로 업데이트
4

메트릭스 확인

Dashboard → Metrics → 비정상 호출 확인
5

보안 관행 검토

유출 원인 조사 및 보안 조치 개선

보안 오류 코드

인증 관련

접근 제어 관련

Webhook 관련

오류 응답 예시


보안 구성 체크리스트

기본 구성 (필수)

  • API 접근에 HTTPS 사용
  • Client ID와 Client Secret을 환경 변수 또는 시크릿 관리 서비스에 저장
  • 인증 정보를 코드 저장소에 커밋하지 않음
  • 프로덕션/테스트 환경에 서로 다른 App 사용
  • Webhook 서명 올바르게 검증

고급 구성 (권장)

  • 시크릿 관리 서비스 연동 (AWS Secrets Manager / HashiCorp Vault)
  • Metrics 대시보드에서 호출 통계 정기 확인
  • 서비스별로 별도 App 생성

엔터프라이즈 구성 (선택)

  • SIEM 시스템 연동으로 로그 분석
  • 보안 인시던트 대응 프로세스 수립

FAQ

즉시 Dashboard에 로그인하여 해당 App을 삭제하고, 새 App을 생성한 후 해당 인증 정보를 사용하는 모든 애플리케이션 설정을 업데이트하세요. 인증 정보 유출 대응을 참고하세요.
Access Token은 24시간 동안 유효합니다. 권장 사항:
  1. 토큰 캐싱 — 유효 기간 내 동일 토큰 재사용
  2. 사전 갱신 — 만료 약 1시간 전에 토큰 갱신
  3. 오류 재시도 — 401 오류 수신 시 자동으로 새 토큰 획득
Dashboard → Metrics에 로그인하면 요청 IP, 상태 코드, 지연 시간, 소비 Unit, 시간 차원 차트를 확인할 수 있습니다.
일반적인 원인:
  1. Secret 불일치 — 올바른 Webhook Secret을 사용하고 있는지 확인
  2. 페이로드 처리 오류 — 서명 계산에 원본 JSON 문자열을 사용하고 있는지 확인
  3. 서명 헤더 누락 — 요청 헤더에 X-Webhook-Signature가 포함되어 있는지 확인
네. 서로 다른 환경(프로덕션/테스트)과 서비스별로 별도 App을 생성하여 관리 및 문제 해결을 용이하게 하는 것을 권장합니다.

관련 문서

인증

인증 및 인증 정보 관리

데이터 프라이버시

데이터 프라이버시 정책

오류 코드

전체 오류 코드 목록

Webhook 기본 개념

Webhook 구성 및 사용법