View a markdown version of this page

Configuración de Claude Code con la puerta de enlace de aplicaciones de Claude - Amazon CloudWatch
Capacidades claveRequisitos previosImplementación de la puerta de enlaceConexión de los desarrolladores a la puerta de enlaceEnrutamiento de la telemetría a Amazon CloudWatchDisponibilidad y limitacionesSiguientes pasos

Configuración de Claude Code con la puerta de enlace de aplicaciones de Claude

La puerta de enlace de aplicaciones de Claude es un servicio autohospedado que se sitúa entre los clientes de Claude Code de los desarrolladores y el proveedor del modelo. Los desarrolladores inician sesión mediante el proveedor de identidades (IdP) corporativo, en lugar de utilizar claves de API o credenciales de servicios en la nube. La puerta de enlace almacena la credencial del servicio ascendente, aplica el acceso a los modelos y la configuración administrada según el grupo del IdP, y transmite la telemetría de uso al conjunto de herramientas de observabilidad, incluido Amazon CloudWatch.

La puerta de enlace se incluye en el archivo binario claude. El mismo archivo ejecutable con el que se ejecuta Claude Code también ejecuta la puerta de enlace cuando se proporciona el subcomando gateway junto con un archivo de configuración.

Capacidades clave

La puerta de enlace de aplicaciones de Claude proporciona control centralizado en varias dimensiones.

  • Credenciales: la clave de API del servicio ascendente solo se sitúa en la infraestructura. Los desarrolladores se autentican mediante SSO con tokens de corta duración.

  • Control de acceso: los grupos del IdP se asignan a listas de modelos permitidos y a políticas de configuración administrada.

  • Distribución de la configuración: la puerta de enlace entrega la configuración administrada a los clientes que han iniciado sesión.

  • Telemetría: dirige al recopilador las métricas OTLP, como los recuentos de tokens, el modelo, la identidad del usuario y la latencia. Puede distribuir la telemetría a varios destinos, entre ellos CloudWatch, Datadog, Splunk y ClickHouse.

  • Enrutamiento a servicios ascendentes: los clientes utilizan la API Messages de Anthropic. La puerta de enlace traduce las solicitudes para cada servicio ascendente y ofrece conmutación por error. Los servicios ascendentes compatibles incluyen Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google, Microsoft Foundry y la API de Anthropic.

Requisitos previos

Antes de implementar la puerta de enlace, compruebe que se cumplan los siguientes requisitos:

Requisito Details
Versión de Claude Code v 2.1.195 o posterior
Proveedor de identidades Proveedor de OpenID Connect (OIDC), como Okta, Microsoft Entra ID, Google Workspace, Keycloak o Dex
Database PostgreSQL 14 o posterior
Proveedor de modelos ascendente Credenciales de Amazon Bedrock, Claude Platform en AWS, Google Cloud, Microsoft Foundry o una clave de API de Anthropic
TLS Certificado HTTPS o punto de entrada con terminación TLS
Network Dirección de red privada, como RFC 1918, dirección local de vínculo, CGNAT, ULA de IPv6 o dirección de bucle invertido
Tiempo de ejecución Linux para producción, macOS solo para desarrollo local

Implementación de la puerta de enlace

El siguiente procedimiento resume los pasos de inicio rápido. Para obtener instrucciones detalladas, consulte la documentación de la puerta de enlace de aplicaciones de Claude.

Para implementar la puerta de enlace de aplicaciones de Claude

  1. Registre un cliente de OAuth en el proveedor de identidades. Establezca el URI de redireccionamiento en https://claude-gateway.your-domain/oauth/callback.

  2. Aprovisione una base de datos de PostgreSQL, con cualquier instancia de PostgreSQL 14 o una versión posterior. La puerta de enlace ejecuta las migraciones del esquema durante el arranque.

  3. Escriba un archivo de configuración gateway.yaml. En el siguiente ejemplo se muestra una configuración mínima que utiliza Amazon Bedrock como servicio ascendente.

    listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]
  userinfo_fallback: true

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}
  ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}

auto_include_builtin_models: true

  4. Ejecute la puerta de enlace. Puede utilizar Docker Compose o ejecutar directamente el archivo binario.

    claude gateway --config gateway.yaml

  5. Compruebe la interfaz de autenticación. Obtenga el documento de detección, solicite la autorización del dispositivo y pruebe el inicio de sesión en el navegador mediante la URL de la puerta de enlace.

  6. Inicie sesión como desarrollador para confirmar la conectividad de extremo a extremo.

Conexión de los desarrolladores a la puerta de enlace

Para dirigir los equipos de los desarrolladores a la puerta de enlace, distribuya las siguientes claves de configuración administrada mediante la administración de dispositivos móviles (MDM) o la herramienta de administración de la configuración.

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

Después de distribuir la configuración, cada desarrollador debe completar los siguientes pasos.

Para iniciar sesión mediante la puerta de enlace

  1. Ejecute el comando /login en Claude Code.

  2. Pulse Intro en la pantalla de la puerta de enlace de Claude.

  3. Complete el inicio de sesión en el navegador mediante el IdP corporativo.

Después de iniciar sesión, Claude Code dirige la inferencia mediante la puerta de enlace, y esta exporta la telemetría a los destinos configurados.

Enrutamiento de la telemetría a Amazon CloudWatch

La puerta de enlace admite la distribución mediante OTLP/HTTP a varios recopiladores e incorpora información de identidad en las exportaciones. Configure los destinos de telemetría en el archivo gateway.yaml. Cada destino puede recibir métricas, registros o seguimientos.

Cuando configura CloudWatch como destino de telemetría, la puerta de enlace incorpora a cada exportación la identidad del desarrollador procedente del IdP. Las métricas incluyen atributos del usuario, el equipo y la organización, de modo que los mismos paneles de Información de agentes de codificación muestren datos.

Para consultar todas las opciones de configuración de la telemetría, consulte la referencia de configuración.

Disponibilidad y limitaciones

En la siguiente tabla se resume qué admite la puerta de enlace y cuáles son las limitaciones actuales.

Elemento Status
Servicios ascendentes compatibles Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud, Microsoft Foundry y la API de Anthropic
Proveedores de identidades compatibles Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex y otros proveedores compatibles con OIDC
Protocolo de telemetría OTLP/HTTP con distribución a varios destinos
Tiempo de ejecución Linux para implementaciones de producción. macOS solo es compatible con el desarrollo local.
Versión mínima de Claude Code v2.1.195

Siguientes pasos

Utilice los siguientes recursos para obtener instrucciones detalladas de implementación, opciones de configuración y orientación operativa.

Cuando la puerta de enlace comience a enviar métricas a CloudWatch, consulte los paneles como se describe en Visualización de los paneles.