Acertando na autenticação de CLI: o guia completo para todos os 4 métodos

Todo CLI de desenvolvedor vem com login como seu primeiro comando. E cada um resolve a autenticação de maneira diferente.

O GitHub mostra um código e abre seu navegador para você verificá-lo. A AWS abre um navegador para SSO baseado em PKCE. O Stripe faz você confirmar um código de emparelhamento no painel de controle. As ferramentas de IA mais recentes (Claude Code, OpenAI Codex CLI, Cursor) também escolheram suas próprias abordagens.

Se você está construindo um CLI, a autenticação é uma das primeiras coisas que você precisa definir. Escolha o método errado e você ouvirá sobre isso: usuários frustrados, auditorias de segurança ou ambos. E com a recente onda de agentes de codificação de IA que chamam ferramentas CLI programaticamente, os riscos aumentam: você não está mais autenticando apenas um humano. Você pode estar entregando credenciais para um processo autônomo.

Aqui estão os quatro métodos de autenticação que importam, como as maiores ferramentas os implementam e os erros que você vai querer evitar.

Os quatro métodos em resumo#

Antes de aprofundar, aqui está uma comparação rápida:

Cada um tem pontos positivos e negativos. Aqui está o que você precisa saber sobre cada um.

1. OAuth device code flow (RFC 8628)#

Esse é aquele onde seu CLI mostra um código como ABCD-1234 e uma URL, então pede para você abrir a URL em qualquer dispositivo e digitar o código.

Quem usa: GitHub CLI (padrão), Azure CLI (via --use-device-code), Vercel CLI (recentemente mudou para este como padrão), OpenAI Codex CLI (como opção beta)

Como funciona#

1. Você executa cli login
2. O CLI solicita um código de dispositivo no servidor de autenticação, enviando seu client_id e scopes solicitados
3. O servidor retorna três coisas: um device_code (identificador interno), um user_code (o código curto que você digita) e um verification_uri (para onde ir)
4. Seu CLI exibe o código e a URL, e começa a consultar o servidor de autenticação a cada 5+ segundos
5. Você abre a URL em qualquer dispositivo (celular, notebook, outro computador), digita o código e autentica como quiser (senha, SSO, passkeys, MFA)
6. Quando você aprova, a próxima consulta retorna um access token e um refresh token
7. O CLI armazena esses tokens e você está dentro

Por que desenvolvedores gostam#

O grande diferencial: funciona em qualquer lugar. Sessão SSH em um servidor remoto? Funciona. Rodando dentro de um container Docker? Funciona. IDE na nuvem sem navegador local? Funciona. O navegador não precisa estar na mesma máquina do CLI.

Também suporta toda a gama de autenticações corporativas (SAML, OIDC, MFA), porque tudo isso ocorre no navegador, não no terminal. O CLI nunca vê sua senha.

O problema de segurança mais comum#

Device code flow tem um problema de phishing. Um atacante pode iniciar um pedido de device code, obter um user code legítimo e enganar você para digitar, autorizando efetivamente a sessão do atacante. Isso não é teórico. Pesquisadores já documentaram esse ataque contra a autenticação por device code do AWS SSO.

Isso é preocupante o suficiente para que a AWS mudou o padrão. A partir do AWS CLI v2.22.0, o padrão para aws sso login mudou do device code flow para autorização baseada em PKCE. Device code ainda está disponível via --use-device-code, mas não é mais o caminho padrão.

Enquanto isso, o próprio tenant da Microsoft começou a bloquear totalmente o device code flow via políticas de acesso condicional — um forte sinal de que consideram este método de alto risco.

Então temos um cenário curioso: Vercel adotou device code flow como padrão em setembro de 2025, enquanto a AWS se afastou. O padrão parece ser: device code flow é ótimo para ambientes onde você realmente não consegue abrir um navegador, mas se é possível abrir localmente, PKCE é mais seguro.

Do lado dos provedores de autenticação, a demanda está crescendo. Logto acabou de lançar suporte ao OAuth 2.0 Device Authorization Grant para apps nativos na v1.38.0 (open source) e Logto Cloud, então você já pode habilitar device flow como método de autorização para qualquer app nativo. Isso importa se você constrói um CLI. Implementar corretamente o RFC 8628 (expiração do código, rate limit, polling, UX da página de verificação) dá mais trabalho do que parece, e deixar o provedor cuidar disso significa só fazer as chamadas HTTP certas.

Detalhes técnicos do RFC#

Alguns pontos do RFC 8628:

• O valor de expires_in é definido pelo servidor de autenticação. O RFC usa 1800 segundos (30 minutos) como exemplo, mas não é uma exigência fixa.
• Se o servidor não especifica o intervalo de polling (interval), clientes devem usar 5 segundos por padrão.
• Um erro slow_down exige adicionar 5 segundos ao intervalo.
• Device codes devem ter uso único e expirar rapidamente.
• Todas as trocas de token devem ser via HTTPS.

2. OAuth baseado em navegador (redirect localhost)#

Este é o método mais comum para CLIs rodando na máquina local do desenvolvedor. Você executa login, seu navegador abre, você autentica, e o navegador redireciona para um servidor local temporário criado pelo CLI. Implementações modernas usam PKCE (pronuncia-se "pixie"), que torna o fluxo bem mais seguro.

Quem usa: Claude Code, gcloud CLI, Terraform CLI, AWS CLI v2.22+ (para SSO, com PKCE como padrão)

Como funciona#

1. Você executa cli login
2. O CLI inicia um servidor HTTP temporário em uma porta local aleatória (tipo http://127.0.0.1:8742)
3. Ele abre seu navegador padrão no endpoint de autorização do provedor, passando essa URL localhost como redirect URI
4. Você autentica no navegador (SSO, senha, passkeys ou o que for suportado)
5. O provedor redireciona seu navegador para http://127.0.0.1:8742/callback?code=XXXX&state=YYYY
6. O servidor local captura o código de autorização, troca por tokens via um pedido HTTPS back-channel
7. O navegador mostra uma tela "Sucesso! Você pode fechar esta aba"
8. O CLI armazena os tokens e encerra o servidor local

A experiência do usuário é suave. Sem copiar códigos, sem digitar URLs. Apenas uma aba do navegador que abre e fecha.

Limitações#

Isso só funciona quando o CLI pode abrir um navegador e escutar no localhost. Isso exclui:

• Sessões SSH em servidores remotos
• Containers Docker (a menos que você faça malabarismos com port forwarding)
• Pipelines CI/CD
• Servidores headless
• Alguns ambientes corporativos restritos

Por isso a maioria das ferramentas que usam OAuth pelo navegador também tem um fallback, normalmente device code flow ou API keys.

Três erros comuns de segurança#

Erro 1: Bind no 0.0.0.0 ao invés de 127.0.0.1

Esse é o erro mais frequente, e é grave. Se seu servidor de callback escuta em todas as interfaces, qualquer um na rede pode interceptar o código de autorização.

Já vi isso em CLIs de produção. Muitos frameworks de servidor HTTP usam 0.0.0.0 por padrão.

Erro 2: Falta de validação do parâmetro state

O parâmetro state é sua proteção contra CSRF. Sem ele, um atacante pode enganar seu CLI para aceitar um código de autorização de uma sessão maliciosa.

Erro 3: Não usar PKCE

Se seu fluxo OAuth não usa PKCE (Proof Key for Code Exchange), o código de autorização pode ser interceptado e reutilizado.

No fluxo padrão de authorization code, se um atacante intercepta o código (pela rede ou lendo a URL de redirect), pode trocar por tokens. PKCE impede isso exigindo prova de que quem troca o token é o mesmo que iniciou a autorização.

O que PKCE adiciona ao fluxo:

1. Antes de iniciar, o CLI gera um code_verifier aleatório (string de alta entropia)
2. Cria um code_challenge aplicando hash SHA-256
3. O challenge vai na requisição de autorização
4. Ao trocar o código por tokens, envia o code_verifier
5. O servidor checa se verificador e challenge batem

Um atacante sem o code_verifier não conclui a troca.

Por isso o AWS CLI v2.22+ tornou PKCE padrão para SSO, deixando o device code flow para quem não pode abrir navegador local. Quando um browser está disponível na mesma máquina, OAuth com PKCE é melhor: mesma UX, segurança maior, sem vetor de phishing. Device code flow ainda serve para quando o navegador não pode estar na mesma máquina (SSH, containers, dev remoto), mas não é o caso comum do desenvolvimento local.

3. API keys e personal access tokens#

A abordagem mais simples. Você gera um token no painel web, cola na config do CLI ou numa variável de ambiente, e pronto.

Quem usa: Stripe CLI (como opção de login), npm, pip, maioria das ferramentas de IA como fallback (Claude Code via ANTHROPIC_API_KEY, OpenAI via OPENAI_API_KEY, Aider)

Como funciona#

1. Faça login no painel web do serviço
2. Vá em configurações → API keys (ou personal access tokens, ou developer tokens)
3. Gere uma nova chave, normalmente uma string aleatória longa com prefixo (ex: sk_live_, ghp_, npm_)
4. Armazene em arquivo de config (~/.config/stripe/config.toml, ~/.aws/credentials) ou variável de ambiente

O CLI lê na inicialização e usa em requisições API, como um token Bearer no header Authorization.

Por que ainda é popular apesar dos riscos#

Para automação, API keys são imbatíveis. Funcionam em CI/CD, containers, scripts, cron jobs. Qualquer lugar que leia variável de ambiente. Não precisa de navegador. Sem prompts interativos. Sem necessidade de refresh de token.

Para fluxos com agentes de IA, API key é o caminho mais fácil. O Claude Code ou Cursor precisam chamar uma API — basta uma variável de ambiente com API key.

Os riscos são reais#

• Vazamentos. API keys vão parar em commits git, logs, mensagens de erro, saídas do CI. O GitHub busca tokens expostos e relata mais de um milhão vazados por ano.
• Permissões excessivas. Quase todas dão acesso amplo. Se vazarem, o estrago é grande.
• Sem MFA. API keys ignoram seu multi-fator configurado.
• Difícil de rotacionar. Ao trocar uma, tem que atualizar onde estiver armazenada. Em times, vira um problema de coordenação.

Melhoria moderna: troca por tokens temporários#

A jogada inteligente ao usar API keys: troque por tokens de curta duração em tempo de execução.

A AWS popularizou isso com STS (Security Token Service). Suas credenciais longas só servem para pedir credenciais temporárias válidas por 1h. Ferramentas como aws-vault automatizam tudo.

Mesmo começando com API keys, considere adicionar esse padrão. Ele reduz a janela de dano de "até alguém perceber" para "uma hora".

4. Client credentials flow#

Esse fluxo OAuth 2.0 é para autenticação máquina-máquina: serviços conversando entre si, sem humanos envolvidos.

Usado em: CI/CD pipelines, serviços de background, automações

Como funciona#

O serviço envia client_id e client_secret direto para o servidor de autenticação e recebe um access token temporário. Sem navegador, sem interação, sem redirecionamento.

Quando usar#

Use client credentials quando:

• Um serviço ou bot precisa se autenticar, não um humano
• Está num pipeline CI/CD
• Precisa de acesso automatizado e sem supervisão
• O "usuário" é a aplicação em si

Não use para autenticação de humanos. Não suporta MFA, SSO nem verificação interativa.

O que os CLIs famosos realmente usam#

Aqui está um resumo correto baseado na documentação e código fonte atuais. Muitos artigos erram porque as ferramentas mudam o padrão com frequência.

A tendência é clara: OAuth navegador é padrão para dev local, device code flow é fallback para headless, API keys para automação. PKCE cresce como opção mais segura quando navegador está disponível.

Armazenamento de tokens: o que usar e o que evitar#

Fazer a autenticação certa de nada adianta se guardar o token errado.

O certo: chaveiros do sistema operacional#

Todo SO tem um cofre de credenciais embutido e criptografado:

• macOS: Keychain (usado por GitHub CLI, Claude Code)
• Windows: Credential Manager
• Linux: Secret Service API (GNOME Keyring, KDE Wallet)

Eles fornecem criptografia, controle de acesso e integração com hardware. Seu CLI não precisa implementar cripto por conta própria.

Alternativa: arquivos criptografados#

Quando não dá para usar chaveiro (containers, Linux minimalista), use arquivos criptografados e permissões restritas:

O que evitar#

Arquivos texto puro. Parece óbvio, mas há ferramentas que ainda fazem isso. Um arquivo texto com token pode ser lido por qualquer processo do seu usuário, ferramenta de backup, ou alguém com acesso temporário à máquina.

Variáveis de ambiente para armazenamento longo. Variáveis de ambiente aparecem em listagens de processos, logs de crash, e são herdadas por processos filhos. Ótimas para CI/CD (onde a plataforma protege o segredo), mas arriscadas para desenvolvimento local.

Browser localStorage. Se seu CLI possui componente web, não guarde tokens em localStorage. Um XSS expõe tudo.

Gerenciamento do ciclo de vida do token#

Access tokens#

Devem ser de curta duração. Uma hora é padrão. Quando expira, o CLI faz refresh automaticamente. O usuário não precisa fazer login de novo em operações comuns.

Refresh tokens#

Refresh tokens são credenciais de longa duração que permitem conseguir novos tokens sem reautenticar. São alvos valiosos por durarem dias ou meses.

Rotação de refresh token#

Sistemas modernos rotacionam o refresh token a cada uso:

1. CLI envia refresh token para obter novo access token
2. O servidor retorna novo access token e novo refresh token
3. O antigo é invalidado imediatamente
4. CLI armazena os dois novos

Assim, se o refresh token for roubado, ao tentar usar ele após o legítimo, o servidor detecta o reuso e invalida toda a família do token. O token do invasor e do usuário legítimo param de funcionar, forçando novo login, mas bloqueando o atacante de manter acesso.

Erros comuns (com código)#

1. Bind do callback server em todas as interfaces#

Já falado acima, mas vale repetir: sempre use 127.0.0.1, nunca 0.0.0.0.

2. Logar tokens#

Isso acontece mais do que se admite. Um log de debug, handler de erro que despeja headers, modo verbose que imprime tudo.

3. Incluir credenciais em imagens de container#

Imagens Docker não são cofres. Cada layer é extraível.

4. Não tratar expiração de token direito#

Se um token expirar no meio da operação, não falhe com erro 401. Tente um refresh, só peça login se o refresh também expirou.

5. Ignorar o princípio de menor privilégio#

Não peça scope admin:* quando só precisa de repo:read. Vale para OAuth scopes e permissões de API key.

Quando um agente de IA usa seu CLI, isso é crucial. Você provavelmente não quer o assistente IA com permissão de deletar-repositório só para ler código.

O desafio dos agentes de IA#

O que faz 2026 ser diferente de 2023: CLIs não são só para humanos digitando comandos. Agentes de IA como Claude Code, Codex e Cursor (modo agent) chamam CLIs programaticamente. Isso cria novos desafios:

Permissões delegadas. Quando Claude Code faz gh pr create, usa suas credenciais do GitHub. Mas será que o agente deve ter os mesmos privilégios que você? O princípio de menor privilégio diz que não, mas quase nenhuma ferramenta permite restringir as permissões do agente.

Exposição de credenciais. Se sua API key está na env var, todo processo pode ler, inclusive o subprocesso do agente. Ferramentas como Claude Code mitigam com scripts apiKeyHelper que geram tokens temporários sob demanda, mas não é universal ainda.

Autenticação headless para agentes. Um agente de IA sandboxed não pode abrir navegador. Device code flow funciona (humano aprova em outro dispositivo), mas API keys ainda são a solução mais comum pois não exigem interação.

Trilhas de auditoria. Quando o agente faz chamadas API com suas credenciais, o log mostra você fez. Não existe hoje um padrão para separar "o humano fez" de "o agente fez em nome do humano".

Esse campo evolui rápido. O que fazer agora:

• Use tokens restritos/minimais para workflows de agente
• Prefira credenciais de curta duração (temporal, não API keys longas)
• Use credenciais dedicadas para agentes, separadas das suas pessoais
• Monitore o uso das APIs para padrões suspeitos

Framework de decisão#

Precisa escolher um método?

"Meus usuários são desenvolvedores em máquinas locais" → OAuth navegador com PKCE (máxima segurança + UX suave)

"Meu CLI precisa rodar via SSH e containers" → Device code flow como fallback, OAuth navegador como primário

"Roda em CI/CD sem humano" → Client credentials flow ou API keys restritos

"Quero implementar rápido" → API keys (mas adicione rotação depois)

"Clientes enterprise precisam de SSO e MFA" → Qualquer fluxo OAuth (device code ou navegador), suporta tudo corporativo

"Agentes de IA vão usar este CLI" → Suporte API keys (para integração fácil de agente) + OAuth navegador (para humanos), com permissões restritas e tokens de curta duração

FAQ#

Device code flow é seguro?#

É seguro contra a maioria dos ataques, mas tem vulnerabilidade de phishing conhecida. Um atacante pode criar device code e enganar o usuário para autorizar. Por isso a AWS adotou PKCE como padrão no SSO login. Para ambientes headless onde PKCE não é viável, device code flow ainda é a melhor opção. Apenas fique atento ao risco de phishing.

Posso guardar tokens em variáveis de ambiente?#

Em CI/CD: sim — a plataforma cifra elas em disco e injeta só na execução. Para desenvolvimento local: não. Use o chaveiro do SO. Variáveis de ambiente aparecem em listagens de processos, logs, e são herdadas pelos filhos.

Diferença entre API key e personal access token?#

Na prática, pouca. Ambos são credenciais longas para autenticar APIs. O uso é principalmente organizacional: API keys normalmente valem para apps/projetos, personal access tokens são atrelados à conta de usuário. Alguns serviços usam termos de modo intercambiável.

Com que frequência devo rotacionar credenciais?#

Access tokens: a cada hora ou menos (o refresh é automático). Refresh tokens: rode a rotação a cada uso (via servidor). API keys: no mínimo a cada 90 dias, ou imediatamente ao suspeitar de vazamento. Na prática, times só rotacionam API key após incidente — o que é tarde demais.

Como tratar autenticação em containers Docker?#

Três opções, na ordem de prioridade:

1. Device code flow para uso interativo (funciona pois navegador pode ser em outro dispositivo)
2. Variáveis de ambiente passadas no runtime (docker run -e API_KEY=${API_KEY}) em CI/CD
3. Credenciais montadas por volume (docker run -v ~/.config/tool:/root/.config/tool:ro) no dev local

Nunca coloque credenciais na imagem. Nunca.

E a autenticação MCP (Model Context Protocol)?#

MCP é o padrão emergente para agentes de IA conectarem com ferramentas externas. Traz uma nova dimensão: o agente precisa de credenciais para o servidor MCP, que por sua vez precisa de credencial para APIs downstream. Isso está em padronização. No momento, MCP usa API key ou OAuth passado na config. Isso pode evoluir rápido.

---

A autenticação CLI está mudando rápido. O que era boa prática dois anos atrás (device code flow como padrão, arquivos de credencial texto) já está sendo substituído. Se vai adicionar autenticação a um CLI hoje, comece com OAuth navegador + PKCE para humanos, API keys para automação, e pense no dia em que agentes de IA serão seus principais usuários.