최종 업데이트: 2026년 2월 | 버전: v2.0
인증 보안
액세스 토큰 메커니즘
ChainStream은 OAuth 2.0 기반 인증 메커니즘을 사용합니다. Client ID와 Client Secret으로 JWT 액세스 토큰을 생성하여 API 인증에 사용합니다. 인증 흐름: 인증 정보 사양| 항목 | 사양 |
|---|---|
| Client ID | 애플리케이션 고유 식별자 |
| Client Secret | 64자 랜덤 문자열 |
| Access Token | JWT 형식, 만료 시간 및 스코프 포함 |
| 토큰 유효기간 | 24시간 |
액세스 토큰 생성
인증 정보 보안
저장 요구사항| 저장 방식 | 보안 수준 | 비고 |
|---|---|---|
| 환경 변수 | ✅ 권장 | 버전 관리에 포함하지 않음 |
| 시크릿 관리 서비스 | ✅ 최선 | AWS Secrets Manager, HashiCorp Vault 등 |
| 설정 파일 | ⚠️ 주의 | 반드시 .gitignore에 추가 |
| 하드코딩 | ❌ 금지 | 유출 위험 높음 |
코드 예시
멀티 앱 관리
환경 및 서비스별로 별도의 App을 생성하는 것을 권장합니다:| 용도 | 권장 App 이름 | 설명 |
|---|---|---|
| 프로덕션 | prod-main | 프로덕션 워크로드 |
| 테스트 | test-dev | 개발 및 테스트 |
| CI/CD | ci-pipeline | 자동화 테스트 |
| 모니터링 | monitoring | 모니터링 및 알림 |
전송 보안
TLS 요구사항
| 항목 | 요구사항 |
|---|---|
| 최소 버전 | TLS 1.2 |
| 권장 버전 | TLS 1.3 |
| 인증서 검증 | 반드시 활성화 |
| 미지원 | HTTP, TLS 1.0/1.1 |
인증서 검증
Webhook 보안
Webhook 메시지는 서명 메커니즘을 사용하여 메시지 출처의 신뢰성을 보장합니다.서명 검증
Webhook 메시지를 수신하면 Webhook Secret을 사용하여 서명을 검증하여 메시지가 ChainStream에서 발송되었으며 변조되지 않았음을 확인해야 합니다.| 항목 | 설명 |
|---|---|
| 알고리즘 | HMAC-SHA256 |
| 키 | Webhook Secret (Dashboard에서 설정) |
| 서명 헤더 | X-Webhook-Signature |
검증 예시
Webhook Secret 교체
Webhook Secret을 교체하려면:사용량 모니터링
메트릭스 대시보드
Dashboard의 Metrics 패널에서 API 및 WebSocket 호출 통계를 확인할 수 있습니다:| 메트릭 | 설명 |
|---|---|
| 요청 IP | 소스 IP 주소 |
| User Agent | 클라이언트 식별자 |
| 상태 코드 | HTTP 상태 코드 |
| 지연 시간 | 요청 응답 시간 |
| 소비 Unit | 해당 요청이 소비한 사용량 단위 |
| 총 사용량 | 누적 소비 사용량 |
차트 데이터
Metrics 패널은 다양한 시간 차원의 차트를 제공합니다:- 시간별 — 최근 24시간 호출 추이 확인
- 일별 — 최근 30일 호출 추이 확인
- 월별 — 월별 역사 통계 확인
보안 모니터링
🚧 준비 중 — 보안 모니터링 기능이 개발 중이며 곧 제공될 예정입니다.
- 이상 탐지 — 인증 실패 급증, 비정상 지역 등 자동 감지
- 알림 통지 — 이메일 및 Webhook 알림
- 자동 보호 — 임시 차단, 요청 제한 등
IP 화이트리스트
🚧 준비 중 — IP 화이트리스트 기능이 개발 중이며 곧 제공될 예정입니다.
- 단일 IP 설정 (예:
203.0.113.50) - IP 범위 설정 (예:
203.0.113.0/24) - 다중 IP (쉼표 구분)
일반적인 공격 대응
중간자 공격
공격 방식: 공격자가 클라이언트와 서버 간 통신을 가로챕니다. 대응 조치:| 조치 | 설명 |
|---|---|
| HTTPS 강제 | TLS 1.2+ 만 지원 |
| 인증서 검증 | 인증서 검증 반드시 활성화 |
| HSTS | HTTPS 연결 강제 |
인젝션 공격
공격 방식: 공격자가 악의적인 입력 데이터를 통해 비인가 작업을 시도합니다. 대응 조치:| 조치 | 설명 |
|---|---|
| 입력 검증 | 엄격한 파라미터 타입 검사 |
| 파라미터화 쿼리 | SQL/NoSQL 인젝션 방지 |
| 출력 인코딩 | XSS 방지 |
인증 정보 유출 대응
Client Secret 유출이 의심되면 즉시 다음 단계를 실행하세요:보안 오류 코드
인증 관련
| 오류 코드 | HTTP 상태 | 설명 |
|---|---|---|
UNAUTHORIZED | 401 | 인증 정보 없음 |
EXPIRED_TOKEN | 401 | Access Token 만료 |
INVALID_TOKEN | 401 | Access Token 무효 |
INVALID_CREDENTIALS | 401 | Client ID 또는 Secret 오류 |
접근 제어 관련
| 오류 코드 | HTTP 상태 | 설명 |
|---|---|---|
FORBIDDEN | 403 | 권한 없음 또는 할당량 소진 |
RATE_LIMITED | 429 | 요청 빈도 초과 |
INSUFFICIENT_SCOPE | 403 | 토큰 권한 부족 |
Webhook 관련
| 오류 코드 | 설명 |
|---|---|
INVALID_SIGNATURE | Webhook 서명 검증 실패 |
MISSING_SIGNATURE | 서명 헤더 누락 |
오류 응답 예시
보안 구성 체크리스트
기본 구성 (필수)
- 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 구성 및 사용법

