Amazon Bedrock 기반 Claude Code, 조직에서 안전하게 운영하기: LLM Gateway 구축 가이드

“개발자들이 AI 코딩 도구를 쓰고 싶다고 합니다. 보안팀에서 허용해도 될까요?”

이 질문은 이제 대부분의 엔터프라이즈 IT 리더가 마주하는 현실입니다. AI 코딩 도구의 생산성 향상 효과는 분명하지만, 기업 환경에서는 단순히 도구를 허용하는 것만으로 충분하지 않습니다. 누가, 얼마나 사용하는지 추적할 수 있어야 하고, 사용자별 예산을 제한할 수 있어야 하며, 조직의 기존 인증 체계와 통합되어야 합니다.

Claude Code는 에이전틱 코딩(agentic coding) 도구로, 코드베이스를 이해하고 파일을 편집하며 git 커밋까지 자율적으로 수행합니다. 이런 자율적 동작은 높은 생산성을 가져오지만, 동시에 상당한 토큰을 소비합니다. 100명의 개발자에게 토큰 등의 제한 없이 툴을 허용한하면 월 수만 달러의 비용이 발생할 수 있습니다. 이 글에서는 Amazon Bedrock에서 Claude Code를 안전하게 운영하기 위한 LLM Gateway를 구축합니다. IAM Identity Center SSO 인증과 LiteLLM Proxy기반 Gateway를 결합하여, 개발자는 aws sso login 한 번으로 Claude Code를 사용하고, 관리자는 사용자별 사용량 추적과 예산 관리를 수행할 수 있습니다. IAM Identity Center는 Microsoft Entra ID나 Okta 같은 외부 IdP와 SAML 2.0으로 연동할 수 있으므로, 조직에서 이미 사용 중인 SSO 인프라를 그대로 활용할 수 있습니다. 전체 인프라를 AWS CDK로 구현한 코드는 GitHub에서 확인할 수 있습니다.

LLM Gateway와 Claude Code

왜 LLM Gateway가 필요한가

Claude Code를 Amazon Bedrock에 직접 연결하면, 각 개발자에게 Bedrock 호출 권한(IAM)을 부여하는 것만으로 동작합니다. Bedrock은 Model Invocation Logging을 통해 모든 모델 호출의 메타데이터와 입출력 데이터를 CloudWatch Logs 또는 S3에 기록할 수 있으며, 이를 기반으로 CloudWatch 대시보드나 Athena 쿼리로 사용량을 분석하고 Lambda로 예산 초과 차단 로직을 구현하는 등 자체적인 관리 체계를 구축할 수도 있습니다. 하지만 사용자별 비용 집계 대시보드, 예산 제어 자동화, 인증 체계 연동 등을 모두 직접 구현하고 운영해야 하므로 상당한 개발 공수와 관리 포인트가 수반됩니다:

• 사용자별 비용 추적 불가: Bedrock CloudWatch 메트릭은 IAM 역할 단위로 집계되어 개발자 간 비용 구분이 어렵습니다
• 사용자별 예산 제한 불가: IAM 정책으로는 “이 사용자의 월 사용량을 100달러로 제한”하는 제어가 불가능합니다
• 중앙 집중식 인증 관리 어려움: 개발자별 IAM 자격증명 관리 또는 전원이 동일 역할을 공유해야 합니다
• 감사 로그 부재: 누가, 언제, 어떤 작업에 모델을 사용했는지 추적하기 어렵습니다

Claude Code 공식 문서에서는 이러한 문제를 해결하기 위해 LLM Gateway 패턴을 소개합니다. LLM Gateway는 조직과 LLM API 프로바이더 사이에 위치하는 중간 서비스로, 인증, 사용량 추적, 접근 제어 등의 기능을 제공합니다. 이 글에서 사용하는 LiteLLM Proxy는 이러한 기능을 기본 제공하며, 관리자 포털(Web UI)을 통해 사용자별 키 관리, 예산 설정, 사용량 모니터링을 수행할 수 있습니다.

Pass-through 모드

LLM Gateway를 구성할 때 가장 먼저 결정해야 하는 것은 요청 처리 방식입니다. LiteLLM은 두 가지 모드를 제공합니다:

이 블로그에서는 LiteLLM의 Bedrock pass-through 모드를 선택했습니다. Claude Code는 내부적으로 Bedrock 네이티브 API를 사용하므로, pass-through 모드가 변환 없이 요청을 그대로 전달하여 prompt caching을 포함한 모든 기능과의 완전한 호환성을 보장합니다. Translation 모드는 범용 클라이언트 지원에 유리하지만, Claude Code처럼 이미 Bedrock API를 사용하는 도구에는 불필요한 변환이 오히려 기능 손실을 초래할 수 있습니다.

LiteLLM 보안 경고: LiteLLM PyPI 패키지 버전 1.82.7 및 1.82.8에서 자격증명 탈취 악성코드가 발견되었습니다 (BerriAI/litellm#24518). 공격자가 탈취한 PyPI 토큰으로 이 두 버전을 직접 업로드한 것으로 확인되었으며, GitHub 소스코드에는 악성코드가 포함되지 않았습니다. 악성 버전은 PyPI에서 삭제 완료되었습니다.

• PyPI pip install 사용자: 버전 1.82.7 또는 1.82.8을 설치한 적이 있다면, 즉시 제거하고 영향받은 시스템의 모든 자격증명(AWS 키, DB 비밀번호, API 토큰 등)을 교체하세요.
• Docker 이미지 사용자: LiteLLM 팀은 공식 Docker 이미지(ghcr.io/berriai/litellm)는 의존성 버전이 고정(pin)되어 있어 이번 사건의 영향을 받지 않았음을 확인했습니다. 이 가이드는 PyPI가 아닌 공식 Docker 이미지를 사용하므로, 가이드를 따라 배포한 환경은 영향을 받지 않습니다.

이 글에서 소개하는 LiteLLM은 오픈소스 서드파티 도구이며, AWS가 보증하지 않습니다. 프로덕션 환경에 배포하기 전에 반드시 자체 보안 검토를 수행하세요.

솔루션 아키텍처

전체 흐름

아키텍처는 인증 경로(1~4단계)와 요청 경로(5~7단계)로 구성됩니다:

개발자가 직접 수행하는 작업은 aws sso login과 claude 실행뿐입니다. Virtual Key 생성, 캐싱, LiteLLM 인증은 모두 백그라운드에서 자동으로 처리됩니다.

SSO 인증과 Virtual Key 발급 (2~4단계)

Token Service는 SSO 인증 체계와 LiteLLM Virtual Key 체계를 연결하는 핵심 컴포넌트입니다. API Gateway IAM Auth를 통해 인증된 요청의 SSO ARN에서 사용자명을 파싱하고, 해당 사용자의 Virtual Key를 DynamoDB에서 조회하거나 신규 생성합니다.

SSO ARN 파싱 로직:

def _parse_sso_arn(arn: str) -> tuple[str, str, str] | None:
    """
    SSO assumed-role ARN에서 사용자 정보를 추출합니다.

    ARN 예시:
      arn:aws:sts::123456789012:assumed-role/AWSReservedSSO_ClaudeCodeUser_abc123/alice
    추출 결과:
      ("alice", "ClaudeCodeUser", "123456789012")
    """
    pattern = r"^arn:aws:sts::(\d+):assumed-role/AWSReservedSSO_([^_]+)_[^/]+/(.+)$"
    match = re.match(pattern, arn)
    if not match:
        return None
    return match.group(3), match.group(2), match.group(1)  # username, role, account

AWSReservedSSO_ prefix는 IAM Identity Center가 생성하는 역할에만 붙는 고유 패턴입니다. 일반 IAM 역할에는 이 prefix가 없으므로, SSO를 통하지 않은 직접 IAM 자격증명 사용을 자연스럽게 차단합니다. 이 접근법의 장점:

• 별도의 사용자 데이터베이스 불필요. SSO ARN 자체에 사용자명이 포함되어 있어, Cognito 같은 추가 IdP 연동 없이 개인 식별이 가능합니다.
• 개발자 경험 영향 없음. Claude Code의 apiKeyHelper 메커니즘이 전체 과정을 자동 처리합니다.
• DynamoDB 캐시로 밀리초 응답. Virtual Key는 첫 로그인 시에만 생성되고, 이후에는 캐시에서 즉시 반환됩니다.

apiKeyHelper 스크립트(Claude Code가 API 키를 동적으로 가져오기 위해 호출하는 셸 스크립트입니다):

#!/bin/bash
set -euo pipefail

TOKEN_SERVICE_URL="${TOKEN_SERVICE_URL:-https://{API_GW_ID}.execute-api.us-east-1.amazonaws.com/v1/auth/token}"
AWS_REGION="${AWS_REGION:-us-east-1}"
# SSO 자격증명 export
eval $(aws configure export-credentials --format env 2>/dev/null) || {
  echo "ERROR: aws sso login 을 실행하세요" >&2
  exit 1
}
# Token Service 호출 (SigV4 서명)
RESPONSE=$(curl -s -X POST "$TOKEN_SERVICE_URL" \
  --aws-sigv4 "aws:amz:${AWS_REGION}:execute-api" \
  --user "${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}" \
  -H "x-amz-security-token: ${AWS_SESSION_TOKEN:-}" \
  -H "Content-Type: application/json" \
  -d '{}' 2>/dev/null)

TOKEN=$(echo "$RESPONSE" | python3 -c \
  "import sys,json; print(json.load(sys.stdin).get('token',''))" 2>/dev/null)
if [ -z "$TOKEN" ]; then
echo "ERROR: Token Service에서 키를 받지 못했습니다: $RESPONSE" >&2
  exit 1fi
echo "$TOKEN"

스크립트는 aws configure export-credentials로 SSO 자격증명을 내보내고, curl --aws-sigv4로 SigV4 서명된 요청을 Token Service에 보냅니다. 반환된 Virtual Key를 stdout으로 출력하면, Claude Code가 이를 Bearer Token으로 사용합니다.

LLM Gateway를 통한 Bedrock 호출 (5~6단계)

Claude Code가 LiteLLM을 거쳐 Bedrock에 접근할 때, 인증은 두 단계로 분리됩니다:

• Claude Code → LiteLLM: Virtual Key로 인증. CLAUDE_CODE_SKIP_BEDROCK_AUTH=1로 클라이언트 측 SigV4 서명을 건너뜁니다.
• LiteLLM → Bedrock: ECS Fargate Task Role이 IAM 권한으로 Bedrock을 호출합니다. AWS SDK가 SigV4 서명을 자동 처리합니다.

이 분리 덕분에 개발자에게 Bedrock IAM 권한을 직접 부여할 필요가 없습니다. 모든 Bedrock 호출은 ECS Task Role을 통해 중앙 관리됩니다. 또한 Bedrock으로의 모델 호출은 VPC Endpoint(AWS PrivateLink)를 통해 AWS 내부 네트워크에서 처리됩니다:

// network-stack.ts
this.vpc.addInterfaceEndpoint('BedrockRuntimeEndpoint', {
  service: ec2.InterfaceVpcEndpointAwsService.BEDROCK_RUNTIME,
  subnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
  securityGroups: [this.vpcEndpointSg],
});

트래픽이 인터넷을 경유하지 않으므로 보안이 강화됩니다. 대용량 트래픽 환경에서는 NAT Gateway 데이터 전송 비용 절감 효과도 기대할 수 있습니다.

개발자 경험

초기 설정 (1회)

1단계: AWS CLI SSO 프로필 설정 (~/.aws/config)

[profile claude-code]
sso_session = my-ssosso_account_id = 123456789012
sso_role_name = ClaudeCodeUserregion = us-east-1

[sso-session my-sso]
sso_start_url = https://{IDC_ID}.awsapps.com/startsso_region = us-east-1
sso_registration_scopes = sso:account:access

2단계: Claude Code 설정 (~/.claude/settings.json)

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "ANTHROPIC_BEDROCK_BASE_URL": "https://{ALB_DNS}/bedrock",
    "CLAUDE_CODE_SKIP_BEDROCK_AUTH": "1",
    "AWS_REGION": "us-east-1",
    "AWS_PROFILE": "claude-code"
  },
  "apiKeyHelper": "/path/to/scripts/get-gateway-token.sh"
}

참고: Bedrock 환경에서는 Claude Code의 Server-managed settings를 사용할 수 없습니다. 대신 파일 기반 managed-settings.json 또는 MDM 정책을 통해 이 설정을 중앙 배포할 수 있습니다. managed-settings.json은 Claude Code 설정 우선순위에서 최상위에 위치하여 개발자가 재정의할 수 없으므로, ANTHROPIC_BEDROCK_BASE_URL 등 보안에 민감한 설정을 관리자가 통제하고 개발자의 커스텀 영역을 최소화할 수 있습니다.

일상 사용

export AWS_PROFILE=claude-code
aws sso login    # 브라우저에서 SSO 로그인 (세션 만료 시에만)
claude           # Claude Code 실행 -- 끝

SSO 세션이 유효한 동안은 claude만 실행하면 됩니다.

실제 동작 예시

SSO 인증 없이 접근 시

SSO 로그인 없이 Claude Code를 실행하면, apiKeyHelper 스크립트가 SSO 자격증명을 찾지 못해 오류를 반환합니다:

SSO 인증 후 정상 동작

aws sso login 후 Claude Code를 실행하면, Token Service가 Virtual Key를 자동 발급하고 Claude 모델을 정상적으로 사용할 수 있습니다:

사용자별 예산 초과 시

LiteLLM 관리자 포털에서 설정한 월별 예산을 초과하면, 해당 사용자만 차단되고 예산 초과 오류가 반환됩니다. 다른 사용자는 영향받지 않습니다:

<LiteLLM 관리자 포털에서 사용자별 예산을 설정하고, 초과 시 해당 사용자의 요청이 자동으로 차단된 모습>

인증과 접근 제어

앞서 살펴본 개발자 경험의 이면에서는 다음과 같은 인증 체인이 동작합니다.

5-Layer 인증 체인

이 아키텍처는 5단계의 인증 계층을 거칩니다:

각 계층이 독립적으로 검증하므로, 한 계층이 우회되더라도 다음 계층에서 차단됩니다.

자격증명 관리

하드코딩된 비밀 값이 없습니다. 모든 자격증명은 AWS Secrets Manager에서 관리됩니다:

ECS 컨테이너에는 ecs.Secret.fromSecretsManager()로 시크릿이 주입되어, 태스크 시작 시 Secrets Manager에서 자동으로 값을 가져옵니다.

퇴사자 접근 차단

1단계만 수행해도 SSO 세션 만료 후 차단되지만, 즉시 차단이 필요하면 3단계를 모두 수행합니다.

비용 관리

LiteLLM의 Virtual Key에 예산을 설정하면, 각 사용자의 월별 지출을 제한할 수 있습니다:

# 사용자별 월 100달러 예산 설정
curl -X POST "https://{ALB_DNS}/key/update" \
  -H "Authorization: Bearer {MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "sk-xxxxxxxx",
    "max_budget": 100.0,
    "budget_duration": "30d"
  }'

앞서 개발자 경험 섹션에서 확인한 것처럼, 예산 초과 시 해당 사용자만 차단됩니다. LiteLLM은 Virtual Key별 속도 제한(TPM, RPM)도 지원하므로, 조직 규모에 맞게 함께 설정하는 것을 권장합니다.

위 예시처럼 API로 자동화할 수도 있고, LiteLLM 관리자 포털(https://{ALB_DNS}/ui)에서 웹 UI를 통해 예산 설정, 사용량 확인, 키 관리를 수행할 수도 있습니다. 자동화가 필요한 경우 API를, 수동 관리가 편한 경우 관리자 포털을 활용하면 됩니다.

<LiteLLM 관리자 포털 화면>

확장 포인트

이 아키텍처를 기반으로 조직의 요구사항에 맞게 확장할 수 있습니다:

• 팀별 예산 관리: Token Service에서 SSO 그룹 정보를 추출하여 LiteLLM의 팀 기능과 연동하면, 팀 단위 예산 한도와 사용량 리포팅을 구현할 수 있습니다.
• 감사 로그: Amazon Bedrock의 Model Invocation Logging을 활성화하면 모든 모델 호출의 요청/응답/메타데이터를 CloudWatch Logs 또는 S3에 기록할 수 있습니다. 실시간 모니터링이 필요하면 CloudWatch Logs, 장기 보관과 대량 분석이 필요하면 S3를 선택하며, 두 대상을 동시에 활성화하는 것도 가능합니다.
• 외부 IdP SSO 연동: 이 가이드에서는 IAM Identity Center의 내장 디렉토리를 사용하지만, Microsoft Entra ID나 Okta 같은 외부 IdP와 SAML 2.0으로 연동하면 조직에서 이미 사용 중인 SSO 인프라를 그대로 활용할 수 있습니다. 또한 apiKeyHelper 스크립트의 인증 로직을 커스텀하면 SigV4 서명 외에 다른 인증 방식도 적용할 수 있으므로, 조직의 SSO 체계에 맞게 Token Service 호출 방식을 유연하게 조정할 수 있습니다.
• Amazon Bedrock Guardrails: Bedrock Guardrails를 구성하면 모든 모델 호출에 대해 프롬프트 인젝션 차단, PII 필터링, 유해 콘텐츠 감지를 Bedrock 서비스 레벨에서 적용할 수 있습니다. Guardrails를 적용하려면 InvokeModel 호출 시 guardrailIdentifier 파라미터를 명시하거나, Guardrails Enforcements를 계정/조직 레벨에서 설정해야 합니다.
• AWS Budgets 연동: LiteLLM의 사용자별 예산은 Gateway 레벨의 1차 방어선이고, AWS Budgets는 계정 레벨의 2차 방어선입니다. Bedrock 서비스에 대한 월별 예산과 임계값 알림을 설정하여 비용 폭주를 이중으로 차단할 수 있습니다.

배포

사전 요구사항

• AWS CLI v2, Node.js 18+, AWS CDK v2
• AWS Organization + IAM Identity Center 활성화
• ACM 인증서 (ALB HTTPS용)

배포 명령

npm install
cdk bootstrap    # 최초 1회
cdk deploy LlmGatewayStack \
  -c certificateArn=arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx

NestedStack 구조이므로 루트 스택 하나만 배포하면 전체 인프라가 구성됩니다. 상세 배포 가이드와 검증 절차는 GitHub 리포지토리를 참고하세요.

정리

이 글에서는 Amazon Bedrock 기반 Claude Code를 엔터프라이즈 환경에서 안전하게 운영하기 위한 LLM Gateway 아키텍처를 구축했습니다.

핵심 구현 내용:

• 통합 인증 체계: IAM Identity Center SSO를 Token Service를 통해 LiteLLM Virtual Key에 연결하여, 별도의 사용자 데이터베이스 없이도 기존 조직의 SSO 인프라를 그대로 활용할 수 있습니다.
• 비용 거버넌스: 사용자별 비용 추적과 예산 제한 기능을 통해 AI 코딩 도구의 비용을 효과적으로 관리하고, 예산 초과 시 자동으로 접근을 차단합니다.
• 엔터프라이즈 보안: 5-Layer 인증 체인과 VPC Endpoint를 활용하여 엔터프라이즈 수준의 보안을 제공하며, 모든 트래픽이 AWS 내부 네트워크에서 처리됩니다.
• 개발자 경험: 개발자는 aws sso login과 claude 실행만으로 모든 인증과 키 관리 과정을 의식하지 않고 Claude Code를 사용할 수 있습니다.

배포 및 확장을 위해 전체 인프라는 AWS CDK NestedStack으로 구성되어 있어 npm install && cdk deploy 한 번으로 전체 환경을 구축할 수 있습니다. CDK 코드, Lambda 소스, 배포/운영 가이드를 포함한 전체 구현은 GitHub에서 확인할 수 있습니다.

이 아키텍처는 팀별 예산 관리, 감사 로그, 외부 IdP 연동, Bedrock Guardrails, AWS Budgets 등으로 확장 가능하며, 조직의 요구사항에 맞게 커스터마이징할 수 있습니다.

지금 바로 여러분의 AWS 환경에 배포하여 안전하고 효율적인 AI 코딩 환경을 구축해 보세요.

참고 자료

Claude Code 공식 문서

• Claude Code on Amazon Bedrock
• Claude Code LLM Gateway
• Claude Code 서드파티 통합 가이드

AWS 공식 문서

• Amazon Bedrock VPC Endpoint
• Amazon Bedrock IAM Policy Examples
• Generative AI Lens (Well-Architected Framework)

AWS Solutions & 오픈소스

• Guidance for Claude Code with Amazon Bedrock (AWS Solutions Library)
• LiteLLM – Bedrock Pass-through
• 이 블로그 포스팅의 GitHub Repository