시크릿 키 관리

시크릿 키는 상점의 결제를 승인·취소·조회할 수 있는 자격증명이에요. 비밀번호와 같은 수준으로 다뤄야 해요. 시크릿 키가 유출되면 제3자가 상점 명의로 결제를 승인하거나 취소할 수 있어요.

• 소스 코드에 하드코딩: 비공개 저장소라도 안 돼요. 클론·포크되면 추적할 수 없고, 한 번 커밋되면 히스토리에 남아요.
• 클라이언트·앱에 포함: 디컴파일(역분석)을 통해 쉽게 탈취될 수 있어요.
• URL 쿼리스트링에 포함: 액세스 로그·리퍼러·브라우저 히스토리에 그대로 남아요.
• 로그에 출력: 디버그 로그에 요청 헤더를 통째로 출력하는 코드가 흔한 유출 경로예요.
• 메신저·이메일로 공유: 평문 전송이에요. 개발자센터의 사용자 추가 기능으로 권한을 부여하고 각자 직접 조회하도록 하세요.
• 테스트·라이브 키 혼용: 테스트 환경에서는 테스트 키만 사용하세요. 라이브 키의 노출 위험을 줄일 수 있어요.

키는 애플리케이션 코드·설정 파일과 분리된 전용 시크릿 저장소(vault)에 두고, 실행 시점에 불러오는 방식을 권장해요. 아래는 대표적인 저장소별 연동 예시예요.

API 문서: AWS Secrets Manager API Reference

IAM 정책으로 결제 서버 역할만 읽도록 제한하세요.

API 문서: AWS KMS API Reference

설정 파일에 암호문으로 보관하고 실행 시점에 복호화하는 방식이에요.

API 문서: Google Cloud Secret Manager API

API 문서: Azure Key Vault REST API

API 문서: HashiCorp Vault API Docs

환경변수로 주입하고, 값이 담긴 파일은 반드시 .gitignore에 추가하세요. 이 방식은 차선책이에요. 환경변수는 프로세스 목록·크래시 덤프·에러 리포팅 도구에 노출될 수 있어요.

키를 읽을 수 있는 주체를 필요한 범위로 제한하세요.

• 결제를 담당하는 팀·서비스에만 권한을 부여하세요.
• 외주사를 통해 연동한다면 개발 종료 시점에 조회 권한을 회수하세요. 개발자센터 왼쪽 하단 사용자 추가하기에서 권한을 관리해요.
• 운영 서버 역할과 개발자 개인 계정의 권한을 분리하세요. 라이브 키를 직접 확인할 일은 거의 없어요.
• 퇴사·조직 이동 시 권한 회수를 정기 점검 항목에 포함하세요.

키 자체에 IP 제한을 걸어 호출 주체(호출 서버)를 제한하는 방법도 함께 사용하세요. API 키 접근 정책을 참고하세요.

사람이 조심하는 것만으로는 유출을 막기 어려워요. 자동 탐지 도구를 도입하도록 권고해요.

토스페이먼츠 키 패턴을 커스텀 룰로 추가하면 탐지율이 올라가요.

API 로그를 주기적으로 확인해 직접 보내지 않은 요청이 있는지 점검하세요.

수상한 호출을 발견했다면 아래 순서로 조치하세요.

1. 키를 재발급하고 신규 키를 서버에 반영·배포한 뒤 기존 키를 즉시 폐기해요.
2. API 키 접근 정책에 IP 제한을 등록해요.
3. 토스페이먼츠 고객센터(1544-7772, 평일 오전 8시~오후 7시) 또는 실시간 문의 채널로 연락해요.

토스페이먼츠에서도 유출된 키를 발견하면 조치 요청 메일을 발송해요. 다만 모든 유출을 발견할 수는 없으므로 상점에서 직접 관리하는 것이 기본이에요.

결제 연동을 중개사·연동 솔루션을 통해 하고 중개사 콘솔에 시크릿 키를 등록하는 구조라면, 키 전달 방법과 계약 종료 시 회수 기준을 호스팅사나 연동 솔루션을 이용할 때에서 확인하세요. 중개사 서버 IP는 API 키 접근 정책에 등록해 호출 주체를 제한하세요.

• 시크릿 키가 소스 코드·클라이언트·앱에 들어 있지 않아요.
• 전용 시크릿 저장소(vault)에 분리 보관해요.
• 평문으로 저장·전송하지 않아요.
• 키 접근 권한이 필요한 주체로 제한되어 있어요.
• 외주사·중개사 권한을 개발 종료 후 회수했어요.
• 시크릿 스캐닝이 커밋 또는 CI 단계에 붙어 있어요.
• 테스트·라이브 키를 분리해 사용해요.
• API 로그를 주기적으로 확인해요.
• API 키 접근 정책(IP 제한)을 등록해요.

• 시크릿 키 베스트 프랙티스