Cofres de credenciais de provedor para gateways de IA multimodelos: tempo de execução, administração, cobrança e acesso BYOK separados
Um padrão prático de cofre de credenciais para gateways de IA multimodelos: classifique chaves de provedor upstream, isole o tempo de execução do acesso administrativo, vincule credenciais BYOK a locatários, alterne com segurança e audite cada decisão de credencial.
As chaves de API downstream e as credenciais do provedor upstream resolvem problemas diferentes. Uma chave de desenvolvedor emitida pelo seu gateway identifica o contexto do aplicativo, da equipe, do locatário, do orçamento e da política. Uma chave de provedor upstream permite que o gateway gaste dinheiro e acesse modelos em uma conta de provedor. Tratá-los como o mesmo tipo de segredo é como as equipes acabam com uma chave irrestrita em um projeto compartilhado, credenciais de administrador em serviços de tempo de execução e nenhuma maneira confiável de responder qual locatário causou qual cobrança do fornecedor.
O padrão prático é um cofre de credenciais de provedor: um plano de controle dedicado para importar, classificar, armazenar, selecionar, girar e auditar credenciais upstream. Ele deve ficar atrás do roteador, do livro de cobrança, do mecanismo de política e do fluxo de trabalho de operações, e não dentro do código do aplicativo, dos arquivos de configuração do modelo, dos registros do locatário ou dos eventos analíticos.
O problema do leitor: credenciais upstream tornam-se infraestrutura invisível
A maioria das implantações de vários modelos começa com um objetivo simples: encaminhar uma solicitação compatível com OpenAI para o melhor provedor disponível. Em seguida, mais contas aparecem: um projeto de fornecedor para produção, outro para avaliação, um espaço de trabalho Anthropic para uma unidade de negócios, um projeto do Google Cloud para Gemini e diversas chaves fornecidas pelo cliente para contratos BYOK.
O risco não é apenas vazamento secreto. É a perda do contexto de autorização. Uma chave de provedor válida pode ser tecnicamente capaz de chamar um endpoint, mas o gateway ainda precisa saber se essa chave é permitida para esse locatário, essa família de modelos, essa política de retenção de dados, esse orçamento, essa região e esse caminho de automação.
Fato: as plataformas dos provedores expõem diferentes limites de contas e tipos de credenciais. OpenAI documenta projetos e contas de serviço, e as permissões de chave de API da conta de serviço são padrão para acesso de leitura e gravação para os recursos de API do projeto. OpenAI também expõe objetos-chave da API Admin separadamente do uso comum da API de projeto/tempo de execução. A Anthropic documenta os espaços de trabalho como um limite organizacional e afirma que os endpoints da API Admin exigem chaves de API Admin distintas das chaves de API padrão; A Anthropic também observa que as chaves de API estão vinculadas ao espaço de trabalho onde são criadas e não podem ser movidas entre espaços de trabalho. A documentação da chave da API Gemini do Google diz que cada chave da API Gemini está associada a um projeto do Google Cloud e recomenda restrições de API para reduzir danos se uma chave for comprometida.
Recomendação: não crie um campo “provider_key” genérico e considere-o concluído. Crie um inventário de credenciais que preserve os limites específicos do provedor e exponha um modelo de política normalizado ao gateway.
Defina uma taxonomia de credenciais antes de aceitar chaves
Um cofre deve rejeitar credenciais ambíguas. No momento da importação, o operador ou fluxo de trabalho de automação deve classificar a credencial. No mínimo, use estas categorias:
- Credenciais de inferência de tempo de execução: usadas pelo gateway para chamar endpoints de inferência de modelo, como bate-papo, respostas, incorporações, moderação, transcrição ou geração de imagens, dependendo do suporte do provedor.
- Credenciais de automação de administrador: usadas para gerenciar organizações, espaços de trabalho, projetos, usuários, chaves ou recursos administrativos do lado do provedor. Eles nunca devem estar no caminho da solicitação de tempo de execução.
- Credenciais de faturamento e relatórios: usadas para recuperar uso, faturas, custos ou relatórios da organização onde os provedores oferecem suporte a essas APIs. Mantenha-os separados das chaves de inferência para que os jobs de relatório não gerem uso do modelo.
- Credenciais somente para avaliação: usadas por benchmark, controle de qualidade, migração ou fluxos de trabalho de teste. Eles devem ter cotas baixas, rótulos ambientais claros e nenhuma elegibilidade para produção alternativa.
- Credenciais BYOK do cliente: chaves fornecidas pelo cliente vinculadas a um locatário, conta de provedor, contrato e política de dados específicos. Eles não devem ser agrupados em roteamento compartilhado, a menos que o cliente aceite explicitamente.
Esta taxonomia não é apenas documentação. Deve impulsionar fluxos de trabalho de controle de acesso, elegibilidade de roteamento, alertas e rotação. Se uma credencial for importada sem categoria, proprietário, limite da conta do provedor e uso permitido, ela deverá permanecer desativada.
Armazene segredos em um cofre, não em registros de produtos
O cofre deve ser o único componente que pode descriptografar credenciais upstream. Outros sistemas podem armazenar referências, hashes, campos de status e metadados de política, mas não o valor da credencial em si.
Não armazene segredos upstream nesses locais
- Linhas de perfil do locatário.
- Arquivos de configuração de roteamento do modelo.
- Logs de prompt ou períodos de rastreamento.
- Cargas úteis de eventos de análise.
- Variáveis de CI voltadas para o desenvolvedor.
- Tíquetes de suporte, ferramentas de bate-papo ou capturas de tela.
Um projeto de vault utilizável possui dois planos. O plano secreto armazena material de credenciais criptografadas e controla rigorosamente as operações de descriptografia. O plano de metadados armazena atributos não secretos usados por roteamento e governança. O roteador geralmente precisa apenas de um ID de credencial e de uma recuperação secreta de memória de curta duração no momento do despacho, e não de amplo acesso ao banco de dados para todas as chaves do provedor.
Proteja o cofre como uma infraestrutura de alto valor: criptografia de envelope ou KMS gerenciado, identidades de serviço rigorosas, procedimentos de segurança, testes de backup e restauração, revisão de acesso e alertas sobre volumes incomuns de descriptografia. Um cofre central simplifica a governação, mas também concentra o risco. Essa é a compensação.
Anexar metadados de política a cada credencial
O modelo de metadados deve ser explícito o suficiente para que o gateway possa decidir se uma credencial é elegível antes de chegar ao endpoint do provedor.
Um registro de credencial prático inclui:
- credential_id: identificador interno imutável.
- provedor: OpenAI, Anthropic, Gemini, Azure OpenAI ou outro adaptador.
- provider_account_boundary: organização, projeto, espaço de trabalho, projeto de nuvem, assinatura ou equivalente.
- credential_class: tempo de execução, administração, faturamento, avaliação ou BYOK.
- ambiente: produção, preparação, desenvolvimento, avaliação, sandbox.
- tenant_binding: credencial de plataforma compartilhada, locatário único, grupo de locatários ou locatário BYOK do cliente.
- allowed_model_families: por exemplo, geração de texto, incorporações, visão, imagem, áudio ou perfis de modelos específicos.
- allowed_endpoints: recursos de gateway normalizados mapeados para endpoints do provedor.
- data_policy: classe de retenção permitida, classe de registro, requisito de residência e restrições de recursos.
- budget_scope: centro de custo, cliente revendedor, departamento interno ou contrato.
- proprietário: equipe nomeada ou pessoa responsável.
- criado_em, expira_at, rotação_devido_at, último_usado_at.
- health_status: desconhecido, íntegro, degradado, não autorizado, quota_exhausted, desativado.
- emergency_disable: bloqueio de roteamento imediato independente do estado normal da política.
Mantenha esse modelo neutro em termos de provedor, mas não apague a realidade do provedor. Uma chave antrópica vinculada ao espaço de trabalho e uma chave Gemini vinculada a um projeto do Google Cloud não são intercambiáveis apenas porque ambas podem gerar texto. O gateway precisa dessa procedência para auditorias, estornos e failover seguro.
Acesso separado para tempo de execução, administração e faturamento
A regra mais importante é simples: uma chave usada para inferência em tempo de execução não deve gerenciar organizações fornecedoras, espaços de trabalho, usuários, projetos ou recursos administrativos.
O tráfego em tempo de execução é de alto volume e exposto à maior superfície operacional. Ele passa por roteadores de solicitação, lógica de repetição, manipuladores de streaming, adaptadores de modelo e fluxos de trabalho de incidentes. As credenciais de administrador são de baixa frequência e alto impacto. Eles devem viver atrás de um caminho de aprovação separado com TTLs curtos, denominados aprovação humana quando apropriado, registro forte e sem elegibilidade de roteamento em tempo de execução.
As credenciais de faturamento também merecem separação. Um trabalho de relatório que reconcilia faturas não deve ser capaz de gerar conclusões, e uma chave de inferência em tempo de execução não deve ser a única maneira de recuperar relatórios de uso. Quando um provedor não oferece uma separação refinada, compense no gateway: isole a credencial, limite qual identidade de serviço interno pode recuperá-la e registre cada uso.
Recomendação: torne a classe de credencial um limite rígido de autorização, não um rótulo. Um despachante de tempo de execução não poderá solicitar a descriptografia de uma credencial de administrador, mesmo que um erro de configuração faça referência ao seu ID.
Crie um mecanismo de política de seleção de credenciais
A seleção de credenciais deve acontecer depois que o gateway autentica o chamador downstream e antes de qualquer tentativa de chamada do provedor. O mecanismo de política deve juntar diversas entradas:
- ID do locatário e escopo da chave de API downstream.
- Perfil do modelo solicitado ou ID do modelo específico do provedor.
- Capacidade de endpoint: chat, incorporações, imagem, áudio, lote, arquivos, ferramentas ou automação administrativa.
- Requisitos de retenção de dados e residência.
- Orçamento, reserva de crédito e centro de custo.
- Estado limite de taxa e pressão de cota.
- Metadados de credenciais, integridade, meio ambiente e vinculação de locatário.
O mecanismo deve retornar um dos três resultados: permitir com uma credencial selecionada, negar com um motivo de política ou exigir aprovação. As negações devem ser precisas o suficiente para que as equipes de operações resolvam o problema sem revelar material secreto aos desenvolvedores.
Exemplo de decisão:
Não implemente substituto como “tente a próxima chave”. O substituto deve executar novamente a política. Uma credencial de plataforma compartilhada pode ser válida para acesso de provedor, mas inválida para um cliente somente BYOK. Uma credencial em outro projeto pode ter cota, mas pode violar a atribuição de custos ou requisitos de retenção.
Trate o BYOK como acesso de propriedade do locatário, e não como capacidade ociosa
BYOK muda o modelo de confiança. O cliente forneceu a credencial para que seu tráfego pudesse ser cobrado, controlado ou isolado na conta do provedor. Essa credencial deve estar vinculada ao locatário do cliente e à procedência da conta do provedor.
Controles BYOK recomendados:
- Um registro do vault por cliente, provedor, limite de conta e ambiente.
- Não há roteamento entre locatários por meio de credenciais BYOK.
- Não use como capacidade substituta compartilhada, a menos que o cliente aceite explicitamente.
- Estado de integridade visível ao cliente que não revela a chave bruta.
- Fluxo de trabalho de rotação separado que permite ao cliente adicionar uma chave substituta antes que a chave antiga seja desativada.
- Atribuição clara em análises de uso e faturas: locatário do gateway, limite da conta do provedor, ID da credencial, perfil do modelo e ID de rastreamento da solicitação.
Para agências, revendedores e automação de API de parceiros, o BYOK pode ser mais complexo porque um serviço pode fornecer locatários e credenciais de maneira programática. A mesma regra ainda se aplica: a automação pode importar e vincular credenciais, mas não deve confundir a propriedade do locatário.
Adicione verificações de integridade de simulação sem vazamento de prompts
Uma credencial pode falhar por vários motivos: chave revogada, espaço de trabalho errado, falta de acesso ao modelo, faturamento desativado, esgotamento da cota, restrição de endpoint, incompatibilidade de política regional ou interrupção do provedor. Descobrir que somente após a chegada de uma solicitação de produção cria incidentes barulhentos.
Use verificações de integridade que validam a capacidade sem enviar solicitações ao cliente. Uma verificação sintética pode chamar um endpoint mínimo, listar modelos permitidos quando apropriado ou enviar um prompt fixo inofensivo se essa for a única opção prática. Mantenha esses cheques baratos, com taxas limitadas e rotulados como tráfego sintético em telemetria e faturamento.
As verificações de integridade devem ser executadas:
- Na importação de credenciais.
- Antes de ativar uma credencial para roteamento de produção.
- Após alterações nas restrições do provedor.
- Durante a mudança de rotação.
- Periodicamente para credenciais qualificadas para produção.
Compensação: verificações automatizadas detectam chaves expiradas ou com escopo insuficiente antecipadamente, mas verificações mal projetadas podem criar chamadas desnecessárias ao provedor, ruídos de faturamento ou alarmes falsos durante interrupções do provedor. Armazene o resultado de integridade com carimbo de data/hora, classe de erro do provedor, endpoint testado e família de modelos testada. Não armazene valores secretos ou solicitações confidenciais.
Gire com dois slots, não com uma substituição arriscada
A rotação de credenciais não deve ser uma operação de exclusão e reza. Use um modelo de rotação de dois slots:
- Importar credencial de substituição como inativa, com metadados completos e proprietário.
- Execute verificações de integridade sintética para os endpoints, famílias de modelos e limites de conta pretendidos.
- Ative a elegibilidade sombra para uma pequena fatia de tráfego sintético seguro ou de baixo risco, quando apropriado.
- Mudar o tráfego de produção gradualmente da credencial antiga para a nova.
- Monitore erros, latência, cota e atribuição de custos por ID de credencial.
- Congelar o substituto para a credencial antiga assim que a nova credencial estiver estável.
- Revogue a credencial antiga no provedor e marque o registro do vault como revogado.
- Verifique se nenhuma descriptografia ou chamada de provedor ocorre por meio da credencial antiga após a revogação.
Os prazos de rotação devem estar visíveis nas visualizações e alertas de operações. A rotação de emergência precisa de um caminho mais curto: desativar credenciais, bloquear roteamento, ativar substituição aprovada e preservar todos os registros de auditoria para análise de incidentes.
Restringir chaves de provedor onde o provedor oferece suporte
A política de gateway é necessária, mas as restrições do lado do provedor reduzem o raio de transmissão se uma chave for comprometida ou mal utilizada. Para Gemini e outras chaves de API de plataforma em nuvem, use restrições de API/serviço e restrições de aplicativos adequadas, quando disponíveis. Para projetos de provedores, espaços de trabalho e contas de serviço, evite privilégios organizacionais amplos quando uma chave de ambiente de execução no escopo do projeto for suficiente.
Recomendação: mantenha uma lista de verificação de restrições do lado do provedor para cada classe de credencial. A lista de verificação deve fazer parte da aprovação de importação e da rotação, e não como uma tarefa de segurança separada que pode ser ignorada sob pressão.
Compensação: as restrições do lado do provedor aumentam a sobrecarga operacional. Novos endpoints, famílias de modelos, regiões ou recursos de automação podem exigir alterações de políticas e restrições. Isso é preferível a descobrir, após um vazamento, que uma chave poderia acessar todas as cargas de trabalho em um projeto compartilhado.
Mantenha um registro de auditoria de credenciais somente para acréscimos
Uma trilha de auditoria deve responder quem importou uma credencial, o que ela tinha permissão para fazer, quais decisões de roteamento a selecionaram, quando ela falhou e quando ela foi rotacionada ou revogada.
Registre estes eventos:
- Credencial criada ou importada.
- Metadados alterados, incluindo endpoints permitidos, vinculação de locatário ou política de dados.
- Verificação de integridade executada e resultado registrado.
- Credencial selecionada pela política de roteamento para uma solicitação.
- Descriptografia de credencial solicitada por uma identidade de serviço interna.
- Falha na chamada do provedor devido a erro de autenticação, autorização, cota ou restrição.
- Rotação iniciada, tráfego alterado, credencial antiga revogada.
- Desativação de emergência ativada ou desativada.
- Credencial de administrador ou de segurança acessada.
Não coloque valores brutos de credenciais em eventos de auditoria. Use IDs de credenciais, limites de conta de provedor, IDs de rastreamento de solicitação, identidades de atores e motivos de decisão política. Para tráfego de tempo de execução de alto volume, você pode obter amostras de telemetria de descriptografia detalhada, mas a seleção de roteamento e a atribuição de custos devem permanecer completas o suficiente para faturamento e resposta a incidentes.
Lista de verificação de implementação
- Crie uma taxonomia de credenciais e rejeite importações não classificadas.
- Mova todos os segredos do provedor para um cofre criptografado dedicado.
- Armazene metadados de roteamento separadamente do material secreto.
- Faça com que as credenciais de tempo de execução, administração, faturamento, avaliação e BYOK separem classes de autorização.
- Vincule credenciais BYOK à proveniência da conta do locatário e do provedor.
- Exigir aprovação do mecanismo de política antes de selecionar qualquer credencial upstream.
- Execute verificações de integridade imediatas e seguras antes da elegibilidade para produção.
- Use rotação de dois slots com mudança gradual de tráfego e revogação do lado do provedor.
- Aplique restrições do lado do provedor sempre que disponíveis.
- Mantenha registros de auditoria somente anexados para importação, uso, falhas, rotação e revogação.
- Mantenha as credenciais de administrador atrás de controles de segurança: TTL curto, aprovação nomeada, registro forte, sem uso de tempo de execução.
Conclusão acionável
Comece inventariando todas as credenciais de provedor upstream usadas atualmente pelo gateway, scripts, trabalhos de CI, equipamentos de avaliação e automação de parceiros. Para cada um, atribua uma classe, proprietário, limite de conta do provedor, vinculação de locatário, pontos de extremidade permitidos, famílias de modelos permitidas, prazo de rotação e status de desativação de emergência. Qualquer coisa que você não possa classificar deve ser desativada ou colocada em quarentena até que tenha um propósito claro.
Em seguida, aplique uma regra arquitetônica: os desenvolvedores downstream recebem chaves com escopo de gateway; o gateway sozinho controla o acesso do provedor upstream. Essa separação permite preservar privilégios mínimos, atribuição de locatários, precisão de faturamento, roteamento de política de dados e automação segura, mesmo à medida que provedores, projetos, espaços de trabalho e clientes BYOK se multiplicam.