Os 4 métodos de autenticação CLI que importam, como GitHub, AWS e ferramentas de IA os implementam e os erros de segurança que deves evitar.
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.
Antes de aprofundar, aqui está a comparação rápida:
| Método | Melhor para | Segurança | Precisa de browser? |
|---|---|---|---|
| Fluxo de Código de Dispositivo OAuth | Ambientes headless, SSH | Elevada | Não (na mesma máquina) |
| OAuth baseado em browser (redirect para localhost) | Desenvolvimento local | Máxima | Sim |
| Chaves API / PATs | Automação, CI/CD, criação de protótipos rápida | Moderada | Não |
| Credenciais do Cliente | Máquina-para-máquina, serviços | Elevada | Não |
Todos têm trade-offs. Eis o que precisas saber sobre cada um.
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)
cli loginclient_id e os scopes pedidosdevice_code (identificador interno), um user_code (o código curto que escreves) e um verification_uri (onde deves ir)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 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.
Alguns pontos a saber do RFC 8628:
expires_in para os device codes é definido pelo servidor. O RFC usa 1800 segundos (30 minutos) como exemplo, mas não é obrigatório.interval de polling, os clientes devem assumir 5 segundos.slow_down, adiciona 5 segundos ao intervalo.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)
cli loginhttp://127.0.0.1:8742)http://127.0.0.1:8742/callback?code=XXXX&state=YYYYA experiência do utilizador é suave. Não há códigos para copiar, nem URLs para escrever. Só um separador que abre e fecha.
Só funciona quando a CLI pode abrir um browser e ligar à localhost. Isto exclui:
Por isso, a maioria das ferramentas que usam OAuth por defeito também suportam fallback, normalmente device code flow ou chaves API.
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:
code_verifier aleatório (string de alta entropia)code_challenge ao fazer hash SHA-256 do verifiercode_verifier originalUm 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.
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)
sk_live_, ghp_, npm_)~/.config/stripe/config.toml, ~/.aws/credentials) ou variável de ambienteA CLI lê-a ao arrancar e inclui-a nos pedidos API, normalmente como token Bearer no header Authorization.
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.
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".
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
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.
Usa client credentials quando:
Não uses para autenticação de humanos. Não suporta MFA, SSO, nem nenhum método interativo.
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.
| Ferramenta CLI | Auth por defeito | Opções fallback | Armazenamento de tokens |
|---|---|---|---|
GitHub CLI (gh) | Device code flow via browser | PAT (--with-token), env var (GH_TOKEN) | Keychain do OS (fallback: ficheiro texto) |
| AWS CLI v2 | PKCE auth code flow (SSO) | Device code (--use-device-code), ficheiro de credenciais | ~/.aws/sso/cache/ |
Azure CLI (az) | WAM em Windows; browser auth em Linux/macOS | Device code (--use-device-code) | ~/.azure/msal_token_cache.* |
| Vercel CLI | Device code flow (novo padrão, set 2025) | Token API (--token, env var) | ~/.local/share/com.vercel.cli/auth.json |
| Stripe CLI | Emparelhamento via browser | API key (--interactive, --api-key, ou env var) | ~/.config/stripe/config.toml |
| gcloud CLI | Browser OAuth | --no-browser (manual) | ~/.config/gcloud/ |
| Claude Code | Browser OAuth | API key (env var, apiKeyHelper) | Keychain do OS / ~/.claude/.credentials.json |
| OpenAI Codex CLI | Browser OAuth | Device code (beta), API key | ~/.codex/auth.json / keyring do OS |
| Terraform CLI | Browser OAuth | Colar token | ~/.terraform.d/credentials.tfrc.json |
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.
Acertar na autenticação não serve se guardares os tokens de forma errada.
Todos os principais OS têm um gestor de credenciais encriptado:
Oferecem encriptação de nível OS, controlo de acesso e integração com hardware. A tua CLI não precisa de implementar criptografia.
Quando não há keychain disponível (contentores, Linux minimalista), usa ficheiros encriptados com permissões restritas:
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.
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.
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).
Sistemas modernos rodam refresh tokens a cada uso:
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.
Já abordado acima, mas vale repetir: liga sempre a 127.0.0.1, nunca a 0.0.0.0.
Acontece mais vezes do que se admite. Um log de debug, handler de erro que despeja headers, modo verbose que mostra tudo.
As imagens Docker não são cofres. Cada layer é extraível.
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.
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.
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á:
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
É 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.
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.
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.
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.
Três opções, por ordem de preferência:
docker run -e API_KEY=${API_KEY}) para CI/CDdocker run -v ~/.config/tool:/root/.config/tool:ro) para desenvolvimento localNunca incluas credenciais na imagem. Nunca.
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.