CLAUDE CODE DEEP DIVE WORKSHOP · 시리즈 3/6
③ Admin Setup — 조직 단위로 배포·통제·감사하기
대량 배포, 자격증명 중앙관리, 네트워크 보안, 거버넌스, 비용 모니터링, SSO/ID 연동, 감사까지 관리자 관점의 챕터.
managed-settings.json 거버넌스 → 비용 모니터링 → SSO/SCIM → 감사까지, 관리자가 안전하고 추적 가능하게 운영하는 법.
핵심 9영역
| 영역 | 핵심 내용 |
|---|---|
| 1. 배포 전략 "500대에 설치하고 갱신하는 법" | 사내 npm 미러(Verdaccio/Nexus), Native 대량 배포, Windows MSI, Docker 이미지, 버전 고정, 폐쇄망(air-gapped) |
| 2. 공급자와 자격증명 "키를 나눠주지 않는 인증 설계" | Bedrock(Model access·IAM·SSO), Vertex AI, OAuth, PrivateLink/VPC Endpoint |
| 3. 🆕 Claude apps gateway "자체 호스팅 SSO 게이트웨이" | 자체 호스팅 게이트웨이로 요청 중간 단계 통제 — 최신 에디션 신설 파트 |
| 4. 네트워크와 보안 "사내망에서 안전하게 통과시키기" | 프록시, 내부 CA/DNS, 아웃바운드 검사, DLP Hook, 내부 MCP, Settings 3단 계층 |
| 5. 거버넌스와 정책 "개인이 못 바꾸는 것을 설계한다" | managed-settings.json, 권한 패턴, MCP allowlist, 감사 로그 Hook, 정책 배너 |
| 6. 모니터링과 비용 "쓰임을 보고, 비용을 귀속시키기" | OTel 관측성, /cost, 예산 알람, 자동 스로틀링, 사용자·팀별 비용 귀속 |
| 7. 신원·데이터·컴플라이언스 "감사관의 질문에 답하는 체계" | SSO(IAM Identity Center·Okta 등)·SCIM, CloudTrail, SOC 2, 데이터 취급 |
| 8. 트러블슈팅 "관리자에게 오는 문의의 지도" | 인증·네트워크 문제 진단 흐름 |
| 9. Recap & Labs | Lab: 내부 미러 / Bedrock SSO / managed-settings / DLP Hook / OTel |
실습 체크리스트
☐ MCP server allowlist로 허용 서버만 통과
☐ Audit log Hook으로 도구 사용 기록
☐ /cost + OTel로 사용량/비용 확인
☐ (관리자) SSO 연동 또는 PrivateLink 경유 호출
☐ Lab 1~3 중 하나 완주
🧪 핸즈온 랩 — 통제 가능한 Enterprise 배포
| Task | 내용 |
|---|---|
| 사내 npm 미러(Verdaccio) | 프라이빗 레지스트리로 배포 |
| Bedrock + SSO 자격증명 | 조직 인증 패턴 구성 |
| managed-settings 정책 강제 | 조직 표준을 전사 강제 배포 |
| DLP Hook | 시크릿 유출 차단 |
| OpenTelemetry | 사용량·비용 텔레메트리 맛보기 |
산출물 — managed-settings.json + DLP Hook + OTel 관측 구성
🧪 핸즈온 상세 실습 기록
1. 사내 npm 미러 (Verdaccio)
npm install -g verdaccio
verdaccio --listen 4873 > /tmp/verdaccio.log 2>&1 &
npm ping --registry http://localhost:4873 # PONG이면 정상
npm install -g @anthropic-ai/claude-code --registry http://localhost:4873
claude --version
pkill -f verdaccio프라이빗 레지스트리를 통해 배포 → 폐쇄망·버전 통제의 기초.
2. Bedrock + SSO 자격증명
# aws-config에 [sso-session corp] + [profile claude-workshop] 정의
# IAM 정책: bedrock:InvokeModel / InvokeModelWithResponseStream / ListFoundationModels
aws sso login --profile claude-workshop
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_PROFILE=claude-workshop
export AWS_REGION=ap-northeast-2
claude doctor # API Provider: AWS Bedrock 표시 확인3. managed-settings로 조직 정책 강제
sudo mkdir -p /etc/claude-code
sudo tee /etc/claude-code/managed-settings.json > /dev/null << 'EOF'
{
"permissions": {
"allow": ["Read(**)", "Grep", "Glob", "Bash(npm test:*)"],
"ask": ["Edit(**)", "Write(**)"],
"deny": ["Bash(curl:*)", "Read(.env)"]
}
}
EOF/etc/claude-code/의 managed-settings는 사용자 설정보다 우선해 조직 정책을 강제합니다.
4. DLP Hook — 시크릿 유출 차단
PreToolUse Hook으로 .env·API 토큰 같은 민감 패턴이 읽히거나 커밋되는 것을 차단. (실습용 가짜 값 DB_PASSWORD=lab-fake-… 사용)
5. OpenTelemetry 텔레메트리
OTel 환경변수로 사용량·비용을 관측 시스템으로 내보내는 맛보기. 조직 단위 비용 모니터링의 출발점.
📚 심화 · 비교 · 트러블슈팅 · FAQ
🏛️ 설정 우선순위 — 충돌하면 누가 이기나
| 우선순위 | 위치 | 용도 |
|---|---|---|
| 1 (최강) | /etc/claude-code/managed-settings.json | 조직 강제(관리자) |
| 2 | ~/.claude/settings.json | 사용자 개인 |
| 3 | .claude/settings.json | 프로젝트(팀 공유) |
| 4 | .claude/settings.local.json | 개인 오버라이드(미커밋) |
→ managed-settings는 사용자가 못 바꿉니다. 조직 정책 강제의 핵심.
🔑 우리 조직은 어떤 인증을 써야 할까
| 상황 | 추천 |
|---|---|
| 이미 AWS 청구·거버넌스를 씀 | Bedrock + IAM/SSO |
| GCP 중심 조직 | Vertex AI + ADC |
| 소규모·빠른 시작 | 구독(OAuth) 또는 API 키 |
✅ 전사 배포 전 보안 체크리스트
☐ MCP server allowlist로 허용 서버만 통과
☐ DLP Hook으로 시크릿 유출 차단
☐ 자격증명은 IAM Role/SSO로 (하드코딩·평문 금지)
☐ OTel·CloudTrail로 사용·감사 로그 수집
☐ Offboarding(SCIM)으로 퇴사자 접근 자동 회수
🧯 자주 막히는 지점
| 증상 | 처방 |
|---|---|
| Bedrock 모델 호출 실패 | 콘솔 Model access 승인 + 리전·모델 ID 일치 확인 |
| SSO 로그인 만료 | aws sso login --profile ... 재실행 |
| managed-settings 미적용 | 경로(/etc/claude-code/)·JSON 문법·권한 확인 |
🔭 OpenTelemetry 실전 설정 (최신 20260703 에디션)
최신 에디션은 사용량·비용을 OTLP로 내보내는 표준 환경변수를 제공합니다. 조직 관측 시스템(Collector)에 그대로 연결됩니다.
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
export OTEL_RESOURCE_ATTRIBUTES=team=platform,env=prod→ 지표(metrics)·로그(logs)를 팀/환경 속성과 함께 수집해 사용자별·팀별 비용 추적이 가능합니다.
🔑 자격증명·정책 최신 옵션
| 항목 | 역할 |
|---|---|
CLAUDE_CODE_API_KEY_HELPER_TTL_MS | 자격증명 헬퍼 캐시 수명(회전 주기) 제어 |
managed-settings.json | 사용자 설정보다 우선 — 조직 정책 강제(권한·MCP allowlist·Hook) |
| OIDC / SSO | IdP(Okta·Entra 등) 연동 로그인 흐름 |
🏢 현업 도입 가이드 (규모·비용·환경)
| 주제 | 권장 |
|---|---|
| 비용 예산 | 1인당 월 약 $27 기준 + 30% 안전 마진. Opus 사용은 별도 통제. PoC에서 실측 후 조정 |
| 인증 선택 | 10인 이상 → Bedrock + IAM Identity Center(SSO) / 1~5인 PoC → OAuth Pro로 간단히 |
| 폐쇄망(Air-Gap) | Bedrock VPC Endpoint + 사내 npm 미러(Verdaccio/Nexus) + 사내 MCP 서버 |
| 대량 배포 | "500대 설치·갱신" 관점 — Native/MSI 대량 배포 + 버전 고정 |
❓ FAQ
Q1. 사내망(외부 인터넷 차단)에서 Claude Code를 쓸 수 있나요?
A. 네. Bedrock VPC Endpoint로 AWS 사설망 내에서만 통신하고, npm 미러와 MCP 서버를 사내에 구축하면 됩니다.
Q2. 도입 비용 예산은 어떻게 잡나요?
A. 1인당 월 약 $27 + 30% 마진이 출발점. Opus 사용은 별도 통제하고, PoC에서 실측 후 본 도입 시 조정합니다.
Q3. SSO와 OAuth Pro 중 무엇을 고르나요?
A. 10인 이상은 Bedrock + IAM Identity Center, 1~5인 PoC는 OAuth Pro로 간단히 시작하세요.
Q4. 개발자가 managed-settings를 우회할 수 있나요?
A. 아니요. /etc/claude 디렉토리는 root 권한이 필요하고, deny 규칙은 항상 승리하므로 우회 불가입니다.
Q5. 컴플라이언스 감사 자료는 어디서 얻나요?
A. CloudTrail(필수) + OpenTelemetry(선택) + managed-settings 문서. Anthropic에 SOC 2 보고서를 요청할 수 있습니다.
settings.json·권한·Hooks·MCP·슬래시 커맨드를 실제 설정 수준으로 다룹니다.