API Key 관리 원칙 (API Key Management Principles)

한 줄 정의

API Key 관리 원칙은 비밀값(Secret)을 소스코드와 완전히 격리하고, 최소 권한 및 다층 방어 기반으로 생성부터 로테이션, 유출 모니터링, 사고 대응에 이르기까지 비밀값의 전체 생명주기를 안전하게 통제하는 보안 워크플로우(Workflow)다.

하드코딩 절대 금지: API Key는 Git history, 클라이언트 사이드 번들, 로깅 시스템에 하드코딩 형태로 노출하지 않는다.
다층 방어(Defense in Depth)와 Zero Trust: 필요한 대상에게 최소 권한(Need-to-Know)만 부여하고, 로컬 .env 파일은 오직 개발 환경으로 제한하며 프로덕션 환경에서는 Secret Manager를 이용해 중앙 제어한다.
로테이션 및 자동화: 환경의 민감도에 따라 30일에서 180일 주기로 정기 교체(Rotation)를 수행하며, 무중단 로테이션 4단계 절차를 준수한다.
실시간 유출 탐지: Gitleaks, TruffleHog, GitGuardian 등의 탐지 엔진을 Git pre-commit hook 및 CI/CD 파이프라인에 주입하여 비밀값 노출을 상시 차단한다.
중앙화 관리 도구 도입: 클라우드 Secret Manager나 HashiCorp Vault 외에도, 현대적 DX와 E2EE(End-to-End Encryption)를 제공하는 오픈소스 Infisical을 도입해 Secret의 라이프사이클을 통제한다.

Need-to-Know (최소 권한): 필요한 사람과 시스템에게만 최소한의 권한 범위로 비밀값을 노출한다.
Defense in Depth (다층 방어): 네트워크, 호스트, 애플리케이션 및 비밀값 저장소 각각에 다중 가드레일을 쳐 한 계층이 무너지더라도 전체 인프라가 유출되는 사고를 방지한다.
Zero Trust (신뢰 배제): 내부망의 소속원이나 내부 인스턴스라 하더라도 평문 Key를 쉽게 확인할 수 없도록 암호화 격리한다.
Rotate Early, Rotate Often (정기 교체): 유출 가능성을 고려하여 정기적으로 교체 주기를 가지고 가며, 유출 의심 시 즉시 Revoke(폐기)한다.

🔴 위험 (하드코딩 금지): 소스코드에 하드코딩된 API Key는 봇의 실시간 깃허브 스캐닝 표적이 되며 Git 이력에 영구 박제된다.
🟡 주의 (로컬 개발 제한): .env 파일은 반드시 .gitignore에 등록하여 협업 브랜치에 올라가지 않도록 단속하고, 구조 템플릿 파일인 .env.example만 공유한다.
🟢 권장 (운영 및 배포):
- 클라우드 Secret Manager: KMS 암호화, IAM 기반 세밀한 접근 제어, 자동 로테이션 및 CloudTrail 등의 감사 로그 기록 연동을 사용한다. (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault 등)
- Dynamic Secrets (동적 자격증명): HashiCorp Vault나 Infisical을 통해 데이터베이스나 외부 서비스의 자격 증명을 일회성 임시 Lease 기반으로 생성 후 자동 폐기한다.
- Kubernetes Secret 개선: 기본 K8s Secret은 단순 base64 인코딩에 불과하므로, 외부 도구와 연동되는 Sealed Secrets 또는 External Secrets Operator(ESO) 조합을 사용해 보완한다.

보안 환경별 권장 로테이션 주기:
- 프로덕션 (높은 민감도): 30일 ~ 90일
- 프로덕션 (일반): 90일 ~ 180일
- 개발 및 스테이징: 180일 또는 프로젝트 종료 시 즉시 교체
무중단 로테이션 4단계:
1. 기존 Key의 유효 상태를 유지하면서 신규 Key 생성
2. 신규 발급된 Key를 애플리케이션 환경 변수로 배포
3. 모든 인프라 인스턴스가 신규 Key를 통해 정상 호출하는지 검증
4. 기존에 잔존하던 이전 Key 폐기 (Revoke)
보안 사고 대응 6단계 플레이북:
1. 유출 의심 즉시 해당 API Key의 Revoke (폐기) 집행
2. 시스템의 호출 로그(Audit log) 분석을 통해 유출 유입 시점 파악
3. API 권한 범위를 조사하여 접근 가능한 데이터/서비스 영향도 분석
4. 임시 Secret Manager를 통하여 신규 임시 Key 발급 및 배포
5. 포스트모템(사고 보고서) 작성 및 유출 원인 공유
6. Git pre-commit hook 설정 및 Secret Manager 완전 강제 등의 재발 방지책 강화

Frontend 노출 전면 불허: React, Vue, Next.js 등의 클라이언트 렌더링 코드에 외부 서버 사이드 API Key를 적재해 호출해서는 안 된다. 브라우저 개발자 도구를 통해 쉽게 탈취될 수 있다.
대체 솔루션:
- Backend Proxy: 클라이언트는 외부 Key를 쥐지 않고, 내부 백엔드 API 서버를 통하여 간접적으로 외부 API를 호출하게 한다. Key는 백엔드 서버의 메모리에만 상주한다.
- Edge Functions: Cloudflare Workers, Vercel Edge 등의 미들웨어 경량 서버에서 외부 API Key를 은닉하여 호출을 대행한다.
- 사용자별 JWT + Rate Limiting: 사용자 권한이 매핑된 JWT 토큰을 사용하여 인가받고, 백엔드 게이트웨이에서 분당 호출 한계(Rate Limiter)를 설정한다.
- 노출이 불가피한 키(예: 지도 API): 도메인 HTTP referrer 제한, IP 화이트리스팅, 일일 쿼타 캡 설정 및 정기 교체를 필수로 건다.

Infisical (추천): MIT 라이선스 기반 오픈소스로서 Self-hosted를 무료 지원하며, E2EE(End-to-End Encryption)를 보장하여 인프라 서버조차 원시 Secret 값을 직접 복호화해 볼 수 없는 Zero-Knowledge 보안을 제공한다. 개발자 경험(DX)이 뛰어나 CLI 연동과 K8s Operator 동기화가 용이하다.
HashiCorp Vault: 동적 Secret 및 다양한 온프레미스 인프라와 결합력이 우수하지만 아키텍처가 매우 무겁고 엔터프라이즈 비용이 높다.
클라우드 Secret Manager: 클라우드 인프라 내재화 수준이 높지만 멀티 클라우드 이식이 어렵고 호출 건당 비용이 누적된다.

로컬 개발 연동: .env 파일을 로컬에 수동 보관하지 않고, CLI에서 infisical run --env=dev -- npm run dev와 같이 런타임에 임시 환경 변수로 직접 주입하여 공유 누출을 예방한다.
CI/CD 파이프라인: GitHub Repository 설정에 수십 개의 비밀값을 일일이 저장하지 않고, secrets.INFISICAL_TOKEN 단 하나만 등록한 뒤 GitHub Action 실행 시점에 Infisical CLI를 통해 프로덕션 Secrets를 병렬로 안전하게 호출한다.
최소 권한 Key 분리: 하나의 마스터 Key로 스트라이프 결제, OpenAI API, 샌드그리드 이메일 발송을 모두 해결하지 않고, 각각 목적별로 생성한 Key로 격리하여 Stripe Key 유출 시 이메일 발송 권한이나 기타 인프라에는 영향이 없도록 조치한다.

로컬 Secret 로딩 속도 vs 보안 격리: Universal Auth를 이용해 런타임마다 Secret Manager 서버로부터 동적으로 복호화하여 비밀값을 받아오면 보안성은 향상되나, 네트워크 레이턴시가 발생하고 Secret Manager 장애 시 서버 기동이 실패하는 단점이 생긴다. 이를 위해 E2EE 로컬 복호화 캐시를 설정하는 이중 보안 가드레일 설계가 충돌 요인으로 논의된다.