Como controlar refresh tokens de agentes de IA

Um agente de IA nunca deve manter um refresh token. Essa regra parece severa até você observar o que o token faz: ele permite que um processo continue obtendo acesso depois que a aprovação humana original deixou de estar visível. Um access token pode expirar rapidamente; um refresh token mantém a relação ativa.

O desenho mais útil não é tornar o agente melhor em proteger uma credencial bearer. Coloque a credencial em uma camada de ações controlada por um processo sob responsabilidade humana. O agente solicita uma ação externa específica, a camada decide se aquela execução pode realizá-la, atualiza o token apenas quando necessário e devolve o resultado. Essa estrutura cria um lugar para aprovar, revogar e investigar o uso.

Um cofre de senhas, sozinho, não resolve o problema. O cofre protege o armazenamento. A camada de ações do agente controla o uso. As equipes confundem essas funções o tempo todo e depois descobrem que um token guardado em um armazenamento criptografado continua disponível para qualquer processo capaz de fazer a pergunta certa ao armazenamento.

Refresh tokens de agentes de IA mudam o limite de confiança

Refresh tokens de agentes de IA são perigosos porque estendem a autoridade para além do processo do agente que primeiro precisou deles. Se um agente de programação consegue ler um refresh token de uma variável de ambiente, arquivo de configuração, perfil do navegador ou resposta de um gerenciador de segredos, ele pode usar esse token por meio de qualquer cliente HTTP que consiga chamar. O token deixa de pertencer a uma tarefa delimitada. Ele passa a pertencer a qualquer coisa que obtenha controle daquele processo.

A OAuth 2.0, RFC 6749, descreve refresh tokens como credenciais usadas para obter access tokens quando o token atual expira ou se torna inválido. A especificação os trata como opcionais, mas isso não os torna inofensivos. Os provedores os emitem porque exigir autorização interativa a cada renovação do access token seria incômodo. Essa conveniência é exatamente o motivo pelo qual um agente sem supervisão não deve possuir um.

Mantenha três coisas separadas:

• O proprietário da conta é a pessoa ou identidade de serviço cuja conta concedeu o acesso.
• O solicitante da ação é o processo do agente que pede para chamar uma API agora.
• O custodiante da credencial é o componente que armazena o refresh token e conversa com o endpoint de tokens.

Uma mesma pessoa ou programa pode ocupar mais de um papel em uma configuração pequena, mas os papéis ainda precisam existir. Se o mesmo agente ocupar os três, ele poderá conectar uma conta nova, ampliar seu escopo, atualizar o token indefinidamente e ocultar a ação entre solicitações comuns. Isso não é um desenho de autorização. É um bearer token com um chatbot acoplado.

Já vi equipes dizerem: «o agente só precisa de acesso de leitura» e depois colocarem um refresh token com amplo acesso a repositórios, e-mails ou serviços de nuvem em um arquivo .env local. O access token pode ter vida curta, mas o refresh token torna o erro persistente. Uma injeção de prompt não precisa convencer o modelo a exfiltrar uma senha. Ela pode convencê-lo a usar a autorização ainda válida em uma solicitação que pareça plausível naquele contexto.

O limite deve ficar antes que as credenciais entrem no processo do agente. O agente não recebe o valor do token nem um falso placeholder que possa trocar em outro lugar. Ele recebe uma interface de operações: buscar esta issue, criar este rascunho, ler o status desta implantação, abrir esta sessão SSH neste host aprovado. A camada de ações controla os detalhes do protocolo por trás da operação.

Uma pessoa deve ser responsável pela autorização, não apenas aprovar um prompt

A pessoa que pode aprovar uma atualização deve ser identificada antes de a conexão OAuth existir. «Qualquer desenvolvedor pode clicar em permitir» funciona até que o proprietário da conta saia da empresa, uma caixa de e-mail compartilhada mude de responsável ou um agente reconecte um serviço usando a identidade de outra pessoa.

Para uma conta SaaS pessoal, o proprietário da conta deve concluir a autorização inicial e aprovar a reconexão depois de uma revogação ou expiração. Para uma conta operacional compartilhada, designe um proprietário responsável e uma pessoa substituta que possa revogá-la. Para uma identidade de máquina, o responsável pelo serviço deve autorizar o registro do cliente e seus escopos. Não trate uma pessoa e uma identidade de máquina como equivalentes apenas porque ambas conseguem chamar a mesma API.

Separe quatro decisões que costumam ser condensadas em um único clique no navegador:

1. Quem pode criar a autorização original.
2. Qual camada de ações pode guardar o refresh token resultante.
3. Quais sessões de agentes podem solicitar ações usando essa autorização.
4. Quem pode revogar a autorização ou aprovar uma nova conexão.

A tela original de consentimento OAuth responde apenas à primeira decisão, e às vezes responde de forma limitada. Ela informa ao provedor que o titular da conta autorizou um cliente com determinados escopos. Não informa ao sistema local se um repositório não confiável, um novo subprocesso do agente ou uma tarefa noturna pode usar essa autorização.

Um registro prático de autorização precisa de mais que o e-mail da conta no provedor. Guarde um registro local com um ID de autorização opaco, nome do provedor, referência da conta, conjunto de escopos, proprietário, responsável substituto pela revogação, data da conexão e ações que podem solicitá-la. Evite copiar o refresh token para esse registro. O registro explica o token; não deve virar um segundo armazenamento de segredos.

O caso mais complicado é o acesso compartilhado. Uma equipe costuma conectar uma conta de administrador porque é rápido e depois permite que o agente de cada desenvolvedor opere com ela. Essa escolha destrói a responsabilização. Se a API oferecer contas de serviço, instalações de aplicativos, identidades delegadas ou tokens de projeto com escopo restrito, use essas alternativas. Se não oferecer, limite a camada de ações a um pequeno grupo de operações aprovadas e registre quem é o verdadeiro proprietário da conta compartilhada.

Não dê ao agente autoridade para iniciar sozinho um novo fluxo OAuth no navegador. Ele pode apresentar uma página legítima do provedor, mas também pode conduzir a pessoa a uma conta mais ampla, a uma seleção de escopos mais abrangente ou a outro tenant. Iniciar uma conexão é uma ação administrativa. Exija que a pessoa a inicie pela camada de ações e confira a conta e a lista de escopos antes de consentir.

A camada de ações deve atualizar o token apenas para concluir uma ação aprovada

Uma camada de ações controlada deve trocar um refresh token somente quando tiver uma solicitação autorizada que exija um access token atual. Ela não deve executar um loop em segundo plano que atualiza todas as credenciais «por precaução». A atualização antecipada parece organizada no código e piora a resposta a incidentes, pois mantém autorizações ativas sem uma ação humana ou do agente correspondente.

O caminho da solicitação pode continuar simples:

1. Uma sessão do agente solicita uma operação identificada e fornece parâmetros comuns da ação.
2. A camada de ações identifica a autorização vinculada à operação e verifica se a sessão pode usá-la.
3. Se o access token em cache não existir ou estiver perto de expirar, a camada envia o refresh token ao endpoint de tokens do provedor.
4. A camada chama a API de destino com o access token e devolve o resultado filtrado ao agente.
5. A camada registra a ação e o evento de atualização sem registrar material de credencial.

O agente nunca escolhe o endpoint de tokens, o identificador do cliente, a URL de callback ou a string de escopo. Esses valores pertencem à definição da conexão aprovada pela pessoa. Permitir que o agente os forneça transforma seu gateway em um relay aberto de tokens.

Considere um agente encarregado de publicar uma nota de versão em um rastreador de projetos. Ele solicita à camada de ações a criação de uma issue em um projeto identificado. A camada percebe que a operação exige uma autorização do rastreador para aquele projeto, verifica a sessão solicitante, renova o access token se necessário e publica a nota. O resultado pode ser o ID da nova issue e a referência semelhante a uma URL devolvida pelo provedor, não o bearer token usado para criá-la.

Agora mude o prompt. Uma instrução maliciosa no repositório diz ao agente para «verificar o acesso» listando todos os projetos da organização e criando uma issue de teste em cada um. Se o agente tiver o refresh token, a instrução pode se transformar em uma série direta de chamadas de API. Se ele tiver apenas a interface da operação nomeada, a camada poderá rejeitar solicitações fora do projeto aprovado ou exigir outra autorização humana antes de continuar a sessão.

Isso não exige uma linguagem de políticas complexa. Exige um conjunto pequeno e compreensível de escolhas: qual processo está solicitando, qual autorização ele pode usar e se essa ação precisa de aprovação humana. Mais opções não tornam automaticamente o desenho mais seguro. Muitas vezes elas tornam impossível para o operador saber qual regra venceu.

O Sallyport segue essa separação mantendo as credenciais de API em seu cofre criptografado e executando ações HTTP ou SSH por meio de sua conexão MCP, em vez de devolver credenciais ao agente.

O tipo de autorização define o que você pode automatizar com segurança

Use o fluxo Authorization Code com PKCE para conectar a conta de uma pessoa em um aplicativo desktop ou local. A pessoa entra no provedor, revisa a solicitação de consentimento e retorna ao aplicativo local pelo caminho de redirecionamento registrado. O PKCE vincula a resposta de autorização ao cliente que iniciou o fluxo e reduz o valor de um código de autorização interceptado.

A RFC 9700, OAuth 2.0 Security Best Current Practice, afirma que clientes públicos devem usar PKCE. Ela também diz que refresh tokens de clientes públicos devem usar uma restrição de remetente ou rotação de refresh tokens. Essa orientação importa para integrações com agentes porque um aplicativo local frequentemente se comporta como um cliente público. Enviar um segredo de cliente dentro de um aplicativo desktop não o transforma em cliente confidencial. Qualquer pessoa que tenha o aplicativo pode extrair esse segredo.

Escolha o fluxo de acordo com a identidade conectada:

• Use Authorization Code com PKCE para a conta de um usuário no provedor.
• Use Client Credentials para uma identidade de serviço quando o provedor oferecer suporte e não for necessária a delegação da conta de uma pessoa.
• Use o modelo de instalação ou aplicativo específico do provedor quando ele oferecer acesso mais restrito a projetos ou organizações.
• Use a autorização por dispositivo somente quando o provedor e o ambiente operacional exigirem isso, mostrando à pessoa exatamente qual identidade e conjunto de escopos ela está aprovando.

Client Credentials normalmente não produz refresh tokens, porque o cliente pode solicitar um novo access token autenticando-se novamente. Isso pode ser mais seguro para uma tarefa autônoma se a identidade de serviço tiver permissões restritas e o material de autenticação do cliente permanecer dentro da camada de ações. Não use Client Credentials como desculpa para dar a um agente de programação um segredo de cliente com privilégios amplos.

O acesso offline merece atenção especial. Alguns provedores OpenID Connect exigem o escopo offline_access antes de emitir um refresh token. Solicite-o apenas quando uma ação realmente precisar ser executada depois do fim da sessão interativa. Se houver uma pessoa presente em todas as operações, um access token curto com nova autorização pode ser mais adequado. As equipes frequentemente pedem acesso offline por padrão porque isso evita lidar com expiração. O resultado é trocar um incômodo por uma credencial duradoura.

Evite completamente o Resource Owner Password Credentials. A RFC 9700 desaconselha esse tipo de autorização porque ele entrega a senha do usuário ao cliente. Uma camada de ações não torna isso aceitável. Ela apenas cria outro lugar onde uma senha pode ser perdida.

A rotação só ajuda quando o armazenamento trata corretamente a substituição

A rotação de refresh tokens reduz o dano causado por um token copiado, pois cada atualização bem-sucedida substitui o token anterior. O provedor pode detectar a reutilização de um token antigo e invalidar a família de autorizações afetada. Essa detecção é útil, mas também pode bloquear sua integração legítima quando a lógica de atualização é mal implementada.

A falha mais comum é uma condição de corrida. Duas sessões de agentes precisam de um access token quase ao mesmo tempo. Ambas leem o mesmo refresh token antigo. A primeira sessão atualiza com sucesso e recebe um novo valor. A segunda envia o valor antigo um instante depois. Dependendo do provedor, a segunda solicitação pode falhar ou acionar a detecção de reutilização, revogando toda a família, inclusive o token novo.

Evite a corrida com um único responsável pela atualização de cada autorização. A camada de ações deve serializar o trabalho de atualização para cada ID de autorização. Um segundo solicitante espera o resultado da primeira atualização e usa o access token recém-armazenado, em vez de enviar outra solicitação de token. Isso é uma exigência de correção, não uma otimização.

Armazene o token substituto antes de considerar a atualização bem-sucedida para trabalhos futuros. Uma ordem segura é:

1. Envie o refresh token antigo ao endpoint de tokens por TLS.
2. Valide a resposta e associe-a ao provedor e à autorização esperados.
3. Grave o novo refresh token e os metadados no armazenamento criptografado em uma única atualização durável.
4. Marque o token antigo como inutilizável no estado local.
5. Libere as chamadas em espera com o novo access token ou com um caminho de solicitação atualizado.

Se o processo travar depois que o provedor rotacionar o token, mas antes que o armazenamento local registre o substituto, você poderá perder a autorização. Não é possível corrigir isso com tentativas repetidas. O caminho de recuperação é uma reconexão conduzida por uma pessoa, por isso os registros de proprietário e responsável pela revogação são importantes.

Alguns provedores emitem um novo refresh token apenas em certas ocasiões. Outros devolvem o mesmo token. Seu código precisa aceitar os dois comportamentos sem presumir nenhum deles. Preserve o valor anterior apenas até confirmar que a resposta do provedor e a gravação durável foram concluídas. Nunca registre nenhum dos valores em logs durante a depuração. Um número surpreendente de vazamentos de tokens começa como uma instrução temporária de depuração que sobreviveu a uma versão publicada.

Tokens com restrição de remetente podem reduzir o risco de repetição vinculando um token a uma chave criptográfica mantida pelo cliente. O DPoP, definido na RFC 9449, é uma abordagem possível. Isso não elimina a necessidade de custódia. Se um agente puder usar tanto o refresh token quanto a chave privada de assinatura, ele ainda terá autoridade duradoura. Mantenha os dois materiais atrás da camada de ações e teste o comportamento do provedor antes de depender da restrição.

A revogação precisa de um operador identificado e de um caminho testado

Revogação não é uma configuração que você ativa uma vez. É uma ação que alguém precisa conseguir executar sob pressão, quando o painel do provedor está lento e ninguém se lembra de qual conta autorizou a integração.

Ofereça ao proprietário da conta e ao substituto designado um caminho direto de revogação. Quando revogarem uma autorização, sua camada de ações deve remover o refresh token local, invalidar todos os access tokens em cache e interromper as sessões que ainda possam solicitar essa autorização. Desabilitar a interface do agente enquanto deixa a credencial armazenada é uma revogação incompleta.

A RFC 7009 define uma solicitação de revogação de token OAuth. O provedor publica seu próprio endpoint, mas o formato normalmente se parece com este:

POST /revoke HTTP/1.1
Host: authorization.example
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <client authentication>

token=<refresh-token>&token_type_hint=refresh_token

A RFC 7009 orienta os servidores a devolver uma resposta de sucesso mesmo quando o token enviado já é inválido ou desconhecido. Esse comportamento impede que um invasor use o endpoint como uma fonte para descobrir se um token é válido. Também significa que o operador não pode interpretar apenas um sucesso HTTP como prova de que a autorização tinha acesso ativo. Registre que a solicitação de revogação foi enviada, remova a credencial local e verifique depois com uma chamada inofensiva ao provedor ou com o registro de auditoria dele, se houver.

Prepare a revogação para estes eventos: o proprietário da conta sai da empresa, há suspeita de comprometimento de uma sessão do agente, uma instrução de repositório causou uma chamada externa inesperada, uma integração é desativada ou um provedor informa reutilização de token. Não espere um vazamento para decidir quem tem autoridade para apertar o botão.

Um access token já emitido pode continuar utilizável até expirar. Alguns provedores o revogam imediatamente; outros não. Sua camada local pode interromper imediatamente a emissão de novas ações, que é o controle sob sua responsabilidade. Não prometa invalidação global instantânea a menos que o provedor a documente e você tenha testado o comportamento.

Mantenha a revogação no provedor separada da desativação local. A desativação local impede que sua camada de ações use uma autorização. A revogação no provedor informa a ele que também deve rejeitá-la. Durante um incidente, faça as duas coisas nessa ordem: interrompa primeiro seu próprio caminho de execução e depois envie a solicitação ao provedor. O primeiro passo está sob seu controle e não deve depender de uma chamada de rede externa.

Um registro de auditoria deve explicar a intenção, não apenas o tráfego

Uma lista de chamadas HTTP não consegue dizer se uma atualização foi adequada. Você precisa de um registro que relacione a decisão humana, a sessão do agente solicitante, a referência da autorização e a ação externa resultante.

Não grave refresh tokens, access tokens, códigos de autorização, asserções de cliente nem corpos completos de API no log de auditoria. Strings de tokens são segredos. Corpos completos de resposta podem conter dados de clientes, conteúdo de repositórios ou informações pessoais. Registrá-los por conveniência cria um segundo armazenamento de credenciais e dados, mais confuso.

Um registro de evento útil inclui ID do evento, horário, ID da sessão, identidade do processo solicitante, ID da autorização, referência da conta conectada, nome da operação, host do provedor, recurso solicitado, conjunto de escopos registrado no momento da conexão, referência da aprovação, classe do resultado e código de erro, se houver. Para uma atualização, registre que ela ocorreu e se foi bem-sucedida. O valor do token não é necessário para investigá-la.

A diferença entre um registro de ação e um registro de credencial importa. Um registro de ação informa que uma determinada sessão de agente solicitou o status de uma implantação em um ambiente identificado e que a camada de ações permitiu. Um registro de credencial informa qual autorização sustentou a solicitação e quem é seu proprietário. Mantenha os dois relacionáveis por um ID de autorização opaco, mas não permita que todo operador capaz de consultar o histórico de ações veja os detalhes da conexão da conta.

A evidência contra adulteração melhora a qualidade de uma investigação. Se um processo local comprometido puder editar o mesmo log que escreve, um invasor poderá apagar as entradas importantes. Use tratamento de eventos somente para anexação, com verificações de integridade, e valide o log separadamente do processo que o gerou.

O Sallyport projeta seus diários de sessões e atividades a partir de um log de auditoria criptografado e encadeado por hashes, e o comando sp audit verify verifica essa cadeia offline sem uma chave do cofre.

Analise o comportamento em uma frequência compatível com o poder da autorização. Uma autorização pessoal para um rastreador de issues pode exigir apenas revisões ocasionais. Uma autorização capaz de alterar a infraestrutura de produção precisa ser revisada a cada nova conexão, a cada mudança de escopo e após qualquer comportamento inesperado do agente. A camada de ações deve tornar esses registros legíveis o bastante para que o proprietário responda: «Qual agente usou minha conta, para quê e sob qual aprovação?»

Perfis de navegador e intermediários genéricos de tokens criam desvios silenciosos

Um perfil de navegador é um armazenamento ruim para as credenciais de um agente. Ele pode conter cookies de sessão, access tokens em cache, refresh tokens, seletores de conta e estado de navegação sem relação com a tarefa. Dar ao agente acesso a esse perfil é mais amplo do que delegar uma ação de API e dificulta a limpeza, pois o estado do provedor e o estado do navegador ficam misturados.

Um intermediário genérico de tokens pode criar o mesmo problema se aceitar parâmetros arbitrários do endpoint de tokens enviados pelos solicitantes. As equipes costumam criar uma única API chamada getToken(scope) e se sentem mais seguras porque o token já não fica no processo do agente. O intermediário ainda vira uma máquina de fornecimento de tokens se qualquer sessão puder solicitar qualquer conta conectada ou escopo arbitrário.

Faça o solicitante pedir uma operação, não um token. «Criar uma nota de versão no projeto A» tem um proprietário, um destino e uma exigência de escopo que podem ser inspecionados. «Obtenha um token para tracker.write» deixa autoridade demais com o solicitante.

Não tente resolver isso com um mecanismo enorme de regras antes de entender suas operações. Um catálogo curto de ações aprovadas, vinculado a autorizações nomeadas e pontos de aprovação humana, é mais fácil de revisar e mais difícil de contornar. Acrescente complexidade apenas quando uma necessidade operacional real exigir isso.

Também evite compartilhar um único refresh token entre desenvolvimento, staging e produção. Autorizações separadas tornam a revogação menos dramática e os registros de auditoria menos ambíguos. Um agente de staging não deve manter um caminho para produção apenas porque os dois ambientes usam por acaso o mesmo provedor de identidade.

Comece com uma tabela de proprietários e um exercício de revogação

O primeiro artefato útil é um inventário de autorizações, não código. Crie uma linha para cada refresh token que seus agentes possam fazer ser usado. Inclua o provedor, a referência da conta, o ID da autorização, os escopos, a localização da camada de ações, o proprietário da conta, o substituto responsável pela revogação, o método de criação, o último uso confirmado e o procedimento de desativação local. Se não conseguir preencher uma coluna, você ainda não controla essa autorização.

Depois, faça um exercício de revogação com uma integração de baixo risco. Peça ao proprietário para desativar a autorização localmente, revogá-la no provedor e tentar uma ação comum do agente. Confirme que a camada de ações bloqueia a solicitação, que a reconexão exige uma ação humana explícita e que o histórico de auditoria identifica a sessão anterior. O exercício revela rapidamente suposições problemáticas: endpoints do provedor desconhecidos, propriedade incerta da conta, tokens armazenados em máquinas antigas de desenvolvedores e access tokens em cache que duram mais que o esperado localmente.

Defina uma revisão de expiração para autorizações que não tenham limites impostos pelo provedor. O acesso prolongado às vezes é necessário para trabalhos sem supervisão, mas o acesso indefinido deve ser uma exceção deliberada com um proprietário identificado. Quando uma equipe não consegue indicar o proprietário, a autorização não deve continuar utilizável.

O padrão a seguir é simples: um agente pode solicitar trabalho, mas não deve herdar a capacidade de uma conta de se renovar para sempre. Coloque a credencial de atualização onde uma pessoa possa controlar seu uso e transforme a revogação em uma ação praticada, não em uma busca de emergência por abas do navegador.