RAG sobre ServiceNow: o conector que apaga o user criteria

O que aconteceu

Subi o conector no dia em que ele saiu, 4 de setembro de 2026, contra uma instância de homologação carregada com um export real: cerca de 12 mil artigos espalhados por seis knowledge bases distintas e 40 mil itens de catálogo ativos. O objetivo era medir tempo de sync e qualidade de recuperação para um assistente interno de TI, o caso de uso que a própria AWS cita no anúncio.

Segui a documentação linha a linha. Propriedade glide.oauth.inbound.client.credential.grant_type.enabled em true. Conta de serviço marcada como Web service access only, sem senha interativa. Aplicação OAuth registrada pela página do interceptor, não por insert direto em oauth_entity, como o próprio guia avisa. Inbound Authentication Profile amarrado a uma REST API Access Policy sobre now/table, porque sem isso o token nasce válido e a Table API devolve 401. O passo 3 pede exatamente dois papéis: knowledge_admin e catalog_admin. Atribuí os dois, e o ServiceNow herdou por volta de quatorze papéis contidos.

O sync terminou. Fiz então a pergunta que faço em todo RAG corporativo antes de liberar qualquer coisa: perguntei ao assistente sobre um assunto que eu sabia estar restrito a um grupo específico na instância de origem. A resposta veio inteira, com citação do artigo, para uma identidade que não tinha papel nenhum lá. Não foi alucinação, foi recuperação correta de um documento que o ServiceNow jamais teria renderizado para aquele usuário.

O piloto parou ali. O que segue é o retro, sem culpado: a configuração estava certa segundo a documentação, e é exatamente esse o ponto.

A correção: escopo na ingestão, porque não há escopo na consulta

Quando a fronteira de acesso não existe no momento da recuperação, ela precisa existir antes, no que entra no índice. Foram quatro mudanças concretas.

Uma knowledge base por audiência, não uma por sistema. O Retrieve recebe um knowledgeBaseId; é a única unidade que o IAM enxerga. Separei em duas bases: uma alimentada com crawlPublicKnowledgeArticlesOnly em true, outra com inclusionKnowledgeBaseSysIds listando apenas os sys IDs cujo público coincide com um grupo do IdP. O limite de 10.000 bases por conta e por Region não é o gargalo aqui; o gargalo é operacional, e por isso a granularidade parou em audiência, não em grupo.

Autorização volta para a aplicação. A permissão bedrock:Retrieve passou a ser concedida por role distinta por audiência, com Condition sobre a tag de recurso da base. Quem responde ao usuário resolve o grupo no token do IdP e assume a role correspondente. É mais código do que eu gostaria, e é o preço de usar uma fonte sem ACL.

Filtro por sys ID deixou de ser otimização. inclusionServiceCatalogSysIds e inclusionKnowledgeArticleCategorySysIds são, ao mesmo tempo, controle de escopo e controle de tempo de sync: a documentação de troubleshooting atribui o sync de horas exatamente à ausência deles.

Deleção protegida. Liguei deletionProtectionConfiguration com deletionProtectionThreshold em 15. Se um sync tentar apagar mais de 15% do índice, o que um erro de user criteria na origem provoca com facilidade, a fase de deleção é pulada em vez de esvaziar o assistente em produção.

Identidade: o detalhe que decide se a mitigação funciona

Mesmo nos conectores que têm ACL, o modelo de identidade do Managed Knowledge Base é mais estreito do que a maioria dos desenhos corporativos assume, e vale conhecer antes de prometer segregação fina para o time de risco.

O identificador universal é o e-mail. O userContext.userId do Retrieve é sempre o e-mail do usuário, e ele precisa bater exatamente com o e-mail associado àquele usuário em cada fonte conectada. Não há resolução de alias nem mapeamento entre provedores de identidade. Se a empresa carrega dois domínios por causa de uma aquisição, metade das pessoas recebe zero resultado, e recebe em silêncio, que é o pior modo de falha possível.

Grupos vêm do último sync. A associação usuário-grupo é crawleada na ingestão e resolvida na consulta a partir desse retrato. A verificação em tempo real cobre a janela entre syncs nos quatro conectores que a suportam; credenciais de IdP terceiro ficam em cache por até uma hora, e mudanças de permissão são eventualmente consistentes, tipicamente em minutos. Para um desligamento, isso é tempo de exposição, trate a revogação como evento do IdP e do app, não da base de conhecimento.

Ausência de ACL significa inacessível, não público. Documento sem permissão extraída numa fonte com ACL habilitada não volta para ninguém, e a avaliação falha fechada: erro de resolução de grupo devolve menos resultados, nunca mais. É o comportamento certo, e é também a explicação mais comum para o chamado "o assistente ficou burro depois do deploy".

E a frase que a documentação faz questão de repetir: ACL-aware é filtragem, não autorização. Quem autentica é você.

O que passou a ser medido antes de qualquer liberação

O retro não termina em correção de configuração; termina em sinal. Um vazamento de RAG não gera erro, não gera latência anômala e não aparece em dashboard de disponibilidade, ele aparece como uma resposta útil para a pessoa errada. Três coisas entraram no checklist de release.

Suíte de consultas-canário. Um conjunto pequeno de perguntas cujas respostas corretas são silêncio, uma por audiência, executada contra cada base após todo sync. É teste de regressão de acesso, roda em segundos e custa US$ 1,00 por mil chamadas. A alternativa é descobrir pela ouvidoria.

Contagem de documentos por sync, com faixa esperada. O statistics do GetIngestionJob diz quantos documentos entraram, falharam e saíram. Uma variação brusca costuma significar mudança de escopo na origem, categoria movida, catálogo reativado, antes de significar problema de plataforma. Com deletionProtectionThreshold ligado, o sync que pularia a fase de deleção é exatamente o evento que você quer ver no alarme.

Origem dos trechos citados. Como o assistente devolve citações, o dataSourceId de cada trecho recuperado é telemetria de graça. Se uma base de audiência restrita aparece em resposta de canal aberto, o alarme dispara sem depender de alguém ler a resposta.

O conector economiza semanas de pipeline artesanal, o que ele não economiza é o desenho de quem pode ver o quê. Essa parte nunca foi terceirizável.