최종 업데이트: 2026년 2월 | 버전: v2.0
인증 보안
액세스 토큰 메커니즘
ChainStream은 OAuth 2.0 기반 인증 메커니즘을 사용합니다. Client ID와 Client Secret으로 JWT 액세스 토큰을 생성하여 API 인증에 사용합니다. 인증 흐름: 인증 정보 사양액세스 토큰 생성
인증 정보 보안
저장 요구사항코드 예시
멀티 앱 관리
환경 및 서비스별로 별도의 App을 생성하는 것을 권장합니다:전송 보안
TLS 요구사항
인증서 검증
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일 호출 추이 확인
- 월별 — 월별 역사 통계 확인
보안 모니터링
🚧 준비 중 — 보안 모니터링 기능이 개발 중이며 곧 제공될 예정입니다.
- 이상 탐지 — 인증 실패 급증, 비정상 지역 등 자동 감지
- 알림 통지 — 이메일 및 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
Client Secret이 유출되면 어떻게 해야 하나요?
Client Secret이 유출되면 어떻게 해야 하나요?
즉시 Dashboard에 로그인하여 해당 App을 삭제하고, 새 App을 생성한 후 해당 인증 정보를 사용하는 모든 애플리케이션 설정을 업데이트하세요. 인증 정보 유출 대응을 참고하세요.
Access Token이 만료되면 어떻게 하나요?
Access Token이 만료되면 어떻게 하나요?
Access Token은 24시간 동안 유효합니다. 권장 사항:
- 토큰 캐싱 — 유효 기간 내 동일 토큰 재사용
- 사전 갱신 — 만료 약 1시간 전에 토큰 갱신
- 오류 재시도 — 401 오류 수신 시 자동으로 새 토큰 획득
API 호출 통계는 어떻게 확인하나요?
API 호출 통계는 어떻게 확인하나요?
Dashboard → Metrics에 로그인하면 요청 IP, 상태 코드, 지연 시간, 소비 Unit, 시간 차원 차트를 확인할 수 있습니다.
Webhook 서명 검증 실패는 어떻게 해결하나요?
Webhook 서명 검증 실패는 어떻게 해결하나요?
일반적인 원인:
- Secret 불일치 — 올바른 Webhook Secret을 사용하고 있는지 확인
- 페이로드 처리 오류 — 서명 계산에 원본 JSON 문자열을 사용하고 있는지 확인
- 서명 헤더 누락 — 요청 헤더에
X-Webhook-Signature가 포함되어 있는지 확인
여러 개의 App을 만들 수 있나요?
여러 개의 App을 만들 수 있나요?
네. 서로 다른 환경(프로덕션/테스트)과 서비스별로 별도 App을 생성하여 관리 및 문제 해결을 용이하게 하는 것을 권장합니다.
관련 문서
인증
인증 및 인증 정보 관리
데이터 프라이버시
데이터 프라이버시 정책
오류 코드
전체 오류 코드 목록
Webhook 기본 개념
Webhook 구성 및 사용법

