Autorização de Granularidade Fina: Quão Fina É o Suficiente?

O que a autorização de granularidade fina realmente significa

A autorização de granularidade fina diz respeito ao tamanho do elemento sobre o qual você está decidindo, e não ao mecanismo que você usa para decidir. A autorização genérica (coarse) pergunta: “esta identidade pode usar o gateway de IA?”. A autorização de granularidade fina pergunta: “esta identidade pode chamar a ferramenta delete_issue no servidor MCP do Linear, agora mesmo, para esta pessoa?”.

Essa transição ocorre ao longo de quatro dimensões independentes, que valem a pena ser separadas porque possuem custos diferentes:

A maioria dos artigos sobre controle de acesso de granularidade fina reduz essas dimensões a um único controle deslizante rotulado como “mais seguro” e o ajusta no máximo. Esse é o erro. A granularidade de sujeito e de ação é quase gratuita — um usuário em vez de um grupo, uma permissão em vez de um pacote, não custa nada no momento da revisão. A granularidade de recurso e de ocasião é onde a conta realmente chega.

A granularidade também é ortogonal à escolha entre RBAC e ABAC. Funções simples expressam permissões muito finas se você delimitar as vinculações (bindings) com precisão, e políticas de atributos podem ser desesperadoramente genéricas. O modelo é a forma como você decide; a granularidade é aquilo sobre o qual você decide.

O custo que ninguém calcula

A matemática é simples: quarenta engenheiros e uma permissão em todo o gateway dão a uma revisão de acesso 40 estados para confirmar. Delimite essa permissão por recurso em 12 servidores MCP e você terá 480 estados. Passe para o nível de ferramenta, com 25 ferramentas por servidor, e você terá 12.000 células. Adicione aprovação por invocação e o objeto de revisão deixa de ser uma grade — torna-se um log de eventos.

Ninguém audita 12.000 células. Em vez disso, o verdadeiro risco da supergranularidade se concretiza:

• O modelo passa a ser aproximado. Os revisores param de checar as células e passam a checar apenas os nomes das funções (roles), fazendo com que as permissões subjacentes sofram desvios não observados.
• Alguém cria um atalho (escape hatch). Uma conta de serviço compartilhada com acesso amplo surge, porque o caminho correto exige três aprovações e um chamado. Todos os controles no caminho rigoroso tornam-se meramente decorativos.
• As concessões se acumulam. Concessões de granularidade fina são individualmente pequenas, então ninguém sente o peso de deixar uma ativa. Concessões genéricas são revogadas porque são visíveis.
• A fila de aprovação vira um carimbo automático. Coloque aprovação em tudo e os aprovadores clicarão sem ler — o que é pior do que não ter controle algum, pois agora existe um registro assinado dizendo que um humano concordou.

Portanto, a restrição é a capacidade de resposta (answerability). Em qualquer degrau, você deve ser capaz de responder a três perguntas sem precisar executar um job: quem pode acessar este recurso, o que pode fazer com ele e quando o fez pela última vez. Quebre isso e você terá comprado precisão ao custo da visibilidade.

É por isso também que permissões de menor privilégio (least privilege) e granularidade máxima não são o mesmo objetivo. O menor privilégio concede apenas a autoridade necessária para a função; não exige que ela seja dividida o máximo que o sistema permitir. Uma função que possui exatamente as sete permissões de que um job precisa é de menor privilégio. Setecentas concessões separadas que somam essa mesma autoridade são apenas caras.

A escala da granularidade

Quatro degraus, do genérico ao fino, cada um com uma função específica. A regra é permanecer no degrau mais baixo que contenha o risco.

Duas propriedades tornam esse estrutura uma escala, e não um menu.

Os degraus se compõem de cima para baixo, e não para os lados. O Degrau 3 só importa para identidades que passaram pelo Degrau 2, e uma ferramenta desabilitada é inacessível, independentemente da função que alguém possua. Você pode ser generoso em um degrau genérico e rígido em um fino, e a rigidez será mantida.

Cada degrau possui um formato diferente de registro. Os Degraus 1 e 2 são tabelas que você lê. O Degrau 3 é uma lista que você compara com a do trimestre anterior. O Degrau 4 é um log do qual você retira amostras. Tratar o Degrau 4 como uma tabela é a razão pela qual as equipes terminam com duzentas políticas que ninguém consegue resumir.

Onde as equipes erram

Usar o degrau 1 para fazer o trabalho do degrau 2. De longe, o erro mais comum. Alguém precisa de um servidor MCP, então recebe uma função em todo o tenant contendo mcp-server:ReadMcpServer — o que concede acesso a todos os servidores MCP do tenant. A concessão parece restrita porque a lista de permissões é curta. Mas não é.

Subir para o degrau 4 para evitar uma discussão sobre o degrau 2. Políticas de aprovação são atraentes porque adiam a decisão. No entanto, uma barreira em uma ferramenta que as pessoas erradas nem deveriam acessar é apenas um portão em frente a uma porta aberta. Corrija a vinculação (binding) primeiro.

Tratar alternadores no nível de ferramenta como uma barreira contra chamadores não confiáveis. Desabilitar uma ferramenta a remove da descoberta e bloqueia a invocação — excelente contra um agente que, de outra forma, escolheria algo perigoso em uma lista longa. Mas isso não substitui as permissões do próprio sistema de origem na credencial.

Nunca revisar os degraus mais finos. Concessões genéricas são revisadas porque são visíveis. Uma ferramenta habilitada para uma migração pontual há oito meses torna-se invisível. Audite as listas de ferramentas habilitadas na mesma frequência com que audita as funções.

Quer ver a escala em um único console?

Restrinja uma função a um único recurso e desabilite uma ferramenta nele — leva cerca de cinco minutos do início ao fim.

Comece gratuitamente

Como a escala funciona na TrueFoundry

A TrueFoundry implementa todos os quatro degraus. Um sujeito (usuário, equipe, conta virtual ou agente) mais um recurso mais uma função (role) formam uma vinculação de função (role binding), gerenciada de forma independente da configuração do recurso — permitindo alterar quem pode acessar algo sem precisar fazer o redeploy do recurso.

Degrau 1 — capacidade em todo o tenant

Três funções de tenant vêm integradas: Admin (controle total, não editável), Member (a linha de base padrão e editável) e Read-Only Member (somente leitura, também fixa).

Quando essas opções forem muito amplas ou muito restritas, crie uma função personalizada em Access > Custom Roles. O catálogo é a essência das permissões de granularidade fina aqui: cada entrada é uma chave recurso:Ação agrupada por tipo de recurso, e a nomenclatura indica a granularidade existente antes mesmo de você projetar qualquer coisa.

Criar um servidor MCP e gerenciar um são chaves separadas. Essas divisões fornecem ao design do modelo de autorização sua resolução utilizável.

Uma regra governa este degrau: as permissões de funções personalizadas se aplicam a todos os recursos do tipo selecionado. Para um único recurso, use a página de Access Control desse recurso específico. Fazer o inverso é cometer o erro do degrau 1 fazendo o trabalho do degrau 2 citado anteriormente.

Degrau 2 — funções por recurso

Abra o menu de três pontos do recurso e selecione Access Control.

Escolha os sujeitos e uma função. O painel lateral lista as ações que cada função inclui, para que você veja a concessão antes de confirmá-la.

As funções dependem do recurso: Manager e User em uma conta de provedor; MCP Server Manager, MCP Server User e MCP Server Approver em um servidor MCP; Agent Manager e Agent Access em um agente; níveis de admin, member e viewer em clusters e workspaces. Conceder permissão a uma equipe é melhor do que conceder a uma pessoa — novos membros a herdarão automaticamente, e a tabela de concessões permanecerá curta o suficiente para ser lida. O modelo de controle de acesso do MCP é construído sobre este degrau.

Degrau 3 — por ferramenta dentro de um recurso

Este é o degrau que as equipes demoram mais para adotar, mas do qual os agentes mais precisam. Em um servidor MCP remoto ou gerenciado pela TrueFoundry, a guia Tools controla quais ferramentas podem ser chamadas.

Ferramentas desabilitadas são omitidas das respostas de tools/list e não podem ser invocadas. Ambas as partes contam: o modelo não pode escolher o que nunca vê, e o gateway recusa a chamada se algo tentar chamá-la mesmo assim.

O alternador Enable new tools by default define a linha de base e é uma escolha real de arquitetura. Ativado, a lista funciona como uma lista de bloqueio (denylist) e novas ferramentas do fornecedor aparecem automaticamente. Desativado, funciona como uma lista de permissão (allowlist) e novas ferramentas de origem permanecem ocultas até que alguém as habilite. A lista de permissão é a opção correta para qualquer coisa que toque em produção.

A opção Edit Tool faz algo mais sutil. Além de permitir a substituição da descrição, você pode definir as MCP Tool Annotations como None, Read-only ou Destructive, o que ajusta readOnlyHint ou destructiveHint.

Essa anotação é o rótulo que o degrau 4 lê, fazendo com que uma classificação feita uma única vez se torne uma política contínua sem a necessidade de nomear ferramentas duas vezes.

Degrau 4 — aprovação por invocação

As políticas de aprovação de ferramentas retêm uma chamada de tools/call no gateway, criam uma solicitação pendente e notificam os aprovadores. A ferramenta não é executada. Uma vez aprovada, as chamadas são bem-sucedidas dentro de uma janela de validade; após esse período, uma nova aprovação é necessária.

Dois controles definem a granularidade, e ambos possuem regras de precedência documentadas:

As concessões são restritas ao solicitante, ao servidor específico e à ferramenta, e não são compartilhadas entre usuários. Os aprovadores trabalham a partir de Pending Requests, que exibe a ferramenta, a política, o solicitante, a janela de validade e os argumentos da ferramenta.

Quem pode fazer o quê aqui também é dividido entre os degraus. Apenas administradores do tenant criam, atualizam ou excluem políticas. Aprovar ou negar exige perfil de admin do tenant ou a função MCP Server Approver naquele servidor, adicionada a partir de sua lista de Collaborators.

Se um servidor especificado por uma política não tiver colaboradores com a função Approver, apenas os administradores do tenant poderão decidir — uma maneira silenciosa de canalizar todas as aprovações para três pessoas sobrecarregadas.

Um limite importante: uma negação não é um bloqueio definitivo. Ela é registrada e a chamada seguinte gerará uma nova solicitação. Para interromper o acesso de forma duradoura, desça na escala — remova o acesso do sujeito ao servidor ou desabilite a ferramenta. O Degrau 4 governa ocasiões, não autoridade.

Exemplo prático: leitura versus uso em um grupo de secrets

Grupos de secrets mostram claramente por que a granularidade de ação vale a pena, pois o objetivo é separar a visualização de um valor da dependência em relação a ele.

Um grupo de secrets organiza secrets relacionados para que você gerencie o acesso uma única vez, e não por secret. Quando você salva um secret, o valor vai para o seu próprio gerenciador de secrets — AWS SSM, GCP Secret Manager, HashiCorp Vault, Azure Vault — e a TrueFoundry armazena um nome totalmente qualificado (FQN) que você referencia em implantações, montagens de volume, integrações e chaves de API de modelos no gateway.

Essa indireção é o mecanismo: uma implantação que consome um secret por FQN não exige que nenhum humano tenha lido o valor. Isso torna essa divisão real, e não apenas cosmética:

A linha da função Viewer é o grande ganho. Alguém pode ver que a chave stripe-live-key existe aqui — o suficiente para revisar do que um projeto depende — sem que o valor apareça na tela. O catálogo de permissões torna essa mesma divisão explícita: secret-group:ReadSecretGroup visualiza o grupo, secret-group:ReadData lê os valores. Chaves diferentes permitem que uma função personalizada contenha uma sem conter a outra.

Dois alertas, porque aqui a documentação é mais restrita do que o conceito. Um administrador de tenant tem acesso a todos os grupos de secrets por padrão; para membros e equipes, você atribui uma função em cada grupo individualmente. Além disso, a lista de funções de recursos indica uma quarta função, Secret Group Access, ao lado de Admin, Editor e Viewer — mas a página de gerenciamento de secrets documenta apenas as três acima. Verifique seu próprio console antes de construir um processo baseado nisso.

O padrão se generaliza. Sempre que um recurso tiver tanto uma descrição quanto um payload, procure por chaves separadas cobrindo cada um — repositórios possuem a mesma divisão entre ReadRepository e ReadData — e conceda a descrição sem o payload sempre que isso for suficiente.

Pronto para separar a leitura do uso?

Crie um grupo de secrets, conceda a função Viewer a um colega de equipe e veja os valores permanecerem ocultos.

Comece gratuitamente na TrueFoundry

Pegadinhas que valem a pena conhecer

Concessões se combinam, e remover uma não remove a outra. Um sujeito pode ter acesso direto e também herdá-lo por meio de uma equipe. A TrueFoundry combina ambos, portanto, revogar a concessão direta mantém a herdada intacta. Verifique ambos, nessa ordem. A granularidade fina agrava isso: mais concessões pequenas significam mais locais para verificar.

Editar a função padrão de uma equipe a altera para todas as equipes. Team Member e Team Manager são editados em Access > Default Roles, e a alteração é global. Adicionar virtual-account:ManageVirtualAccount para que uma equipe possa recuperar tokens concede essa capacidade em todas as equipes. As pessoas continuam limitadas às suas próprias equipes, mas a capacidade se espalha. É uma alteração do degrau 1 disfarçada de degrau 2.

Uma aprovação pendente é uma resposta de sucesso, não um erro. Enquanto uma solicitação está pendente, o gateway retorna um resultado JSON-RPC com isError: false e _meta.approval_status: "pending", cujo texto solicita que o chamador aguarde. Um agente que verifica apenas erros tratará isso como um resultado real da ferramenta e continuará a execução. Leia _meta.approval_status e tente novamente.

Leitura relacionada

• Controle de Acesso MCP: Protegendo Agentes de IA com um Gateway MCP — degraus 2 e 3 para ferramentas de agentes
• O que é Autorização MCP? — como as decisões chegam a uma chamada de ferramenta
• Controle de Acesso MCP Enterprise — mantendo a escala legível em vários servidores
• Autenticação de API e RBAC no AI Gateway — onde as concessões são aplicadas no tráfego em tempo real
• Servidores MCP Virtuais — compondo uma superfície de ferramentas curada a partir de vários servidores

Conclusão

A autorização de granularidade fina é vendida como um botão que você ajusta para cima. Na verdade, é uma escala que você sobe deliberadamente, parando quando o risco para de aumentar, e não quando a plataforma fica sem opções.

Cada degrau responde a uma pergunta diferente. A capacidade do tenant pergunta o que alguém pode fazer no geral. As funções por recurso perguntam onde. As permissões no nível de ferramenta perguntam quais operações existem para serem escolhidas. A aprovação por invocação pergunta se esta chamada deve acontecer agora. Nessa ordem, cada degrau restringe o anterior, e todos permanecem legíveis.

Fora de ordem — como uma barreira por chamada protegendo uma vinculação ampla demais ou uma função em todo o tenant substituindo uma concessão de recurso — você obtém um modelo que parece rigoroso em um diagrama, mas que não pode ser explicado em uma auditoria. O modelo de autorização mais fino não é o melhor. O melhor modelo é o mais fino que você consegue ler em voz alta.

Delimite seu primeiro agente na TrueFoundry

Gratuito para começar