O problema que o Claude Apps Gateway resolve
Quando uma empresa começa a distribuir o Claude Code e o Claude Desktop para dezenas ou centenas de desenvolvedores, surgem perguntas que não têm resposta fácil sem uma camada de controle dedicada: quem está usando qual modelo? Quanto cada time está gastando? Como revogar acesso imediatamente quando alguém sai da empresa? Como garantir que contratados não acessem modelos mais caros que o necessário?
O Claude Apps Gateway foi criado exatamente para isso. Trata-se de uma camada de governança self-hosted que fica entre essas aplicações e o Amazon Bedrock (ou o Claude Platform on AWS), centralizando autenticação, políticas de acesso, telemetria e controle de custos em um único ponto. A AWS publicou agora uma referência completa de implantação em produção, expandindo o post de lançamento inicial com arquitetura detalhada, padrões corporativos e recursos de implementação.
Arquitetura de referência
O gateway é distribuído dentro do mesmo binário da CLI do Claude Code. Iniciado com o comando claude gateway --config gateway.yaml, ele opera em modo servidor e carrega sua configuração YAML na inicialização. Na implantação de referência, o container roda no AWS Fargate dentro de uma nuvem privada virtual (VPC), mas a mesma imagem pode ser executada no Amazon Elastic Kubernetes Service (Amazon EKS) ou no Amazon Elastic Compute Cloud (Amazon EC2), dependendo do ambiente existente.
Os principais componentes da arquitetura são:
- Computação e estado: cada tarefa do Fargate executa um container stateless do gateway. O Amazon Relational Database Service (Amazon RDS) para PostgreSQL armazena o estado de autenticação de curta duração — códigos de dispositivo, sessões, contadores de gasto por usuário e registros de auditoria. Como o estado vive no banco e não no container, qualquer tarefa pode atender qualquer requisição, sem necessidade de sessões fixas no balanceador.
- Entrada e DNS privado: um Application Load Balancer (ALB) interno encerra o TLS usando um certificado do AWS Certificate Manager. Uma zona hospedada privada do Amazon Route 53 resolve o endereço do gateway para IPs privados acessíveis via VPN, AWS Direct Connect ou conectividade privada equivalente.
- Conectividade de serviços: endpoints de VPC mantêm o tráfego de serviços AWS no perímetro privado, enquanto um NAT gateway fornece o egresso externo necessário.
- Credenciais upstream: o gateway se autentica no Amazon Bedrock usando a role do AWS Identity and Access Management (IAM) atribuída à tarefa. A chave de API do Claude Platform on AWS e outras credenciais estáticas ficam no AWS Secrets Manager. Nenhuma credencial upstream chega às máquinas dos desenvolvedores.
Nota operacional importante: o timeout de inatividade do load balancer deve ser configurado para superar o maior intervalo esperado sem dados. O padrão é 60 segundos — conexões ociosas além desse limite são encerradas. Vale verificar tanto respostas não-streaming com atraso quanto pausas entre chunks em respostas streaming.
Fluxo de requisições
O fluxo tem duas etapas distintas. No login (uma vez por sessão), o time de plataforma distribui configurações gerenciadas (managed settings) que apontam o Claude Code e o Claude Desktop para a URL privada do gateway. Quando o desenvolvedor executa /login, o cliente inicia o fluxo OAuth 2.0 de autorização de dispositivo e abre o navegador para autenticação via provedor de identidade OpenID Connect (OIDC). Após autenticação, o gateway emite um token de curta duração (válido por 1 hora por padrão), com renovação silenciosa em background.
Nas requisições de inferência, cada chamada carrega o bearer token. O gateway o valida, resolve identidade e grupos do desenvolvedor, aplica a política correspondente, avalia o limite de gasto e roteia a requisição para o Amazon Bedrock ou Claude Platform on AWS. A resposta retorna em streaming. As métricas de uso são encaminhadas via Protocolo OpenTelemetry (OTLP) para o coletor configurado, atribuídas à identidade autenticada.
Scripts de implantação e templates de configuração estão disponíveis no repositório de acompanhamento. Orientações operacionais detalhadas estão no guia de implantação. Detalhes sobre o ciclo de vida dos tokens estão na documentação do Claude Apps Gateway.
As cinco capacidades de governança
1. Autenticação com Login Único (SSO)
O gateway delega a autenticação ao provedor de identidade OIDC da empresa. Os desenvolvedores fazem login uma única vez via SSO no navegador. Provedores compatíveis incluem Okta, Microsoft Entra ID, Auth0, Keycloak e Amazon Cognito.
O gateway não mantém diretório de usuários próprio — não há contas para pré-criar nem sincronização SCIM para configurar. Os grupos que o provedor de identidade atribui ao usuário são os mesmos usados para correspondência de políticas, sem camada de tradução. O desligamento de um colaborador é simplesmente removê-lo do provedor: a sessão expira dentro do tempo configurado (1 hora por padrão), sem necessidade de rotacionar credenciais.
Exemplo de configuração com Microsoft Entra ID:
oidc:
issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
client_id: ${OIDC_CLIENT_ID}
client_secret: ${OIDC_CLIENT_SECRET}
allowed_email_domains: [company.com]
groups_claim: rolesAtenção: o Microsoft Entra ID não inclui claims de grupo ou role por padrão. Se as políticas usarem match: {groups: [...]} com roles do Entra, é necessário adicionar groups_claim: roles à configuração OIDC. Sem isso, o gateway não consegue resolver membros de grupo e todos os usuários correspondem apenas à política catch-all. Para instruções específicas por provedor, consulte o guia de configuração de provedores de identidade.
2. Políticas centralizadas de acesso a modelos
O gateway aplica o controle de acesso a modelos no lado do servidor e distribui permissões de ferramentas como configurações gerenciadas, com escopo por grupo do provedor de identidade. As políticas são avaliadas na ordem de declaração — a primeira correspondência é selecionada e mesclada com a política base match: {}. Sempre inclua uma política match: {} ao final como catch-all; sem ela, usuários sem correspondência recebem acesso irrestrito ao catálogo.
Managed:
policies:
# Contratados: apenas Haiku, sem acesso à web
- match: { groups: [contractors] }
cli:
availableModels: [claude-sonnet-5, claude-haiku-4-5]
enforceAvailableModels: true
permissions:
deny: ["WebFetch", "WebSearch"]
# Engenheiros: acesso completo com restrições
- match: { groups: [engineers] }
cli:
availableModels: [claude-opus-4-8, claude-sonnet-5, claude-haiku-4-5]
permissions:
allow: [Read, Grep, Bash, Edit]
deny: ["Read(./.env)", "Read(./secrets/**)"]
# Catch-all: todos os outros usuários autenticados. Deve ser o último.
- match: {}
cli:
availableModels: [claude-haiku-4-5, claude-sonnet-5]O controle de modelos é aplicado no servidor. Um desenvolvedor cujo grupo permite apenas Claude Haiku não consegue contornar a restrição, mesmo com um cliente modificado. O seletor de modelos no Claude Code e no Claude Desktop exibe apenas os modelos permitidos. Alterações propagam para clientes conectados em até uma hora, sem ação necessária dos desenvolvedores.
Atenção: inclua desktop: {} em cada entrada de política para habilitar clientes Claude Desktop. Sem isso, o gateway rejeita requisições de inferência do Desktop para usuários que correspondem àquela política, mesmo que o login tenha sido bem-sucedido. Para o schema completo de políticas, consulte a referência de configuração.
3. Telemetria e atribuição por usuário
O cliente emite métricas de uso (claude_code.token.usage, claude_code.cost.usage e claude_code.active_time.total) atribuídas à identidade do desenvolvedor autenticado: ID de usuário, e-mail e grupos. O gateway repassa essa telemetria via Protocolo OpenTelemetry (OTLP) para o coletor configurado. Backends compatíveis incluem Datadog, Splunk, Grafana e Amazon CloudWatch via coletor AWS Distro for OpenTelemetry (ADOT).
telemetry:
forward_to:
- url: https://otel-collector.internal.example.com
metrics: true
logs: false
traces: falseLogs e traces são opt-in porque podem conter código-fonte e conteúdo de prompts. A maioria das implantações começa apenas com métricas, que fornecem breakdowns de custo e uso por usuário sem expor dados sensíveis. Mais detalhes na página de configuração do Claude Apps Gateway.
4. Roteamento com failover
O gateway roteia inferência para um ou mais upstreams na ordem declarada, com failover automático em caso de indisponibilidade, throttling ou timeout. É possível combinar Amazon Bedrock em múltiplas regiões e Claude Platform on AWS:
upstreams:
# Amazon Bedrock (usa a role da task ECS, sem chaves estáticas)
- name: bedrock-east
provider: bedrock
region: us-east-1
auth: {}
# Amazon Bedrock em segunda região para failover
- name: bedrock-west
provider: bedrock
region: us-west-2
auth: {}
# Claude Platform on AWS (fallback entre provedores)
- name: claude-platform
provider: anthropicAws
region: us-east-1
workspace_id: wrkspc_01ABCDEFGHIJKLMN
auth:
api_key: ${ANTHROPIC_AWS_API_KEY}Atenção: failover entre provedores diferentes pode alterar os termos de serviço aplicáveis e a geografia de processamento de dados. Para o schema completo de upstreams, consulte a referência de upstreams.
5. Limites de gasto por usuário
Enquanto o AWS Budgets e o AWS Cost Explorer oferecem visibilidade no nível de conta com agregação periódica, o gateway complementa essas ferramentas com enforcement inline antes da inferência ocorrer. Os limites operam em três níveis: padrão organizacional, por grupo e por usuário (com precedência nessa ordem, do mais específico para o mais geral). Cada limite se aplica individualmente por desenvolvedor, não como pool compartilhado.
# Padrão organizacional: $500/mês por desenvolvedor (valores em centavos de USD)
curl -X POST https://<gateway>/v1/organizations/spend_limits \
-H "x-api-key: $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"scope":{"type":"organization"},"amount":"50000","period":"monthly"}'
# Limite mais restritivo para um grupo: $10/dia para contratados
curl -X POST https://<gateway>/v1/organizations/spend_limits \
-H "x-api-key: $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"scope":{"type":"rbac_group","rbac_group_id":"contractors"},"amount":"1000","period":"daily"}'
# Bloqueio imediato de um usuário: limite zerado
curl -X POST https://<gateway>/v1/organizations/spend_limits \
-H "x-api-key: $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"scope":{"type":"user","user_id":"<oidc-sub>"},"amount":"0","period":"daily"}'Quando o desenvolvedor atinge o teto, o gateway retorna HTTP 429 imediatamente. Os contadores resetam automaticamente no início de cada período (diário, semanal ou mensal). Os limites de gasto são gerenciados exclusivamente via Admin API — não há interface gráfica. Times de plataforma tipicamente automatizam isso com um script que sincroniza limites de um arquivo de configuração versionado como parte do pipeline de deploy, ou via Terraform chamando a API.
Limitações importantes: o gasto é estimado com base em contagens de tokens pelo preço de tabela — é um circuit breaker em tempo real, não uma fatura. Descontos por uso comprometido e taxas negociadas não são refletidos. Se o banco de dados estiver indisponível, o enforcement falha aberto por padrão (inferência continua). Organizações que precisam de enforcement estrito podem configurar fail_closed_on_error: true para bloquear requisições. Para faturamento definitivo, reconcilie com os logs de invocação do Amazon Bedrock ou o AWS Cost and Usage Report. Detalhes completos na documentação de limites de gasto.
Padrões de implantação
A forma de implantar o gateway depende da estrutura da organização, dos padrões de tráfego e dos requisitos de governança. Não existe uma arquitetura única correta. A AWS descreve cinco padrões principais:
Padrão A: Time único, região única
Recomendado para times avaliando o gateway ou organizações com um único grupo de desenvolvimento em uma região. Implantação mínima: um upstream Amazon Bedrock em us-east-1, um limite de gasto diário organizacional e todos os desenvolvedores com o mesmo acesso a modelos. Ponto de partida ideal — adicione complexidade conforme o caso de uso exigir.
Padrão B: Multi-time com acesso diferenciado
Indicado para organizações com múltiplos times que precisam de níveis diferentes de acesso a modelos e limites de gasto. Os grupos do provedor de identidade direcionam políticas diferenciadas. Por exemplo: engenharia de plataforma com acesso a Opus + Sonnet + Haiku e $50/dia; desenvolvedores de aplicação com Sonnet + Haiku e $20/dia; contratados apenas com Haiku, $5/dia e ferramentas web bloqueadas. Os limites de grupo são herdados individualmente por cada desenvolvedor, não como orçamento compartilhado.
Padrão C: Amazon Bedrock + Claude Platform on AWS (híbrido)
Ideal para organizações que querem o Amazon Bedrock como upstream preferencial com o Claude Platform on AWS como capacidade de overflow. As requisições vão primeiro para o Bedrock; somente em caso de rate limit ou indisponibilidade o gateway faz fallback para o Claude Platform on AWS.
Padrão D: Gateway para ferramentas de desenvolvimento, Bedrock direto para aplicações
Recomendado para organizações onde as ferramentas de desenvolvimento precisam de governança (SSO, limites de gasto, telemetria), mas as aplicações de produção chamam o Amazon Bedrock diretamente com cotas isoladas e acesso a funcionalidades nativas como Amazon Bedrock Knowledge Bases, Agents e Flows — que o gateway não faz proxy.
Padrão E: Multi-conta (serviços compartilhados)
Recomendado para organizações onde um time central de plataforma opera o gateway e unidades de negócio individuais possuem seu próprio acesso ao Amazon Bedrock em contas separadas. O faturamento cai na conta de cada time; o gateway roteia para o upstream correto com base na configuração de modelos.
upstreams:
- name: team-alpha
provider: bedrock
region: us-east-1
auth:
aws_access_key_id: ${TEAM_ALPHA_AKID}
aws_secret_access_key: ${TEAM_ALPHA_SK}
- name: team-beta
provider: bedrock
region: us-east-1
auth:
aws_access_key_id: ${TEAM_BETA_AKID}
aws_secret_access_key: ${TEAM_BETA_SK}Atenção: o gateway não assume nativamente uma role IAM diferente por upstream. O roteamento multi-conta requer credenciais explícitas na configuração de upstreams. Armazene essas credenciais no AWS Secrets Manager e rotacione-as periodicamente. Chaves de acesso de longa duração representam um tradeoff significativo de segurança. Considere um processo externo que atualize periodicamente credenciais de curta duração do AWS Security Token Service (AWS STS) no ambiente do gateway para reduzir a exposição.
Como começar
O Claude Apps Gateway entrega cinco capacidades — autenticação SSO, políticas de modelos por grupo, telemetria por usuário, roteamento multi-região com failover e limites de gasto — em um único container e um arquivo YAML. Não há taxa por assento. Quando o Amazon Bedrock é o upstream, nenhum dado dos desenvolvedores sai da conta AWS. Os desenvolvedores continuam usando o mesmo binário claude que já conhecem; o gateway é invisível para eles após o login inicial.
Para começar, clone o repositório no GitHub e escolha uma de duas trilhas — ambas provisionam o mesmo deployment no Amazon ECS Fargate: um ALB interno, Amazon RDS para PostgreSQL, ECR, Secrets Manager, uma role IAM para a task e um coletor de telemetria ADOT. A escolha é entre o script idempotente setup.sh, para visibilidade total de cada chamada AWS, ou um stack do AWS Cloud Development Kit (AWS CDK) para um ciclo de vida gerenciado. Para detalhes de configuração, consulte a documentação do Claude Apps Gateway.
Fonte
Deploying Anthropic Claude apps gateway for AWS for enterprise workloads (https://aws.amazon.com/blogs/machine-learning/deploying-anthropic-claude-apps-gateway-for-aws-for-enterprise-workloads/)
Leave a Reply