Amazon Bedrock, Google Cloud, Microsoft Foundry용 Claude 앱 게이트웨이

• Claude 앱 게이트웨이를 사용하는 이유, 자체 실행보다 추가되는 것, 그리고 다른 것이 더 적합한 경우
• 전제조건이 포함된 빠른 시작으로 게이트웨이를 0에서 로그인한 개발자까지 진행
• 개발자 연결, 관리 설정을 통해 게이트웨이 URL 설정 포함
• 가용성 및 제한사항 - 게이트웨이를 통해 작동하는 Claude Code 기능 및 서버가 지원하는 것 포함

​

Claude 앱 게이트웨이를 사용하는 이유

• 자격증명: 업스트림 API 키 또는 클라우드 자격증명은 인프라에만 존재합니다. 개발자는 회사 SSO로 인증하고 단기 베어러 토큰을 받으므로, 오프보딩은 IdP에서 발생합니다. 사용자를 프로비저닝 해제하면 게이트웨이 액세스는 기본값인 1시간 내에 세션 수명 내에 만료됩니다.
• 액세스 제어: IdP 그룹은 모델 허용 목록 및 관리 설정 정책에 매핑됩니다. 게이트웨이는 모델 액세스를 서버 측에서 적용하여 부여되지 않은 모델에 대한 요청을 거부하고, 각 그룹의 관리 설정 정책을 선택하며, CLI는 관리 설정 계층에서 이를 적용합니다. 다른 팀은 다른 모델, 도구, 권한을 얻고, 개발자는 정책이 잠근 것을 재정의할 수 없습니다.
• 설정 전달: 게이트웨이는 관리 설정을 로그인한 클라이언트에 자체적으로 전달하여 claude.ai 관리 콘솔의 서버 관리 설정을 대체합니다.
• 텔레메트리: Datadog, Splunk 또는 ClickHouse와 같은 각 구성된 대상은 기본적으로 토큰 수, 모델, 사용자 ID 및 지연 시간이 포함된 OpenTelemetry Protocol (OTLP) 메트릭을 받으며, 로그 및 추적은 대상별 옵트인입니다.
• 업스트림 라우팅: 클라이언트는 Anthropic Messages API를 게이트웨이에 말하고, 게이트웨이는 Bedrock, Google Cloud의 Agent Platform, Foundry 또는 Anthropic API 중 각 업스트림에 대해 변환하며, 그들 사이에 장애 조치가 있습니다. 개발자가 알아차리거나 재구성하지 않고도 지역, 제공자 또는 장애 조치 순서를 변경할 수 있습니다.

​

다른 게이트웨이 구현

​

빠른 시작

​

필수 조건

​

단계

listen:
  host: 0.0.0.0
  port: 8080
  # TLS 종료 프록시 뒤에서 필수. IdP
  # redirect_uri 및 검색 문서에 사용됨.
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com        # /.well-known/openid-configuration을 제공해야 함
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]        # 조직 외부의 id_tokens 거부
  userinfo_fallback: true                  # email/groups를 생략하는 IdP의 경우; 그 외에는 무해함

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}        # openssl rand -base64 32
  ttl_hours: 1                             # IdP 프로비저닝 해제 시 취소 지연도 제한

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}    # 관리 Postgres의 경우 ?sslmode=require 추가

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {} # 비어있음: AWS 기본 자격증명 체인
# (IRSA, EC2/ECS 작업 역할, 환경 변수, ~/.aws)

# 모델은 업스트림별로 자동으로 변환됩니다. 기본 제공 카탈로그
# claude-opus-4-8을 us.anthropic.claude-opus-4-8으로 매핑하고 모든
# Bedrock 지원 Claude 모델에 대해 동일하게 합니다. false로 설정하고 `models:` 목록을 추가하여
# 특정 모델만 노출하세요.
auto_include_builtin_models: true

services:
  gateway:
    image: <your-registry>/claude-gateway:<version>
    ports: ["8080:8080"]
    volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]
    environment:
      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
      GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}
      GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway
      # AWS 자격증명: 프로덕션에서는 이를 생략하고 인스턴스
      # 역할을 사용하세요. 로컬 Compose 테스트의 경우 자신의 것을 전달하세요:
      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
      AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}
    depends_on:
      postgres:
        condition: service_healthy
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gw"]
      interval: 5s
    volumes: ["pgdata:/var/lib/postgresql/data"]
volumes: { pgdata: }

{"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}
[gateway] 2026-06-10T17:03:21.408Z info migration 1 applied
[gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

{
  "issuer": "https://claude-gateway.internal.example.com",
  "device_authorization_endpoint": "…/oauth/device_authorization",
  "token_endpoint": "…/oauth/token",
  "grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
}

curl -s -X POST https://claude-gateway.internal.example.com/oauth/device_authorization | jq

{
  "device_code": "…",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://claude-gateway.internal.example.com/device",
  "verification_uri_complete": "https://claude-gateway.internal.example.com/device?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

​

개발자 연결

​

게이트웨이 URL 설정

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}

​

CI 파이프라인 및 원격 머신

​

개발자에게 적용되는 것

• 모델 액세스: 정책이 부여하지 않는 모델에 대한 요청은 400을 반환하고, /model 선택기는 정책의 availableModels 허용 목록으로 필터링됩니다. 정책에서 enforceAvailableModels: true를 설정하여 Default 옵션이 availableModels 내의 모델로 확인되도록 하세요. 없으면 Default는 선택 가능하게 유지되고 해당 모델이 부여되지 않으면 요청 시 거부됩니다.
• 텔레메트리 대상: 텔레메트리 전달이 구성되면, OTLP 내보내기 엔드포인트는 게이트웨이에 고정되고, 게이트웨이 푸시 구성은 로컬로 설정된 OTEL_* 변수를 재정의합니다.
• 자격증명: 게이트웨이 토큰은 세션의 유일한 자격증명입니다. ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper 및 이전 claude.ai 로그인은 로그인 중에 무시되므로, 개발자는 먼저 claude.ai에서 로그아웃할 필요가 없습니다.
• 관리 설정: 잠긴 키는 로컬로 재정의될 수 없습니다. CLI는 시작 시 정책을 적용하고 각 시간별 폴에서 적용합니다.
• 시작: 로그인한 세션은 게이트웨이가 도달 불가능할 때 약 10초 후 시작 시 오류로 종료되며, 설정 없이 시작하는 대신입니다.
• 프로비저닝 해제: 사용자가 IdP에서 비활성화된 세션은 다음 새로 고침이 실패할 때 ttl_hours 내에 만료됩니다.

​

조직이 볼 수 있는 것

​

가용성 및 제한사항

​

다음 단계

• 예를 들어 그룹별 RBAC, 다중 업스트림 장애 조치 또는 텔레메트리 대상을 추가하여 gateway.yaml을 최소 구성 이상으로 확장하세요. 구성 참조는 모든 옵션을 다룹니다.
• Compose에서 Kubernetes 또는 Cloud Run의 프로덕션 배포로 이동하고, IdP를 올바르게 설정하고, 보안 모델을 검토하세요. 배포 및 운영 가이드는 IdP별 설정, 컨테이너 이미지 요구사항, 상태 프로브 및 문제 해결을 다룹니다.
• 개별 개발자 또는 그룹에 지출 상한을 설정하여 폭주 워크로드가 전체 약정을 소비할 수 없도록 하세요. 지출 제한은 관리 API 및 적용 방식을 다룹니다.
• Google Cloud의 완전한 작동 예제(Cloud Run, Cloud SQL 및 Secret Manager 포함)는 Google Cloud에 배포를 참조하세요.