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

Cada CLI de programador vem com login como o seu primeiro comando. E cada uma resolve a autenticação de forma diferente.

O GitHub mostra-te um código e abre o browser para o verificares. A AWS abre um browser para SSO baseado em PKCE. A Stripe pede-te para confirmares um código de emparelhamento no dashboard. As ferramentas de IA mais recentes (Claude Code, OpenAI Codex CLI, Cursor) também escolheram cada uma o seu próprio método.

Se estás a construir uma CLI, a autenticação é uma das primeiras coisas que tens de definir. Se escolheres o método errado, vais dar por isso: utilizadores frustrados, auditorias de segurança, ou ambos. E com a recente vaga de agentes de codificação IA que chamam ferramentas CLI de forma programática, o risco é maior: já não estás apenas a autenticar um humano. Podes estar a passar credenciais a um processo autónomo.

Aqui estão os quatro métodos de autenticação que interessam, como as maiores ferramentas os implementam, e os erros que deves evitar.

Os quatro métodos em resumo#

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

Todos têm trade-offs. Eis o que precisas saber sobre cada um.

1. Fluxo de código de dispositivo OAuth (RFC 8628)#

Este é aquele em que a tua CLI mostra-te um código como ABCD-1234 e um URL, depois diz-te para abrires esse URL em qualquer dispositivo e inserires o código.

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

Como funciona#

1. Corres o comando cli login
2. A CLI pede um código de dispositivo ao servidor de autenticação, enviando o seu client_id e os scopes pedidos
3. O servidor devolve três coisas: um device_code (identificador interno), um user_code (o código curto que escreves) e um verification_uri (onde deves ir)
4. A CLI mostra o código e o URL, e começa a fazer polling ao servidor de autenticação a cada 5+ segundos
5. Abres o URL em qualquer dispositivo (telemóvel, portátil, outro computador), escreves o código e autenticas-te como quiseres (password, SSO, passkeys, MFA)
6. Assim que aprovas, o próximo polling devolve um access token e refresh token
7. A CLI guarda-os e estás autenticado

Porque é que os programadores gostam#

A grande vantagem: funciona em qualquer lado. Sessão SSH a um servidor remoto? Funciona. Dentro de um contentor Docker? Funciona. IDE cloud sem browser local? Funciona. O browser não precisa de estar na mesma máquina que a CLI.

Também suporta todo o tipo de autenticação enterprise (SAML, OIDC, MFA), porque isso acontece todo no browser, não no terminal. A CLI nunca vê a tua password.

O problema de segurança que a maioria ignora#

O fluxo de código de dispositivo tem um problema de phishing. Um atacante pode iniciar um pedido de device code, obter um user code legítimo e enganar-te a inseri-lo, autorizando efetivamente a sessão do atacante. Não é teórico. Investigadores de segurança documentaram este ataque contra a autenticação de device code do AWS SSO.

Isto é suficientemente grave para que a AWS tenha mudado o padrão. Desde a AWS CLI v2.22.0, o padrão para aws sso login mudou do fluxo de código de dispositivo para o fluxo de código de autorização baseado em PKCE. O device code continua disponível via --use-device-code, mas já não é o caminho principal.

Enquanto isso, o próprio tenant da Microsoft começou a bloquear totalmente device code flow com políticas de acesso condicional, o que indica claramente que consideram-no de alto risco.

Portanto, temos uma divisão interessante: a Vercel adotou device code flow como padrão em setembro de 2025, enquanto a AWS se afastou dele. O padrão parece ser que device code flow é ótimo para ambientes onde não há mesmo possibilidade de abrir um browser, mas, se o consegues abrir localmente, o PKCE é mais seguro.

Do lado dos fornecedores de autenticação, a procura está claramente a aumentar. O Logto lançou recentemente suporte para OAuth 2.0 Device Authorization Grant para apps nativas na v1.38.0 (open source) e Logto Cloud, por isso agora podes ativar o flow de dispositivo como método de autorização para qualquer aplicação nativa. Isto importa se estiveres a construir uma CLI. Implementar o RFC 8628 corretamente (expiração do código, rate limit, polling, UX da página de verificação) dá mais trabalho do que a maioria espera, e se o teu fornecedor de autenticação tratar disso, só tens de fazer os pedidos HTTP certos.

Detalhes técnicos do RFC#

Alguns pontos a saber do RFC 8628:

• O valor de expires_in para os device codes é definido pelo servidor. O RFC usa 1800 segundos (30 minutos) como exemplo, mas não é obrigatório.
• Se o servidor não indicar o interval de polling, os clientes devem assumir 5 segundos.
• Se receberes um erro slow_down, adiciona 5 segundos ao intervalo.
• Device codes devem ser single-use e expirar rapidamente.
• As trocas de tokens devem ser feitas sempre via HTTPS.

2. OAuth baseado em browser (redirect para localhost)#

Este é o método mais comum para CLIs a correr na máquina local do developer. Corres login, o browser abre, autenticas-te e o browser faz redirect para um servidor local temporário criado pela CLI. Implementações modernas adicionam PKCE (pronuncia-se "pixie"), tornando o fluxo muito mais difícil de atacar.

Quem usa: Claude Code, gcloud CLI, Terraform CLI, AWS CLI v2.22+ (para SSO, com PKCE por defeito)

Como funciona#

1. Corres o comando cli login
2. A CLI inicia um servidor HTTP temporário numa porta aleatória local (ex: http://127.0.0.1:8742)
3. Abre o browser predefinido no endpoint de autorização do fornecedor, passando o URL localhost como redirect URI
4. Autenticas-te no browser (SSO, password, passkeys, o que o fornecedor suportar)
5. O fornecedor de autenticação faz redirect do browser para http://127.0.0.1:8742/callback?code=XXXX&state=YYYY
6. O servidor local captura o código de autorização, troca-o por tokens via HTTPS em back-channel
7. O browser mostra uma página "Sucesso! Podes fechar este separador"
8. A CLI guarda os tokens e termina o servidor local

A experiência do utilizador é suave. Não há códigos para copiar, nem URLs para escrever. Só um separador que abre e fecha.

Quando corre mal#

Só funciona quando a CLI pode abrir um browser e ligar à localhost. Isto exclui:

• Sessões SSH a servidores remotos
• Contentores Docker (a menos que faças ginásticas de port forwarding)
• Pipelines CI/CD
• Servidores headless
• Certos ambientes corporativos restritos

Por isso, a maioria das ferramentas que usam OAuth por defeito também suportam fallback, normalmente device code flow ou chaves API.

Três armadilhas de segurança que continuam a aparecer#

Armadilha 1: Ligar às interfaces 0.0.0.0 em vez de 127.0.0.1

É o erro mais comum e é grave. Se o teu servidor de callback ouvir em todas as interfaces, qualquer pessoa na mesma rede pode intercetar o código de autorização.

Já vi isto em CLIs em produção. É fácil errar porque muitas bibliotecas de servidores HTTP têm como padrão 0.0.0.0.

Armadilha 2: Não validar o parâmetro state

O parâmetro state é a tua proteção CSRF. Sem ele, um atacante pode enganar a tua CLI e ela aceitar um código de uma sessão maliciosa.

Armadilha 3: Não usar PKCE

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

Num fluxo standard de autorização, se um atacante intercetar o código (na rede ou ao ler o URL de redirect), pode trocá-lo por tokens. O PKCE previne isto, obrigando a provar que a troca de tokens foi iniciada pelo mesmo cliente que fez o pedido de autorização.

Veja como o PKCE melhora o fluxo:

1. Antes de iniciar, a CLI gera um code_verifier aleatório (string de alta entropia)
2. Cria um code_challenge ao fazer hash SHA-256 do verifier
3. O challenge vai no pedido de autorização
4. Ao trocar o código por tokens, a CLI envia o code_verifier original
5. O servidor de autenticação verifica se o verifier bate certo com o challenge

Um atacante que intercete o código não tem o code_verifier e não consegue concluir a troca.

É por isso que a AWS CLI v2.22+ tornou o PKCE o padrão para SSO, deixando device code flow. Se a CLI pode abrir o browser na mesma máquina, OAuth com PKCE é superior — mesma UX, segurança mais forte, sem vetor de phishing. O device code flow continua a ser o ideal quando o browser não pode estar na mesma máquina (SSH, contentores, ambientes de dev remotos), mas isso não é o caso comum em desenvolvimento local.

3. Chaves API e personal access tokens#

A abordagem mais simples. Geras um token no dashboard web, colas no ficheiro de config da CLI ou numa variável de ambiente, e já está.

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

Como funciona#

1. Faz login no dashboard web da plataforma
2. Vai às definições → chaves API (ou tokens de acesso pessoal, ou developer tokens)
3. Gera uma chave nova, normalmente string longa aleatória com prefixo (ex: sk_live_, ghp_, npm_)
4. Guarda-a num ficheiro de config (~/.config/stripe/config.toml, ~/.aws/credentials) ou variável de ambiente

A CLI lê-a ao arrancar e inclui-a nos pedidos API, normalmente como token Bearer no header Authorization.

Porque ainda é popular mesmo com os riscos#

Para automação, as chaves API são difíceis de bater. Funcionam em CI/CD, contentores, scripts, cron jobs. Tudo o que possa ler variáveis de ambiente. Não precisas de browser. Não há prompts interativos. Não tens de refrescar tokens.

Especialmente nos fluxos de agentes IA, as chaves API são o caminho mais fácil. Se o Claude Code ou Cursor precisa de chamar uma API, uma variável de ambiente com a chave resolve logo.

Os riscos são reais#

• Fugas. Chaves API acabam em commits git, ficheiros de log, mensagens de erro e output de CI. O GitHub faz scans a tokens expostos e reporta mais de um milhão de fugas por ano.
• Permissões a mais. A maioria das chaves API tem acesso largo. Se forem expostas, o dano pode ser grande.
• Sem MFA. Chaves API ignoram a tua MFA bem configurada.
• Difícil de rodar. Sempre que rodas uma chave, tens de atualizar em todo o lado onde estiver guardada. Em equipas, torna-se um desafio de coordenação.

Melhoria moderna: troca por tokens temporários#

A melhor prática com chaves API: trocá-las por tokens de curta duração em runtime.

A AWS foi pioneira com o STS (Security Token Service). As credenciais de longa duração só servem para pedir credenciais temporárias que expiram em uma hora. Ferramentas como a aws-vault automatizam isto completamente.

Mesmo que comeces com chaves API, considera adotar este padrão. Isto limita a janela de dano de uma chave comprometida de "até alguém reparar" para "uma hora".

4. Fluxo de credenciais do cliente#

Este fluxo OAuth 2.0 é para autenticação máquina-para-máquina: serviços a falar com serviços, sem humanos envolvidos.

Usado em: pipelines CI/CD, serviços de background, tooling automatizado

Como funciona#

O serviço envia o client_id e client_secret diretamente ao servidor de autenticação e recebe um access token temporário. Sem browser, sem interação, sem redirect.

Quando usar#

Usa client credentials quando:

• Um serviço ou bot precisa autenticar-se, não um humano
• Estás num pipeline CI/CD
• Precisas de acesso automático, sem interação
• O "utilizador" é a aplicação

Não uses para autenticação de humanos. Não suporta MFA, SSO, nem nenhum método interativo.

O que as CLIs reais realmente usam#

Aqui está uma tabela corrigida baseada em documentação e código-fonte atual. Muitos artigos erram nisto porque as ferramentas mudam os padrões frequentemente.

A tendência é clara: OAuth baseado em browser é o padrão para desenvolvimento local, com device code flow como fallback para ambientes headless e chaves API para automação. O PKCE está a tornar-se o padrão mais seguro quando o browser está disponível.

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

Acertar na autenticação não serve se guardares os tokens de forma errada.

O certo: keychains do sistema operativo#

Todos os principais OS têm um gestor de credenciais encriptado:

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

Oferecem encriptação de nível OS, controlo de acesso e integração com hardware. A tua CLI não precisa de implementar criptografia.

O fallback: ficheiros encriptados#

Quando não há keychain disponível (contentores, Linux minimalista), usa ficheiros encriptados com permissões restritas:

O que evitar#

Ficheiros em texto simples. Devia ser óbvio, mas muitas ferramentas ainda o fazem. Ficheiros de token em texto simples estão acessíveis a todos os processos do utilizador, ferramentas de backup e quem tiver acesso temporário à máquina.

Variáveis de ambiente para armazenamento a longo prazo. São visíveis no ps, muitas vezes aparecem em logs de crash, e passam para processos filhos. São aceitáveis em CI/CD (onde a própria plataforma gere o segredo), mas arriscadas em desenvolvimento local.

localStorage do browser. Se a tua CLI tiver componente web, não guardes tokens aqui. Uma XSS e está tudo exposto.

Gestão do ciclo de vida dos tokens#

Access tokens#

Mantém-os de duração curta. Uma hora é o padrão. Ao expirar, a CLI deve refrescar automaticamente. O utilizador não deve precisar de fazer re-login para operações normais.

Refresh tokens#

São as credenciais longas que permitem pedir access tokens sem reautenticar. São alvos de alto valor pelos atacantes devido à sua longevidade (dias a meses).

Rotação de refresh tokens#

Sistemas modernos rodam refresh tokens a cada uso:

1. A CLI envia o refresh token para obter novo access token
2. O servidor devolve um novo access token e um novo refresh token
3. O refresh token anterior é logo invalidado
4. A CLI guarda ambos os tokens

Isto limita o impacto de um refresh token roubado. Se um atacante tentar usar um refresh token já usado pela CLI legítima, o servidor deteta o reuse e invalida a família toda de tokens. Tanto o token roubado como o atual deixam de funcionar, forçando um novo login mas bloqueando o atacante.

Armadilhas comuns (com código)#

1. Servidor de callback ligado a todas as interfaces#

Já abordado acima, mas vale repetir: liga sempre a 127.0.0.1, nunca a 0.0.0.0.

2. Logging de tokens#

Acontece mais vezes do que se admite. Um log de debug, handler de erro que despeja headers, modo verbose que mostra tudo.

3. Incluir credenciais em imagens de contentores#

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

4. Não lidar corretamente com expiração de tokens#

Quando um token expira a meio de uma operação, não crashar com erro 401. Tenta refrescar, só pedindo autenticação se o refresh token também estiver expirado.

5. Ignorar princípio do mínimo privilégio#

Não peças admin:* se só precisas de repo:read. Vale para scopes OAuth e permissões de chaves API.

Quando um agente IA usa a tua CLI, isto torna-se ainda mais crítico. Provavelmente não queres que um assistente de IA tenha perms para apagar repositórios só porque precisa de ler código.

O fator agente IA#

Aqui está o que torna 2026 diferente de 2023: CLIs já não servem só para humanos a escrever comandos. Agentes de código IA como Claude Code, Codex, e o modo agente do Cursor chamam CLIs programaticamente. Isto levanta novos desafios:

Permissões delegadas. Quando o Claude Code corre gh pr create por ti, está a usar as tuas credenciais GitHub. Mas um agente IA deve ter as mesmas permissões que tu? O princípio do mínimo privilégio diz que não, mas quase nenhuma ferramenta permite limitar permissões só ao agente.

Exposição de credenciais. Se a tua chave API está numa variável de ambiente, qualquer processo pode lê-la, incluindo subprocessos do agente IA. Ferramentas como o Claude Code já resolveram isto com scripts apiKeyHelper que geram tokens de curta duração on demand, mas ainda não é universal.

Auth headless para agentes. Um agente IA num ambiente isolado não pode abrir um browser. Device code flow funciona aqui (humano aprova noutro dispositivo), mas o mais comum é a chave API porque não exige interação.

Auditoria. Quando um agente faz chamadas API com as tuas credenciais, os logs mostram tu a fazeres as chamadas. Não há standard para distinguir "foi humano" de "foi o agente pelo humano".

Isto está a evoluir rápido. O melhor que podes fazer já:

• Usa tokens com scopes mínimos para workflows de agente
• Prefere credenciais de curta duração (tokens temporários, não chaves API de longa duração)
• Usa credenciais dedicadas para agentes, separadas das tuas pessoais
• Monitora uso API para padrões estranhos

Framework de decisão#

A escolher método de auth? Eis o resumo:

"Os meus utilizadores são devs nas suas máquinas" → OAuth baseado em browser com PKCE (máxima segurança + UX suave)

"A minha CLI precisa de funcionar em SSH e contentores" → Device code flow como fallback, browser OAuth como principal

"Isto corre em CI/CD sem humanos" → Client credentials flow ou chaves API com scope

"Quero implementar rapidamente" → Chaves API (mas adiciona rotação depois)

"Clientes enterprise precisam de SSO/MFA" → Qualquer fluxo OAuth (device code ou browser), que dá stack completo de enterprise auth

"Agentes IA vão usar esta CLI" → Suporta chaves API (integração fácil de agente) + browser OAuth (para humanos), sempre com scopes mínimos e tokens de curta duração

FAQ#

Device code flow é seguro?#

É seguro contra a maioria dos ataques, mas tem uma vulnerabilidade conhecida de phishing. Um atacante pode gerar um device code e enganar utilizadores a autorizá-lo. É por isso que a AWS mudou para PKCE como padrão em SSO login. Para ambientes headless onde PKCE não é prático, o device code flow continua a ser a melhor opção. Mas tens de estar atento ao risco de phishing.

Devo guardar tokens em variáveis de ambiente?#

Para CI/CD: sim, porque a plataforma CI os encripta em disco e injeta no runtime. Para desenvolvimento local: não. Usa o keychain do SO. Variáveis de ambiente aparecem em processos, podem ser logadas ou vazadas a processos filhos.

Qual a diferença entre uma chave API e um personal access token?#

Na prática, pouca. Ambos são credenciais de longa duração para autenticar pedidos API. A diferença é sobretudo organizacional: chaves API são associadas a um projeto ou app, PATs tendem a ficar ligados à conta do utilizador. Alguns serviços usam os termos como sinónimos.

Com que frequência devo rodar credenciais?#

Access tokens: a cada hora ou menos (feito automaticamente pelo refresh). Refresh tokens: gira a rotação a cada uso (o servidor trata disso). API keys: pelo menos a cada 90 dias, ou imediatamente se suspeitares de fuga. Na prática, a maioria só roda depois de problemas, o que é tarde.

Como faço autenticação em contentores Docker?#

Três opções, por ordem de preferência:

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

Nunca incluas credenciais na imagem. Nunca.

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

O MCP é o novo standard para agentes IA ligarem-se a ferramentas e serviços externos. Introduz uma dimensão extra: o agente precisa de credenciais para o MCP server, que precisa de credenciais para downstream APIs. Isto ainda está a ser standardizado. Por agora, quase todos usam chaves API ou tokens OAuth passados na config do MCP. Espera que evolua depressa.

---

A autenticação CLI está a mudar rápido. O que era best practice há dois anos (device code flow por defeito, ficheiros de credencial em texto simples) já está a ser substituído. Se estás a adicionar auth numa CLI hoje, começa com OAuth + PKCE para humanos, chaves API para automação, e prepara-te para o dia em que agentes IA são os teus principais utilizadores.