Por que arquivos de refresh token do OAuth são credenciais de produção?

Um arquivo auth.json copiado não é sobra de configuração. Se ele contém um refresh token, é uma credencial de produção capaz de continuar criando tokens de acesso depois que a pessoa que o copiou já foi embora. Chamar a máquina de «sem interface» não muda isso. Apenas remove o aviso do navegador que lembraria alguém de pensar em responsabilidade.

Já vi equipes protegerem uma chave de API com cuidado e depois enviarem um arquivo de refresh token para um host de compilação como anexo de uma conversa, porque o token de acesso dentro dele expirava rapidamente. Isso é o contrário do que deveria acontecer. O token de acesso de curta duração costuma ser a parte menos interessante do arquivo. O caminho de renovação é o que um invasor, um agente com permissões excessivas ou um trabalho noturno sem responsável pode continuar usando.

Um arquivo de refresh token é um pacote de credenciais

Um arquivo de refresh token do OAuth é um pacote de credenciais porque normalmente contém estado suficiente para obter um novo token bearer sem a presença de uma pessoa. Os campos exatos variam de acordo com a biblioteca cliente, mas a combinação perigosa é conhecida: um refresh token, um identificador de cliente, um endpoint de token, escopos concedidos e, às vezes, um segredo de cliente ou uma asserção específica do dispositivo.

Não deixe a extensão do arquivo fazer o risco parecer menor. JSON é apenas um envelope. Um arquivo chamado .cache/session.json, token-store.json ou auth.json merece o mesmo cuidado que uma chave SSH privada quando pode renovar o acesso a um serviço de produção.

A estrutura de autorização OAuth 2.0, RFC 6749, descreve refresh tokens como credenciais usadas para obter tokens de acesso. Ela também diz que o servidor de autorização pode emitir um novo refresh token e que o cliente deve descartar o antigo. É fácil tratar essa última frase como um detalhe do protocolo. Em um sistema sem supervisão, ela é uma exigência operacional: dois trabalhadores que acreditam ter o arquivo atual podem agora disputar a identidade de uma credencial.

Separe estes três itens no seu inventário:

• Um token de acesso autoriza uma solicitação por um período limitado.
• Um refresh token autoriza a renovação, muitas vezes ao longo da vida útil de vários tokens de acesso.
• Um cliente OAuth identifica o software que solicita a renovação.

As equipes costumam misturar os dois primeiros e então fazem o argumento errado sobre expiração. Um token de acesso de cinco minutos não torna seguro um refresh token copiado. Isso pode apenas significar que o arquivo copiado dá a um invasor tokens novos em lotes de cinco minutos.

Uma entrada de inventário de produção deve responder a mais do que «qual serviço usa isto?». Registre o servidor de autorização, o identificador do cliente OAuth, o servidor de recursos, o sujeito ou a conta de serviço, os escopos exatos concedidos, o ambiente, o horário de emissão se estiver disponível, o responsável pela renovação, o caminho de execução aprovado e o método de revogação. Se você não consegue preencher esses campos, não tem uma credencial pronta para uso autônomo. Tem um arquivo que funcionou por acaso nos testes.

O trabalho sem interface facilita a perda de responsabilidade

Um agente sem interface precisa de um acordo de renovação que indique um responsável. A falha costuma começar quando um desenvolvedor autoriza uma ferramenta local usando a própria conta e depois copia o cache para um servidor porque o servidor não consegue concluir o fluxo pelo navegador. O trabalho funciona, então a cópia se torna permanente.

Agora faça as perguntas que as pessoas deixam de lado porque são incômodas. O token representa o desenvolvedor, a equipe ou o trabalho? Quem pode revogá-lo sem interromper o trabalho de outra pessoa? Qual repositório ou instrução do agente informa ao trabalho onde encontrá-lo? Um funcionário que está saindo pode invalidar a identidade por trás dele? A página de consentimento do provedor mostra uma conta pessoal embora o trabalho se comporte como um serviço?

«A conta da plataforma é a responsável» não é uma resposta, a menos que essa conta tenha um administrador documentado, um procedimento de recuperação e privilégios limitados. Um token copiado de um login pessoal é pior do que uma chave de API visível em um aspecto: muitas vezes chega como um arquivo de cache opaco, por isso os revisores não conseguem ver quais permissões vieram junto.

Use uma identidade de serviço dedicada quando o provedor oferecer essa opção. Dê a essa identidade o menor conjunto de permissões de recursos que permita ao trabalho terminar. Registre um cliente OAuth separado para cada limite de confiança relevante, como desenvolvimento, homologação e produção. Não use um único cliente abrangente e um único consentimento amplo apenas porque é conveniente renovar.

Vale manter uma distinção clara: a identidade do cliente OAuth e a identidade do recurso são controles diferentes. Um identificador de cliente informa qual software solicitou um token. O sujeito e os escopos informam quais recursos o token pode acessar e o que ele pode fazer. Uma equipe que cria um cliente dedicado, mas continua autorizando-o como administrador humano, melhora um pouco a atribuição e mantém intacto o problema de privilégios.

Para um agente, escreva um registro simples de responsabilidade ao lado da documentação da implantação, não dentro do arquivo de token:

Credential name: billing-export-prod
OAuth client: agent-billing-prod
Resource identity: svc-billing-export
Scopes: reports.read, exports.write
Renewal owner: platform-oncall
Execution path: production job runner through credential broker
Revocation: authorization server admin console and RFC 7009 endpoint

Esse registro é propositalmente sem graça. É por isso que ajuda às duas da manhã. Ele permite que um operador revogue a concessão certa sem tentar adivinhar se o arquivo pertencia ao laptop antigo de um desenvolvedor, a um teste de homologação ou ao trabalho que agora está enviando alertas.

Mantenha o caminho de renovação fora do espaço de trabalho do agente

O processo do agente não deveria ler um arquivo de refresh token. Se um agente consegue ler a sequência, ele pode imprimi-la, gravá-la em um registro, incorporá-la a um patch, enviá-la para uma ferramenta remota ou deixá-la em um relatório de falha. Instruções para não divulgar o segredo não mudam a capacidade do processo de exfiltrar dados que ele consegue ler.

As permissões do sistema de arquivos ainda importam, mas são uma camada de contenção posterior à escolha arquitetural. Um modo de arquivo como 0600 impede o acesso de outras contas locais em um host Unix convencional. Ele não impede que o processo autorizado do agente, seus plugins, processos filhos, depuradores ou um trabalho de backup leiam o arquivo. Também não explica por que esse host tem uma credencial de renovação de produção em primeiro lugar.

Coloque o refresh token em um gerenciador de segredos, no armazenamento de credenciais do sistema operacional ou em um gateway local que não permita ao agente consultar os valores brutos. O gateway deve aceitar uma solicitação de ação restrita, buscar ou atualizar a credencial internamente, chamar o endpoint de recurso aprovado e retornar o resultado de que o agente precisa. Uma solicitação pode ser assim:

{
  "action": "create_export",
  "target": "billing-api",
  "parameters": {
    "report_date": "2026-07-23"
  }
}

O agente recebe uma resposta como esta, não um token:

{
  "status": "accepted",
  "export_id": "exp_4821",
  "report_date": "2026-07-23"
}

Esse limite evita um erro frequente: montar um diretório de segredos em todos os contêineres de trabalho e chamar isso de acesso controlado. A montagem torna o segredo disponível para toda biblioteca, comando de shell, extensão e diagnóstico acidental dentro do contêiner. Um gateway pode rejeitar destinos desconhecidos, anexar a credencial correta por conta própria e manter o estado de renovação fora da memória do agente.

No macOS, o Sallyport segue esse modelo em suas ações HTTP e SSH compatíveis: as credenciais permanecem em seu cofre criptografado e o agente recebe resultados das ações em vez de segredos em texto simples. Esse projeto é útil porque trata a solicitação como aquilo que deve ser autorizado, não o arquivo de token como uma conveniência a ser entregue.

Não coloque arquivos de refresh token em diretórios de repositórios, espaços de trabalho de CI, pastas de rede compartilhadas, arquivos ocultos do diretório pessoal, imagens de contêiner ou caminhos genéricos de backup. Cada local cria um mecanismo de cópia diferente, e cada cópia acrescenta um problema futuro de revogação. Se uma ferramenta antiga exige um caminho, dê a ela um diretório de execução isolado e de curta duração, gerenciado por um auxiliar de credenciais, e faça o auxiliar criar e remover o arquivo. Trate isso como uma exceção de compatibilidade com data para acabar, não como seu padrão.

Os escopos devem descrever um trabalho, não um departamento

Um agente sem interface deve ter escopos que descrevam seu único trabalho. Um token autorizado a ler todos os projetos porque talvez o agente precise de outro projeto algum dia acabará sendo usado em um contexto que ninguém esperava. Escopos amplos são populares porque as telas de autorização e a documentação dos provedores podem ser frustrantes. O custo aparece mais tarde, durante um incidente, quando revogar um token de automação também interrompe trabalhos sem relação.

Comece pelas chamadas finais da API, não pela lista de escopos disponíveis do provedor. Anote os verbos e recursos de que o trabalho precisa. Um trabalho que busca faturas e envia um relatório final pode precisar de acesso de leitura às faturas e acesso de gravação a um local de exportação. Ele não precisa de escopos para administração de usuários, exclusão de repositórios, alterações de cobrança ou gerenciamento de permissões só porque alguém usou essas permissões durante a configuração inicial.

Os escopos do OAuth não bastam. As permissões do lado do recurso podem ampliar o efeito de um escopo que parece modesto. Um token com files.write ainda pode causar grandes danos se o sujeito tiver acesso a todas as pastas das equipes. Vincule a identidade de serviço a um projeto, pasta, unidade organizacional ou repositório limitado sempre que o provedor permitir. Depois teste os casos negativos: uma ação contra um recurso de produção próximo deve falhar por motivo de permissão, não apenas porque o agente ainda não tentou executá-la.

Crie concessões separadas para funções separadas mesmo quando o provedor aceita uma lista combinada. Por exemplo, mantenha separado um trabalho de coleta de dados somente leitura e um trabalho que publica resultados. Uma credencial de publicação vazada tem impacto, ritmo de rotação e responsável pela aprovação diferentes dos de uma credencial de leitura. Combiná-las economiza um fluxo de renovação de token, mas torna toda investigação mais difícil.

Evite padrões de escopo baseados na sessão de um administrador humano. Administradores geralmente consentem com permissões amplas porque precisam delas para a configuração. O agente em execução não herda o julgamento do administrador. Ele herda a autorização.

Um teste útil de revisão é este: leia o registro de consentimento e tente descrever o trabalho em uma frase. Se a descrição virar «ele pode gerenciar várias coisas de que talvez precisemos», a concessão não está pronta. Restrinja o trabalho ou divida-o. O inconveniente de manter duas credenciais custa menos do que descobrir que um agente de exportação podia alterar configurações de identidade.

Tokens que se atualizam sozinhos precisam de um único responsável

A rotação de refresh tokens cria um problema de gerenciamento de estado, e trabalhadores sem supervisão precisam resolvê-lo de propósito. Muitos servidores de autorização fazem a rotação dos refresh tokens: depois de uma atualização bem-sucedida, o servidor retorna uma substituição e pode invalidar o token anterior. A RFC 9700, OAuth 2.0 Security Best Current Practice, recomenda a rotação de refresh tokens ou tokens vinculados ao emissor para clientes públicos, a fim de detectar reutilização. É uma recomendação de segurança sólida, mas não torna seguro um arquivo compartilhado.

Considere uma falha comum. O trabalhador A e o trabalhador B começam com o mesmo auth.json montado. O trabalhador A atualiza primeiro e recebe R2; o provedor invalida R1. Antes que A grave R2, o processo morre ou a gravação do sistema de arquivos cai em uma camada local que B não consegue ver. O trabalhador B envia R1, recebe invalid_grant e tenta novamente. Um operador vê um trabalho com falha, copia um cache antigo de um backup e, agora, a resposta ao incidente criou mais cópias da credencial.

Use uma destas opções:

1. Um gateway de credenciais controla as atualizações e armazena a substituição de forma transacional.
2. Um único trabalhador programado controla uma determinada concessão, com um bloqueio explícito e sem réplicas paralelas compartilhando o estado do token.
3. Existem concessões separadas para trabalhadores separados, de modo que cada refresh token tenha um único gravador.

A primeira opção costuma ser a mais simples. A segunda pode funcionar para um trabalho pequeno e controlado, mas a expiração do bloqueio e a recuperação após falhas precisam de um projeto real. A terceira custa mais trabalho de consentimento e de ciclo de vida, mas contém bem as falhas.

Não resolva a disputa desativando a rotação se o provedor permitir isso. Essa recomendação é atraente porque esconde o problema de concorrência. Ela também dá a um refresh token roubado mais tempo para operar sem ser percebido. Corrija o modelo de responsabilidade.

Seu caminho de persistência precisa atualizar o novo token de forma atômica e preservar metadados suficientes para detectar um gravador obsoleto. No mínimo, armazene uma versão, o horário da última atualização bem-sucedida e um identificador estável da credencial que seja seguro registrar. O armazenamento de segredos deve rejeitar uma atualização que tente substituir a versão 14 quando a versão 15 já existe. Uma sobrescrita simples permite que um trabalhador lento ressuscite um estado antigo.

Quando o servidor de autorização oferecer tokens vinculados ao emissor, entenda o que está vinculado. Um mecanismo de prova pode tornar um token copiado menos útil sem a chave mantida pelo cliente correspondente. Ele não substitui o controle de acesso a essa chave nem transforma uma concessão de consentimento humano em uma identidade de serviço adequada. Trate-o como outra barreira, não como motivo para distribuir arquivos de cache.

A rotação é um procedimento, não um lembrete no calendário

Uma política de rotação só é confiável quando alguém consegue executá-la sem improvisar. A rotação baseada em calendário tem seu lugar, mas mudanças de responsabilidade, atividade suspeita, comprometimento de host, exposição de repositório e erros inesperados de invalid_grant devem acionar a mesma sequência preparada. Não espere a data programada quando suspeitar que um token copiado escapou.

Um procedimento funcional tem cinco ações:

1. Congele o agente ou o caminho do gateway afetado para que ele não continue atualizando durante a mudança.
2. Identifique o cliente OAuth, a identidade do recurso, os escopos e a versão da credencial a partir do registro de responsabilidade e dos logs.
3. Revogue o refresh token ou a concessão no servidor de autorização, usando o console do provedor ou seu endpoint de revogação compatível com a RFC 7009 quando disponível.
4. Remova todas as cópias conhecidas em execução e invalide qualquer processo de backup ou cache que possa restaurá-las.
5. Cadastre novamente a identidade dedicada, teste a ação mínima permitida e registre a versão substituta.

A RFC 7009 define a revogação de tokens e permite deliberadamente que os servidores revoguem tokens e concessões relacionados ao processar uma solicitação. Isso significa que o operador precisa conhecer o alcance do impacto antes de pressionar o botão de revogação. Um provedor pode invalidar o token de acesso atual, a família de refresh tokens ou a concessão inteira. A resposta certa não é evitar a revogação. É documentar quais trabalhos compartilham uma concessão para que não compartilhem uma por acidente.

Teste a rotação com uma identidade descartável que não esteja em produção. Confirme que uma substituição recém-emitida funciona, que o token antigo falha e que um trabalhador obsoleto não consegue sobrescrever o novo estado. Depois pratique a resposta a um token revogado. O trabalho deve falhar de forma segura, com um erro reconhecível e uma identidade que possa ser associada a um chamado, não retornar silenciosamente ao login armazenado de um desenvolvedor.

Os backups precisam de tratamento especial. Backups criptografados ainda preservam um refresh token até o fim do período de retenção. Talvez você não consiga excluir imediatamente os blocos históricos de backup, mas pode revogar imediatamente a concessão exposta. Documente o local de retenção para que um investigador saiba que a mídia de recuperação contém um segredo obsoleto, mesmo depois que ele deixar de funcionar.

Audite ações e eventos de renovação separadamente

Os registros de auditoria precisam mostrar tanto os eventos de renovação quanto as ações executadas com os tokens de acesso resultantes. Um evento de atualização informa que uma credencial continuou ativa. Não informa se o agente leu um relatório ou alterou mil registros. Da mesma forma, um registro de ação da API sem a versão da credencial não permite saber qual caminho de renovação a autorizou.

Registre metadados seguros para cada atualização: horário, identificador da credencial, versão do token antes e depois, identificador do cliente OAuth, identificador do sujeito, escopo solicitado ou retornado se o provedor o disponibilizar, host de execução ou identidade do gateway e resultado. Registre metadados seguros para cada ação protegida: identificador da sessão do agente ou do trabalho, destino solicitado, operação, identificador do recurso, decisão de autorização, código de resultado e identificador de correlação.

Nunca registre o refresh token, o token de acesso, o código de autorização, o segredo do cliente, a URL completa de callback ou o cabeçalho Authorization bruto. Fazer a remoção depois do registro é tarde demais se um coletor, gravador de terminal ou monitor de erros já recebeu o evento. Crie chamadas de registro que nunca aceitem esses campos, em vez de depender da lembrança de cada chamador para usar um filtro.

Uma consulta útil de incidente começa com uma ação sobre um recurso e volta pelo caminho. Suponha que uma exportação tenha aparecido no destino errado. Você deve conseguir responder: qual trabalho a solicitou, qual processo executou o trabalho, qual cliente OAuth ele usou, qual versão da credencial forneceu o acesso, quando essa versão foi emitida e se outro host usou a mesma versão. Se qualquer elo depender da leitura do valor do token, o projeto de auditoria está quebrado.

A evidência de adulteração importa quando agentes atuam sem supervisão constante. Um log somente de acréscimos no mesmo host é melhor do que o silêncio, mas um invasor que controla o host pode editar tanto o cache quanto o registro. Mantenha os dados de auditoria em um sistema protegido e verifique sua integridade de forma independente. Em sistemas capazes de manter um registro criptografado e encadeado por hash, a verificação offline oferece ao investigador uma forma de conferir se as entradas mudaram sem expor primeiro os segredos subjacentes.

A aprovação deve ficar nas ações, não na exposição do token

A aprovação humana é mais útil no limite em que um agente tenta afetar um sistema externo. Pedir a uma pessoa que aprove um arquivo de refresh token uma vez e depois permitir que qualquer processo o use por semanas cria uma aparência de controle enquanto coloca a sequência sensível em circulação.

Escolha as aprovações de acordo com a consequência. Uma consulta somente leitura pode ser executada em uma sessão pré-aprovada e com escopo restrito. Enviar dados para um destino novo, modificar permissões, excluir um recurso ou usar uma credencial fora do trabalho habitual deve parar para uma decisão humana. Quem aprova precisa ver o processo solicitante, o destino, a operação e parâmetros suficientes para entender o efeito. Um aviso genérico de «permitir OAuth» quase não serve para nada.

Não confunda prompts frequentes com segurança. Se cada chamada inofensiva pedir consentimento, as pessoas aprovarão por hábito. Defina um limite de sessão razoável para o trabalho rotineiro e exija uma aprovação separada para operações de alto impacto. A decisão precisa continuar visível quando o agente estiver rodando à mesa da cozinha, em uma conexão durante uma viagem ou dentro de um trabalho noturno.

O teste é simples: se uma instrução do agente se tornar hostil ou um plugin se comportar mal, ele consegue transformar o acesso em uma ação no mundo externo sem passar por um controle que mostre a uma pessoa o que vai acontecer? Se a resposta for sim porque ele já tem o auth.json, mova a credencial para trás de um gateway e redesenhe a superfície de solicitações.

Trate arquivos auth.json antigos como um projeto de migração

Caches de tokens existentes raramente desaparecem em uma tarde, mas deixá-los sem documentação porque a migração é inconveniente garante que se tornem permanentes. Comece encontrando cada consumidor e depois classifique o arquivo por serviço, sujeito, escopos, ambiente, número de gravadores e caminho de armazenamento. Revogue as cópias que você não consegue atribuir. Um token sem responsável não deveria renovar nada.

Mova um fluxo de trabalho por vez. Primeiro crie uma identidade de recurso e um cliente dedicados. Depois coloque o refresh token por trás do armazenamento de segredos ou gateway escolhido. Em seguida, altere o trabalho para enviar uma solicitação de ação permitida e compare o novo registro de auditoria com a saída do trabalho antigo. Só depois que a substituição funcionar você deve revogar a concessão pessoal antiga.

Espere resistência de algumas ferramentas. Certos SDKs presumem que são donos de um cache JSON local e fazem a atualização silenciosamente quando o encontram. Mantenha essas ferramentas em um wrapper de compatibilidade restrito, com apenas um processo autorizado a ler o arquivo e sem acesso geral do agente. Coloque a remoção desse wrapper na fila de trabalho do responsável pelo serviço. «A biblioteca exige isso» explica uma exceção temporária, mas não justifica um caminho permanente de vazamento de segredos.

O primeiro alvo da migração deve ser o arquivo com o escopo mais amplo ou o responsável menos claro, não o arquivo mais fácil de mover. Essas são as credenciais que transformam um erro contido do agente em um incidente de produção. Depois de migrar um fluxo de forma limpa, dificulte a repetição do padrão antigo por meio da revisão de implantação, de alterações nos modelos e da recusa em montar caches brutos de credenciais nos ambientes de execução dos agentes.

Um refresh token deve ter um único responsável, um único caminho de renovação controlado e uma trilha de auditoria que identifique cada ação externa que ele autorizou. Se o seu auth.json atual não atende a essas condições, revogue-o depois que o caminho substituto provar que consegue.