Controles de equipe orientados por SCIM para um gateway de API de IA: provisionar usuários, revogar chaves e manter contas de serviço em execução
Use SCIM e SSO como entradas do ciclo de vida e deixe o gateway impor funções explícitas, perfis de modelo, autoridade de gastos, propriedade de chave e regras de transferência de conta de serviço. O objetivo é a rápida desativação sem interromper os aplicativos de produção.
O desligamento de uma pessoa não deve se tornar um exercício de interrupção. Em muitas equipes, o provedor de identidade pode desabilitar o funcionário rapidamente, mas o gateway da API de IA ainda possui chaves de desenvolvedor de longa duração, scripts compartilhados, contas de serviço de produção, locatários de revendedores e privilégios de cobrança que não são mapeados corretamente para uma conta humana. O padrão prático é usar o SCIM como entrada do ciclo de vida e, em seguida, manter a autorização, a propriedade da chave, os limites de gastos, o acesso ao modelo e os registros de auditoria como objetos de gateway explícitos.
O problema: as alterações de identidade não são iguais à autorização da API
O SSO responde se um usuário pode fazer login. O SCIM ajuda a automatizar o provisionamento de usuários e grupos. Nenhum deles, por si só, responde a todas as questões operacionais que um gateway de IA deve impor: qual locatário esse usuário pode administrar, quais perfis de modelo ele pode usar, quais chaves são pessoais, quais chaves executam a produção, quem pode aprovar aumentos de orçamento e quais objetos de cliente da Partner API eles podem tocar?
Uma arquitetura limpa trata a identidade como a origem dos eventos do ciclo de vida, não como o modelo de autorização completo. O gateway deve receber alterações de usuários e grupos do provedor de identidade, normalizá-las e traduzi-las em registros nativos do gateway. Esses registros devem então ser avaliados em tempo de execução para ações administrativas, criação de chaves de API, acesso a modelos, limites de gastos, propriedade de contas de serviço e exportações de auditoria.
Fato: SCIM 2.0 é um protocolo padrão IETF para gerenciamento de identidade entre domínios. Seu comportamento de protocolo é especificado na RFC 7644 e seus esquemas de recursos são especificados na RFC 7643. O SCIM oferece às equipes uma maneira padrão de criar, atualizar, desativar e agrupar usuários entre sistemas.
Recomendação: não coloque autorização de gateway diretamente em nomes de grupos de IdP ou caminhos de solicitação. Use grupos SCIM como entradas para uma tabela de mapeamento controlada e, em seguida, avalie funções e políticas de gateway a partir de registros de propriedade do gateway.
Objetos principais que o gateway deve possuir
O gateway precisa de seu próprio modelo de autorização porque o acesso LLM combina segurança, custo e continuidade operacional. No mínimo, defina esses registros como objetos de primeira classe:
- Identidade: o usuário humano provisionado, vinculado ao assunto do IdP, e-mail, status e participação no grupo.
- Locatário ou espaço de trabalho: o limite administrativo para usuários, chaves, orçamentos, perfis de modelo, integrações e uso.
- Função: permissões de gateway, como desenvolvedor, administrador de locatário, administrador de faturamento, administrador de modelo, auditor ou administrador de API de parceiro.
- Perfil do modelo: um conjunto permitido de modelos, regras de roteamento, restrições de manipulação de dados e portas de recursos.
- Autoridade orçamentária: quem pode gastar, aumentar limites, criar chaves de alto custo ou aprovar exceções temporárias.
- Chave de API de propriedade humana: uma chave criada para uma pessoa, normalmente revogada ou suspensa quando essa pessoa sai.
- Conta de serviço: uma identidade do aplicativo com proprietários, finalidade, ambiente, metadados de rotação, carimbo de data/hora da última utilização e política anexada.
- Evento de auditoria: um registro imediatamente minimizado de decisões de identidade, função, chave, orçamento e autorização.
Essa separação torna o offboarding determinístico. Um usuário pode ficar inativo sem excluir contas de serviço que foram registradas corretamente como identidades de aplicativo. Um administrador de locatários pode perder autoridade de cobrança sem perder o acesso básico de auditoria somente leitura. Um revendedor pode gerenciar inquilinos de clientes atribuídos sem poder enumerar inquilinos não relacionados.
Fluxo de provisionamento: do evento SCIM ao acesso ao gateway
Um fluxo de provisionamento útil é chato por natureza. Deve tolerar novas tentativas, atualizações parciais e atraso na sincronização de grupos. As implementações SCIM diferem em termos de tempo, comportamento de exclusão versus desativação, mapeamentos de atributos e suporte de grupo, portanto, o gateway deve evitar suposições frágeis.
1. Ingerir e normalizar o usuário
Quando o gateway recebe um evento de criação ou atualização de usuário SCIM, ele deve atualizar o registro de identidade usando um identificador externo estável. Armazene o status do usuário, o nome de exibição, o email, o departamento ou centro de custo, se disponível, e as referências brutas do grupo IdP em um formato normalizado. Evite usar e-mail como único identificador imutável; os e-mails mudam.
Exemplos de campos de identidade normalizados:
2. Traduzir grupos em funções de gateway
Use uma tabela de tradução gerenciada por gateway. Cada linha deve vincular uma referência de grupo IdP a um locatário, uma função e perfis opcionais, como modelos permitidos ou classes de orçamento. Grupos não mapeados não devem conceder nada. Os mapeamentos privilegiados devem exigir revisão, especialmente o administrador de faturamento, o administrador do modelo, o proprietário do locatário e o administrador da API do parceiro.
Recomendação: use negação padrão para grupos não mapeados. É melhor para um grupo recém-criado não produzir acesso de IA do que herdar acidentalmente o modelo de produção ou a autoridade de cobrança porque uma string corresponde a um prefixo de caminho.
3. Materialize o acesso efetivo
Após a tradução do grupo, materialize o acesso efetivo ao gateway do usuário: associações de locatários, funções, perfis de modelo, permissões de criação de chaves, autoridade orçamentária e permissões de integração. As verificações de tempo de execução devem ler esta visualização materializada ou um serviço de autorização fortemente consistente, e não analisar strings de grupo de IdP em cada solicitação.
Isso também dá aos administradores uma análise de acesso utilizável: “mostre-me todos que podem criar chaves no locatário de suporte”, “mostre-me quem pode aumentar os limites de gastos mensais” e “mostre-me todos os usuários que podem acessar modelos de raciocínio de alto custo”.
Separar chaves humanas das contas de serviço
A distinção operacional mais importante é simples: uma chave humana representa uma pessoa; uma conta de serviço representa um aplicativo. Tratar ambas como chaves de API genéricas cria riscos de exclusão.
As chaves de propriedade humana devem herdar o ciclo de vida do usuário humano. Quando o usuário fica inativo, o gateway deve bloquear a criação de novas chaves e suspender ou revogar chaves pessoais. Essas chaves também devem ter proprietário, inquilino, perfil de modelo, perfil de orçamento, carimbo de data/hora da última utilização e metadados de finalidade para que as equipes possam ver o uso indevido antes do dia de desligamento.
As chaves da conta de serviço não devem pertencer a um funcionário que está saindo de uma forma que interrompa a produção. Uma conta de serviço deve ter pelo menos dois proprietários humanos ou um grupo de proprietários, um rótulo de ambiente, uma política de rotação, visibilidade do último uso e um perfil de política. Ele deve permanecer ativo quando um proprietário sai, desde que exista outro proprietário válido ou que exista um processo de quebra de vidro.
Fato: as principais orientações sobre nuvem geralmente desencorajam chaves de contas de serviço de longa duração não gerenciadas e recomendam exceções restritivas. O mesmo princípio se aplica às chaves de gateway de IA: mantenha as identidades dos aplicativos explícitas, com escopo definido, revisadas e alternadas.
Recomendação: se uma chave pessoal estiver sendo usada por um trabalho autônomo, não a preserve silenciosamente durante a desativação. Coloque-o em quarentena, sinalize-o como uso de produção classificado incorretamente, exija transferência de propriedade e substitua-o por uma chave de conta de serviço de acordo com a política.
Projetar o desprovisionamento como uma máquina de estado
O desprovisionamento deve ser um fluxo de trabalho, não um único comando de exclusão. Uma máquina de estado fornece ao gateway estrutura suficiente para reduzir riscos rapidamente, preservando a auditabilidade e a continuidade da produção.
Estado 1: desprovisionamento recebido
O gateway recebe um evento de desativação, exclusão, remoção de grupo ou ciclo de vida equivalente do SCIM. Registre o evento, sua origem e o acesso efetivo anterior. Como os eventos do IdP podem ser repetidos ou chegar fora de ordem, torne esta etapa idempotente.
Estado 2: usuário marcado como inativo
Defina a identidade do gateway como inativa. Bloqueie login interativo, ações administrativas, criação de novas chaves, criação de novas contas de serviço e alterações de orçamento. Isso deve acontecer antes da execução de tarefas de limpeza mais lentas.
Estado 3: chaves pessoais suspensas
Suspender chaves de propriedade humana imediatamente ou após um curto período de carência definido pela política. O padrão mais seguro é a suspensão imediata. Para experiência do desenvolvedor, o gateway pode retornar um erro de autenticação claro que aponta os administradores para o proprietário inativo, ID da chave, locatário e último uso bem-sucedido.
Estado 4: Transferência de propriedade obrigatória
Encontre recursos pertencentes ao usuário inativo: contas de serviço, locatários, perfis de modelo, integrações, contatos de cobrança, credenciais da API do parceiro e canais de alerta. Transfira a propriedade automaticamente quando existir um grupo proprietário válido. Caso contrário, coloque o recurso em uma fila de “proprietário necessário”.
Estado 5: Notificações e Revisão
Notifique proprietários de locatários, administradores de segurança ou administradores de cobrança. A notificação deve incluir as chaves afetadas, os últimos carimbos de data/hora usados, o uso nos últimos 30 e 90 dias, as contas de serviço que precisam de um novo proprietário e todas as chaves pessoais que atenderam recentemente ao tráfego de produção.
Estado 6: Finalização
Depois que as regras de retenção permitirem, finalize a exclusão ou o anonimato dos atributos do usuário, preservando os registros de auditoria necessários. A auditoria do ciclo de vida da identidade geralmente não requer prompts brutos. Armazene eventos minimizados por prompt que descrevem a decisão política, IDs de objeto, ator, locatário, carimbo de data/hora e resultado.
O acesso ao modelo e os limites de gastos pertencem à mesma revisão
A autorização do gateway de IA não envolve apenas quem pode chamar um endpoint. Um usuário pode ter permissão para chamar modelos de baixo custo para desenvolvimento, mas não modelos de raciocínio de alto custo, ferramentas hospedadas, trabalhos em lote ou aliases de produção. Um usuário pode ter permissão para gastar com o orçamento da equipe, mas não aprovar um aumento no orçamento.
Para cada função efetiva, defina o custo relacionado e as permissões do modelo:
- Perfis de modelo e aliases internos permitidos.
- Custo máximo estimado por solicitação.
- Perfil de orçamento mensal ou diário.
- Permissão para criar chaves pessoais.
- Permissão para criar ou possuir contas de serviço.
- Permissão para usar ferramentas hospedadas, processamento de arquivos, sessões em tempo real ou cargas de trabalho em lote.
- Permissão para visualizar análises de uso, faturas ou exportações de centro de custo.
Recomendação: crie uma exportação de revisão de acesso que reúna identidade, funções de gateway, chaves ativas, contas de serviço, uso nos últimos 30 e 90 dias, permissões de modelo e autoridade orçamentária. Isso é mais útil do que uma simples lista de usuários porque mostra o risco operacional e o poder de compra juntos.
API de parceiro e autorização multilocatário
A automação da API do parceiro adiciona outro limite de autorização. Uma agência, revendedor ou plataforma pode fornecer locatários, usuários, chaves, orçamentos e exportações de uso de clientes por meio de uma API. Os usuários internos orientados pelo SCIM não devem obter automaticamente amplo acesso ao objeto do cliente apenas porque administram o próprio locatário do parceiro.
Faça com que cada operação da Partner API tenha como escopo o chamador e o locatário do cliente. O provisionamento deve ser idempotente: criar o mesmo locatário de cliente, mapeamento de grupo ou usuário duas vezes deve convergir para um estado esperado. A listagem de endpoints deve retornar apenas objetos que o chamador tem permissão explícita para administrar.
Isso é importante porque falhas de autorização no nível do objeto e na propriedade do objeto são riscos comuns da API. Em um gateway de IA, os objetos expostos são confidenciais: registros de locatários, chaves de API, livros de uso, orçamentos, permissões de modelo, listas de membros e contas de serviço. O gateway deve testar esses caminhos com diversas identidades e vários IDs de locatário, não apenas com um administrador de caminho feliz.
Testes úteis incluem:
- O administrador do locatário A tenta ler, alternar ou revogar as chaves do locatário B.
- O usuário suspenso tenta uma chave de API pessoal antiga.
- O administrador do revendedor tenta enumerar inquilinos de clientes que não são de sua propriedade.
- O membro do projeto tenta modificar as configurações de faturamento.
- O proprietário da conta de serviço tenta se conceder administrador de faturamento.
- A credencial da API do parceiro tenta alterar perfis de modelo fora do escopo permitido do cliente.
Auditoria sem acumulação imediata
As investigações do ciclo de vida da identidade geralmente precisam saber quem alterou o acesso, qual política foi avaliada, qual objeto foi afetado e se a ação foi bem-sucedida. Eles geralmente não exigem prompts brutos. Mantenha um fluxo de auditoria separado para decisões de identidade e políticas.
Registre eventos como:
- Usuário provisionado, atualizado, desativado ou excluído.
- Grupo mapeado, não mapeado ou rejeitado.
- Função de gateway concedida, alterada ou removida.
- Chave pessoal criada, suspensa, revogada ou usada após a desativação.
- O proprietário da conta de serviço foi alterado.
- Autoridade orçamentária concedida ou removida.
- Perfil do modelo anexado ou desanexado.
- Solicitação de API do parceiro negada devido ao escopo do locatário.
Cada evento deve incluir ator, sujeito, inquilino, tipo de objeto, ID do objeto, sistema de origem, decisão, código de razão e carimbo de data/hora. Use IDs estáveis em vez de conteúdo de prompt bruto. Quando forem necessários detalhes da carga útil, armazene metadados de política estruturados em vez de entradas de modelo.
Lista de verificação de implementação
Use esta lista de verificação ao implementar controles de equipe orientados por SCIM em um gateway de IA:
- Defina objetos nativos de gateway para locatário, função, usuário, chave, conta de serviço, perfil de modelo, perfil de orçamento e acesso de integração.
- Armazene o assunto do IdP externo separadamente do e-mail.
- Tornar os upserts de usuários e grupos do SCIM idempotentes.
- Use uma tabela revisada de tradução de grupo para função com comportamento de negação padrão.
- Exigir aprovação explícita para mapeamentos de funções privilegiadas.
- Distinguir chaves de propriedade humana de chaves de conta de serviço no esquema e na IU.
- Bloqueie usuários inativos de login, ações administrativas, criação de chaves e alterações de orçamento.
- Suspender chaves pessoais durante o desprovisionamento.
- Transfira ou coloque em quarentena recursos pertencentes a usuários inativos.
- Exigir que as contas de serviço tenham metadados do proprietário, finalidade, ambiente, carimbo de data/hora da última utilização e metadados de rotação.
- Junte-se às análises de acesso com análises de uso e autoridade orçamentária.
- Teste a autorização em nível de objeto entre locatários, clientes, usuários, chaves e objetos de cobrança.
- Mantenha os registros de auditoria de identidade minimizados por padrão.
Compensações
O SCIM reduz o desvio de acesso manual, mas não elimina a necessidade de autorização específica do gateway. Diferentes provedores de identidade lidam com sincronização, exclusões, desativações, novas tentativas e mapeamento de atributos de grupos de maneira diferente. O gateway deve tolerar informações parciais e convergir com segurança.
A revogação imediata da chave pessoal reduz o risco de desligamento, mas pode expor a má higiene operacional quando uma chave do desenvolvedor foi usada por um trabalho autônomo. Isso não é motivo para manter as chaves pessoais vivas indefinidamente. Esse é um motivo para detectar antecipadamente o uso da produção de chaves pessoais e migrá-lo para contas de serviço antes que um funcionário saia.
Mapeamentos de grupos detalhados podem expressar uma governança precisa, mas muitos grupos tornam-se difíceis de auditar. Um conjunto menor de funções de gateway, combinado com perfis de modelo e perfis de orçamento, geralmente é mais fácil de operar.
As contas de serviço mantêm os aplicativos em execução, mas podem ficar sem propriedade ou com privilégios excessivos. Exija proprietários, datas de revisão, metadados de rotação, perfis de modelo com escopo, orçamentos com escopo e análises usadas pela última vez.
Predição: as análises de acesso ao gateway de IA combinarão cada vez mais identidade, uso, autoridade de gasto e permissões de modelo em um único relatório. Analisar “quem tem acesso” sem mostrar “o que eles podem gastar e quais chaves ainda estão ativas” será muito superficial para as equipes que executam cargas de trabalho de IA de produção.
Conclusão prática
O padrão durável é permitir que o SCIM e o SSO conduzam o ciclo de vida e, em seguida, permitir que o gateway possua autorização. Provisione usuários do provedor de identidade, traduza grupos por meio de mapeamentos revisados, materialize funções de locatário, vincule modelos e perfis de orçamento explicitamente e trate chaves humanas de maneira diferente das contas de serviço.
Para offboarding, use uma máquina de estado: receba o evento de identidade, marque o usuário como inativo, bloqueie novo acesso, suspenda chaves pessoais, transfira ou coloque em quarentena recursos de propriedade, notifique os proprietários e finalize a exclusão depois que as regras de retenção permitirem. Isso dá às equipes de segurança uma revogação rápida, dá continuidade à produção das equipes de plataforma e dá às finanças e aos auditores um registro claro de quem tinha autoridade sobre modelos, gastos, chaves e locatários.