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

인증 보안

액세스 토큰 메커니즘

ChainStream은 OAuth 2.0 기반 인증 메커니즘을 사용합니다. Client ID와 Client Secret으로 JWT 액세스 토큰을 생성하여 API 인증에 사용합니다. 인증 흐름: 인증 정보 사양
항목사양
Client ID애플리케이션 고유 식별자
Client Secret64자 랜덤 문자열
Access TokenJWT 형식, 만료 시간 및 스코프 포함
토큰 유효기간24시간

액세스 토큰 생성

import { AuthenticationClient } from 'auth0';

const auth0Client = new AuthenticationClient({
  domain: 'dex.asia.auth.chainstream.io',
  clientId: process.env.CHAINSTREAM_CLIENT_ID,
  clientSecret: process.env.CHAINSTREAM_CLIENT_SECRET
});

const { data } = await auth0Client.oauth.clientCredentialsGrant({
  audience: 'https://api.dex.chainstream.io'
});

const accessToken = data.access_token;

인증 정보 보안

저장 요구사항
Client Secret은 ChainStream 서비스에 접근하기 위한 핵심 인증 정보입니다. 유출 시 서비스 남용과 재정적 손실이 발생할 수 있습니다.
저장 방식보안 수준비고
환경 변수✅ 권장버전 관리에 포함하지 않음
시크릿 관리 서비스✅ 최선AWS Secrets Manager, HashiCorp Vault 등
설정 파일⚠️ 주의반드시 .gitignore에 추가
하드코딩❌ 금지유출 위험 높음

코드 예시

// ❌ 위험: 하드코딩된 인증 정보
const clientId = "your_client_id";
const clientSecret = "your_secret";

// ❌ 위험: 버전 관리에 커밋
// config.json: { "client_id": "...", "client_secret": "..." }

// ✅ 안전: 환경 변수 사용
const clientId = process.env.CHAINSTREAM_CLIENT_ID;
const clientSecret = process.env.CHAINSTREAM_CLIENT_SECRET;

// ✅ 안전: 시크릿 관리 서비스 사용
const credentials = await secretsManager.getSecret('chainstream-credentials');

멀티 앱 관리

환경 및 서비스별로 별도의 App을 생성하는 것을 권장합니다:
용도권장 App 이름설명
프로덕션prod-main프로덕션 워크로드
테스트test-dev개발 및 테스트
CI/CDci-pipeline자동화 테스트
모니터링monitoring모니터링 및 알림

전송 보안

TLS 요구사항

항목요구사항
최소 버전TLS 1.2
권장 버전TLS 1.3
인증서 검증반드시 활성화
미지원HTTP, TLS 1.0/1.1

인증서 검증

프로덕션 환경에서 인증서 검증을 건너뛰지 마세요. 이는 중간자 공격(MITM) 위험에 노출됩니다.
// ❌ 위험: 인증서 검증 건너뛰기
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

// ✅ 안전: 정상 인증서 검증 (기본 동작)
const response = await fetch('https://api.chainstream.io/v1/...');

Webhook 보안

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

서명 검증

Webhook 메시지를 수신하면 Webhook Secret을 사용하여 서명을 검증하여 메시지가 ChainStream에서 발송되었으며 변조되지 않았음을 확인해야 합니다.
항목설명
알고리즘HMAC-SHA256
Webhook Secret (Dashboard에서 설정)
서명 헤더X-Webhook-Signature

검증 예시

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express 미들웨어 예시
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Webhook 메시지 처리
  console.log('Received webhook:', req.body);
  res.status(200).send('OK');
});

Webhook Secret 교체

Webhook Secret을 교체하려면:
1

새 Secret 생성

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

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

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

서명 검증 확인

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

사용량 모니터링

메트릭스 대시보드

Dashboard의 Metrics 패널에서 API 및 WebSocket 호출 통계를 확인할 수 있습니다:
메트릭설명
요청 IP소스 IP 주소
User Agent클라이언트 식별자
상태 코드HTTP 상태 코드
지연 시간요청 응답 시간
소비 Unit해당 요청이 소비한 사용량 단위
총 사용량누적 소비 사용량

차트 데이터

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

보안 모니터링

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

IP 화이트리스트

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

일반적인 공격 대응

중간자 공격

공격 방식: 공격자가 클라이언트와 서버 간 통신을 가로챕니다. 대응 조치:
조치설명
HTTPS 강제TLS 1.2+ 만 지원
인증서 검증인증서 검증 반드시 활성화
HSTSHTTPS 연결 강제

인젝션 공격

공격 방식: 공격자가 악의적인 입력 데이터를 통해 비인가 작업을 시도합니다. 대응 조치:
조치설명
입력 검증엄격한 파라미터 타입 검사
파라미터화 쿼리SQL/NoSQL 인젝션 방지
출력 인코딩XSS 방지

인증 정보 유출 대응

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

즉시 App 삭제

Dashboard → Apps → App 선택 → 삭제
2

새 App 생성

Dashboard → Apps → 새 App 생성
3

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

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

메트릭스 확인

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

보안 관행 검토

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

보안 오류 코드

인증 관련

오류 코드HTTP 상태설명
UNAUTHORIZED401인증 정보 없음
EXPIRED_TOKEN401Access Token 만료
INVALID_TOKEN401Access Token 무효
INVALID_CREDENTIALS401Client ID 또는 Secret 오류

접근 제어 관련

오류 코드HTTP 상태설명
FORBIDDEN403권한 없음 또는 할당량 소진
RATE_LIMITED429요청 빈도 초과
INSUFFICIENT_SCOPE403토큰 권한 부족

Webhook 관련

오류 코드설명
INVALID_SIGNATUREWebhook 서명 검증 실패
MISSING_SIGNATURE서명 헤더 누락

오류 응답 예시

{
  "error": {
    "code": "EXPIRED_TOKEN",
    "message": "Access token has expired",
    "details": {
      "expired_at": "2024-01-15T10:30:00Z"
    }
  }
}

보안 구성 체크리스트

기본 구성 (필수)

  • 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 구성 및 사용법