AWS 기술 블로그
Claude Apps Gateway on AWS 자세히 알아보기
들어가며
최근 많은 엔터프라이즈 기업들은 Amazon Bedrock을 기반한 Claude Code 및 Claude Desktop의 도입을 적용하고 있습니다. Amazon Bedrock을 통해 Claude 모델을 호출하면, 사용자의 데이터를 모델 학습에 재활용하지 않으며, Private Network 기반으로 사용자들의 Claude 사용 환경을 구성 할 수 있습니다. 또한 기존 AWS 계정·IAM 권한 체계를 통해 인증과 비용을 통합 관리할 수 있으며, Guardrails로 콘텐츠 필터링을 적용하는 등 사내 보안 거버넌스에 맞춘 Claude 사용 환경을 구성 할 수 있습니다.
그러나, Amazon Bedrock 기반의 Claude를 도입 할 시 사용자 각자의 AWS Access Key 관리, 누가 어떤 모델을 얼마나 썼는지, 권한 회수는 제때 되었는지 등의 사용 환경을 구성해야합니다. 그래서 많은 조직이 Claude와 Bedrock 사이에 LLM Gateway(ex. LiteLLM)를 두어, 개발자는 LLM Gateway에서 발급 받은 API Key을 통해 LLM Gateway와 인증하고, 실제 Amazon Bedrock과의 업스트림 자격증명은 Gateway가 한 곳에서만 보관하며 모델 접근·사용량을 사용자 단위로 통제하는 방식을 택합니다.
이 글에서는 Anthropic이 Claude Code 바이너리에 기본 내장한 자체 Gateway인 Claude Apps Gateway를 AWS 환경에 직접 구성하고 배포해보면서, 어떤 기능을 제공하고 어디까지 지원하는지 자세히 살펴봅니다.
Claude Apps Gateway이란?
Claude Apps Gateway는 Anthropic이 Claude Code CLI 바이너리에 기본으로 내장해 배포하는 자체 LLM Gateway입니다. 별도의 프록시 프로젝트를 따로 설치할 필요 없이, 개발자 노트북에서 claude를 실행하는 것과 동일한 바이너리로 claude gateway --config gateway.yaml 명령만 실행하면 서버로 동작합니다.
Claude Apps Gateway는 개발자와 모델 제공자 사이에서 인증·접근 제어·사용량 추적을 조직이 통제하는 한 곳으로 중앙화하는 역할을 합니다. 기존의 LLM Gateway(ex. LiteLLM)와는 다르게, 개발자는 API Key를 발급받아 보관하는 대신 회사 IdP(Okta, Microsoft Entra ID, KeyCloak 등)로 브라우저 SSO 로그인을 하고, 로그인이 끝나면 Gateway가 발급한 단기 세션 토큰으로 인증합니다. 이를 통해 기존의 구성 된 IdP 구조 기반으로 그룹 및 사용자 별 Claude 모델에 대한 권한 제어 및 사용량 제어를 가능하게 합니다.
Claude Code의 사용을 기존 IdP와 연동하는 것 외에도, Claude Apps Gateway는 IdP 그룹별로 Managed Settings를 동적으로 전달할 수 있게 해줍니다. 순수 Bedrock 환경에서는 각 사용자의 Claude Code 사용 환경을 제어 할 수 있는 Managed Setting에 대한 사용이 불가했습니다. Claude Apps Gateway에서 Managed Settings 정책을 매핑해두면 로그인한 클라이언트에 Gateway가 해당 정책을 직접 전달하며, 그룹별로 모델·툴 접근 권한을 다르게 강제할 수 있습니다.
AWS에서 Claude Apps Gateway 구성하기

구성 시 주의 사항 및 아키텍처 소개
Claude Apps Gateway는 크게 세 구간으로 나눠서 볼 수 있습니다. 개발자의 Claude Code는 브라우저로 회사 IdP에 로그인하고, IdP는 Gateway의 콜백으로 인증 결과를 돌려줍니다. Gateway는 이 인증 상태와 세션 정보를 PostgreSQL에 저장하고, 로그인이 끝난 이후의 모든 요청은 Gateway가 보관한 업스트림 자격증명(Bedrock IAM 등)으로 대신 서명해서 전달합니다. 이 구조의 동작을 위해서는 아래 구성 시 주의사항에 대한 요건을 확인해야합니다.
- Claude 바이너리 버전: Gateway 기능은 Claude Code v2.1.195부터 포함되어 있습니다. Gateway를 띄우는 서버와 로그인하는 개발자 각자의 머신 모두 v2.1.195 이상이어야 합니다. 만약 업스트림으로 Bedrock이 아니라 Claude Platform on AWS를 사용한다면, Gateway 서버 쪽은 v2.1.198 이상이 필요합니다.
- Private Network 기반의 연결: Claude Code는 사설 IP로만 resolve되는 주소의 Gateway에만 연결을 허용합니다.
/login단계에서 Gateway의 호스트명이나 IP가 사설 IP로 resolve되어야 하고, 하나라도 공개 IP로 풀리면 거부됩니다. 이를 위해 개발자가 사용하는 Claude Code 환경과 AWS 상에 배포된 Claude Apps Gateway 간에는 Direct Connect 구성 또는 VPN 기반의 Private Network 연결을 구성해야합니다. - HTTPS 기반의 Claude Apps Gateway 구성: Gateway는 개발자 노트북과 로그인용 브라우저 양쪽 모두에서 https://로 접근 가능해야 합니다. 이를 위해 Claude Apps Gateway 앞단에 ALB 배치 또는 설치된 서버에 웹서버(ex. Nginx) 구성을 통해 Claude Code 개발 PC와 Claude Apps Gateway 간에는 HTTPS 기반의 통신 환경을 구성해야합니다. (해당 블로그에서는 ALB로 구성했습니다.)
- OpenID 기반의 IdP와 연동만 지원: Claude Apps Gateway는 OIDC(OpenID Connect) 호환 IdP만 지원합니다. Okta, Microsoft Entra ID, Google Workspace, Keycloak 등 OIDC 표준을 따르는 IdP라면 연동할 수 있습니다. (SAML이나 LDAP 기반 IdP는 지원 불가)
- PostgreSQL 14 이후 버전의 RDBMS 사용: Gateway는 디바이스 로그인 플로우 상태와 rate-limit 카운터를 저장하기 위해 PostgreSQL 14 이상이 필요합니다. 이를 위해 Amazon RDS 및 Amazon Aurora 기반의 PostgreSQL 을 사용 할 수 있습니다.
Docker 기반의 Claude Apps Gateway 배포
gateway.yaml을 통해 Claude Apps Gateway 환경 설정
Claude Apps Gateway을 배포하기 위해서는, Claude Apps Gateway의 환경 설정 파일을 작성해야 합니다. gateway.yaml 을 작성 및 배포시 활용하며, 환경 설정에 대한 예시는 아래와 같습니다.
Docker 기반 배포를 위한 도커 파일 생성
Docker 이미지 빌드 및 실행
Claude Apps Gateway 기능 소개
1-1. Identity Provider(IDP) 와 연동한 Claude Code 로그인
개발자 PC에서 Claude Apps Gateway을 통해 로그인 하기 위해서는 아래 두 가지 조건이 충족되어야 합니다.
- Claude Code v2.1.195+ 버전 이상 사용
- managed-settings.json 설정 파일을 저장해야하며 아래는 File-based 방식의 저장 방식입니다. 더 자세한 방법은 Claude Code 공식 문서를 확인하세요.
- macOS: /Library/Application Support/ClaudeCode/managed-settings.json
- Linux and WSL: /etc/claude-code/managed-settings.json
- Windows: C:\Program Files\ClaudeCode\managed-settings.json
개발자 PC에서 Claude Apps Gateway을 통해 로그인하여 사용하기 위해서는 claude /login 명령어를 통해 로그인 할 수 있습니다. 명령어 입력 시 액세스 코드가 발급되고, 해당 코드를 Claude Apps Gateway에 입력합니다. 최종 사내 IdP에 로그인하여 Claude Code을 IdP와 연계하여 사용 할 수 있습니다.

1-2. Identity Provider(IDP) 와 연동한 Claude Desktop 로그인
Claude Desktop App에서도 Claude Apps Gateway을 통한 인증이 가능합니다. Claude Apps Gateway 기반의 Claude Desktop 사용을 위해서는 아래의 조건이 충족되어야 합니다.
- Help → Troubleshooting → Developer Mode 활성화합니다.
- Developer → Configure third-party inference 셋팅에서 아래와 같이 셋팅합니다.
- 연결 타입 : Gateway로 지정
- Gateway base URL : Claude Apps Gateway URL 지정
- Credential kind를 Interactive Sign-in 으로 지정


2. Managed Settings 기반의 권한 제어
Managed Settings는 Claude Code의 설정 체계에서 관리자가 강제로 적용하는 계층입니다. Managed Settings은 두 가지 방식으로 전달됩니다. 하나는 MDM으로 각 기기에 managed-settings.json 파일을 배포하는 방식이고, 다른 하나는 claude.ai 관리자 콘솔에서 조직 정책을 등록해 로그인한 클라이언트에 동적으로 내려주는 방식입니다.
문제는 순수 Amazon Bedrock 환경에서는 이 중 관리자 콘솔 기반 배포를 쓸 수 없었다는 점입니다. 그래서 Amazon Bedrock 기반으로 Claude Code을 사용하는 조직이 쓸 수 있는 방법은 MDM으로 managed-settings.json 파일을 기기에 정적으로 배포하는 것뿐이었습니다. 이 방식은 정책이 사용자가 아니라 기기에 묶여 있다는 한계가 있었습니다.
사용자가 Claude Apps Gateway을 통해 로그인을 하게 되면 Claude Apps Gateway에 설정 된 Managed Settings 정보를 ~/.claude/remote-settings.json 경로에 캐시하게 됩니다. 캐시된 Settings 정보는 사용자가 로컬에 설정한 ~/.claude/settings.json 보다 우선하여 적용됩니다.

3. IDP 그룹 별 모델 및 사용량 제어
그룹 별 모델 제한
모델 접근 제어는 앞서 본 managed.policies를 그대로 활용합니다. match.groups로 특정 IdP 그룹을 지정하고, 그 그룹에만 적용할 cli.availableModels를 지정하면 그룹마다 사용할 수 있는 모델 목록이 달라집니다. 아래와 같이 전체 사용자에게는 Opus, Sonnet, Haiku 모델에 대한 사용을 승인하지만, 임시 사용자에 속한 그룹은 Haiku 모델만 허용해 줄 수 있습니다.

아래와 같이 임시 사용자 그룹에 속한 사용자는 Opus 모델에 대한 사용은 불가하고, Haiku에 대한 사용만 가능하게 됩니다.

그룹 별 사용량 제한
조직이나 사용자별로 Claude Code 사용량을 제한하려면, Gateway가 노출하는 별도의 Admin API를 통해서 설정해야 합니다. admin 블록을 활성화해두면 /v1/organizations/spend_limits 엔드포인트가 활성화되고, 이 API로 사용자·그룹·조직 단위의 한도를 실시간으로 조정할 수 있습니다.
아래와 같이 모든 사용자에게는 주간 $100의 예산을 할당하고, 임시 사용자 그룹에 속한 사용자에게는 주간 $50을 할당한다고 가정해보도록 하겠습니다. 사용량 제한을 위해 gateway.yaml 에서 설정한 write_keys을 사용합니다. 사용량 설정이 아닌 단순 조회용을 위해서는 read_keys 을 통해서도 가능합니다.
- write_keys: 한도 설정/삭제/조회 모두 가능 (관리자용)
- read_keys: 조회만 가능 (모니터링/대시보드용)

모든 사용자에게 주간 $100의 예산 할당
임시 사용자 그룹(temporary-group)에게 주간 $50의 예산 할당
현재 설정한 한도 목록 조회
사용자별 주간 지출 vs 한도 조회
사용자에게 할당 된 예산이 초과 시 아래처럼 자동으로 사용이 차단됩니다.

4. OpenTelemetry을 통한 모니터링
OpenTelemetry(OTEL)은 메트릭·로그·트레이스 같은 텔레메트리 데이터를 표준화된 형식으로 수집하고 내보내는 오픈소스 프레임워크입니다. Claude Code는 세션에서 발생하는 토큰 사용량, 모델별 요청 수, 지연 시간 같은 지표를 OTLP(OpenTelemetry Protocol) 형식으로 내보낼 수 있습니다. 그러나 Amazon Bedrock 환경에서는 이를 사용하기 위해서는 개발자마다 로컬에서 OTEL_EXPORTER_OTLP_ENDPOINT 같은 환경변수를 직접 설정해야 했습니다.
Claude Apps Gateway는 이 OpenTelemetry 파이프라인을 중앙에서 관리합니다. gateway.yaml에 전달 대상을 설정해두면 로그인한 모든 클라이언트에게 OTEL 관련 환경변수가 자동으로 적용되어 사용자의 사용 기록들이 OpenTelemetry 수집 대상으로 전달되게 됩니다. 아래는 metrics, logs, trace에서 전달되는 지표 정보입니다.
- metrics: 토큰 수, 요청 수, 지연 시간 같은 집계 카운터
- logs와 traces: 전체 bash 명령어, 툴 입력값, 파일 경로 등 Claude Code가 개발자 머신에서 하는 모든 작업

CloudWatch의 Coding Agent Insights을 활용한 사용량 및 생산성 모니터링
Amazon CloudWatch의 Coding Agent Insights는 Claude Code, OpenAI Codex, GitHub Copilot 같은 AI 코딩 에이전트가 내보내는 OpenTelemetry 지표(토큰 사용량, 툴 호출, 레이턴시 등)를 받아 자동으로 채워지는 사전 구성된 대시보드입니다. 조직·부서·팀·비용 센터·사용자 단위로 도입률과 비용을 비교할 수 있고, 에이전트가 정해진 형식으로 지표를 보내기 시작하면 대시보드를 따로 만들 필요 없이 CloudWatch 콘솔에 자동으로 나타납니다.
Gateway의 텔레메트리 전달 기능은 SigV4 서명이 아닌 정적 헤더 인증만 지원하기 때문에, CloudWatch OTEL엔드포인트에 인증하려면 Bearer 토큰 역할을 하는 API 키가 필요합니다. API의 발급은 AWS CLI 또는 AWS 콘솔에서 발급이 가능합니다. Metrics 용 Key와 Logs Key는 각각 발급받아야 합니다. 아래는 Metrics 키를 발급받는 예시입니다.

Claude Apps Gateway가 CloudWatch에 지표를 전송하기 시작하면, 별도의 대시보드 구성 없이도 다양한 카테고리 별로 사용량 및 생산성을 확인 할 수 있습니다. 전체 및 각 사용자 별 토큰·비용·토큰 타입 등의 지표를 실시간으로 확인 할 수 있습니다. 개발 생산성 탭에서는 사용자별 코드 라인 증감, 커밋, 활동 시간, PR 현황뿐 아니라 언어별 코드 생성량과 편집 도구 사용 패턴까지 확인할 수 있어, 단순 사용량 집계를 넘어 실제 개발 생산성 지표까지 확인이 가능합니다.


OpenTelemetry을 통한 각 사용자 별 프롬프트 로깅
사용자들의 프롬프트 정보들을 별도로 로깅하기 위해서는 OTEL_LOG_USER_PROMPTS=1을 설정해야 실제 프롬프트 내용이 로그에 포함됩니다. Gateway는 이 로그에 로그인한 사용자의 user.id, user.email, user.groups를 자동으로 함께 전달하기 때문에, 별도 설정 없이도 누가 어떤 프롬프트를 입력했는지 사용자별로 구분해서 확인할 수 있습니다.

한계 및 미지원 사항
Claude Apps Gateway를 도입하기 전에 아래의 제약사항을 확인해야합니다. 해당 제약 사항은 블로그를 작성하는 시점을 기준으로 합니다.
- OIDC 전용 인증: SAML이나 LDAP 기반 IdP는 지원하지 않습니다. 필요하다면 OIDC 브리지를 앞에 위치시켜야 합니다.
- UI 기능 미제공: Gateway 설정은 gateway.yaml 파일 하나로만 관리되고, 변경 시 재배포를 통해 변경 할 수 있습니다.
- WebSearch API 미지원: Gateway 세션에서는 CLI가 어떤 프로바이더로 라우팅되는지 확인할 수 없어서 WebSearch API 툴 자체가 비활성화됩니다.
- Windows 서버 미지원: Gateway 서버는 네이티브 Linux 바이너리에서만 동작합니다.
결론
이 글에서는 Amazon Bedrock 기반으로 Claude Code를 쓰는 조직이 LiteLLM 같은 범용 LLM Gateway 대신 Claude Apps Gateway를 도입했을 때 얻을 수 있는 것들을 살펴봤습니다. Claude Apps Gateway 기반의 Claude on Amazon Bedrock을 사용할 경우 아래의 이점을 경험 할 수 있습니다.
- 불필요한 LLM Gateway 키 발급 및 관리: Claude Apps Gateway을 사용 할 경우 Claude Code/Desktop 사용 시 IdP 기반으로 로그인하게 됩니다. 이를 통해 기존의 오픈소스 LLM Gateway 에서 필요하던 키 발급 및 관리가 불필요하게 됩니다.
- IdP 그룹 및 사용자 기반의 모델 사용 권한/사용량 제어: 기존 IdP에 구성되어 있던 그룹 및 사용자 정보를 기반으로 Claude 모델에 대한 사용 권한 및 사용량 제어를 가능하게 합니다. 이를 통해 더 효율적인 Claude Code/Desktop 운영을 구성 할 수 있습니다.
- Managed Setting을 통한 Claude 사용 환경 제어: 지금까지 Anthropic 1P에서 사용 가능하던 Managed Setting을 통해 사용자들의 Claude 사용 환경을 중앙에서 관리 할 수 있습니다. 관리자가 설정한 Managed Setting은 각 각 사용자 환경에서 가장 우선적으로 적용되게 됩니다.
- OTLP의 중앙 처리와 CloudWatch와의 연계: 각 사용자들의 OTLP 데이터를 사용자 환경이 아닌 Claude Apps Gateway 단에서 목적지로 전달합니다. 목적지를 CloudWatch로 전달 할 경우 별도의 OTLP 파이프라인을 구성이 불필요하며, Coding Agent Insights 기능을 통해 사용 현황 및 개발 생산성을 파악 할 수 있습니다.