CLI kimlik doğrulamasını doğru yapmak: 4 yöntem için eksiksiz rehber

Her geliştirici CLI aracı, ilk komutu olarak login ile gelir. Ve her biri kimlik doğrulamayı farklı şekilde çözer.

GitHub sana bir kod gösterir ve doğrulaman için tarayıcını açar. AWS, PKCE tabanlı SSO için tarayıcıyı açar. Stripe, eşleştirme kodunu panelde onaylamanı ister. Yeni nesil AI araçları (Claude Code, OpenAI Codex CLI, Cursor) da her biri kendi yolunu seçti.

Bir CLI geliştiriyorsan, kimlik doğrulama ilk çözeceğin konulardan biridir. Yanlış yöntemi seçersen duyarsın: sinirlenen kullanıcılar, güvenlik denetimleri ya da her ikisi. Son zamanlarda CLI araçlarını programatik olarak çağıran AI kodlama ajanlarıyla beraber risk daha yüksek: artık sadece insanı değil, otonom bir süreci de yetkilendiriyorsun.

İşte önemli olan dört kimlik doğrulama yöntemi, en büyük araçlar bunları nasıl uyguluyor ve yapmaktan kaçınmak isteyeceğin hatalar.

Dört yöntemin genel görünümü#

Detaya inmeden, hızlı karşılaştırma:

Her birinin avantaj-dezavantajları var. Her biri için bilmen gerekenler:

1. OAuth cihaz kodu akışı (RFC 8628)#

Bu yöntemde CLI, sana ABCD-1234 gibi bir kod ve bir URL gösterir, sonra herhangi bir cihazdan o URL'yi açıp kodu girmeni ister.

Kullananlar: GitHub CLI (varsayılan), Azure CLI (--use-device-code ile), Vercel CLI (yakında varsayılan oldu), OpenAI Codex CLI (beta seçenek)

Nasıl çalışır#

1. cli login komutunu çalıştırırsın
2. CLI, kimlik doğrulama sunucusundan bir cihaz kodu ister, client_id ve gerekli izinleri gönderir
3. Sunucu üç şey döndürür: bir device_code (iç kimlik), bir user_code (senin girdiğin kısa kod), ve bir verification_uri (gitmen gereken adres)
4. CLI kodu ve URL’yi ekrana basar, ve ardından kimlik sunucusunu her 5+ saniyede bir yoklamaya başlar
5. Herhangi bir cihazdan URL’yi açar, kodu yazarsın ve istediğin şekilde (parola, SSO, passkey, MFA) kimliğini doğrularsın
6. Onayladığında bir sonraki yoklama erişim ve yenileme tokenini döndürür
7. CLI bunları saklar ve giriş yapmış olursun

Neden geliştiriciler seviyor#

En büyük özelliği: heryerde çalışması. Uzaktan bir sunucuya SSH ile girdin mi? Çalışır. Docker konteynerinde mi? Çalışır. Tarayıcısı olmayan bir bulut IDE’de mi? Çalışır! Tarayıcı ile CLI aynı makinede olmak zorunda değil.

Ayrıca tam kurumsal kimlik doğrulama yöntemlerinin (SAML, OIDC, MFA) tamamını da destekler. Bunun nedeni, tüm dessasmaranın tarayıcıda gerçekleşmesi, terminalde değil. CLI asla parolanı görmez.

En çok gözden kaçan güvenlik detayı#

Cihaz kodu akışının bir oltalama (phishing) problemi var. Saldırgan biri cihaz kodu isteği başlatıp geçerli bir kullanıcı kodu elde edip seni kandırabilir. Bu şekilde saldırganın oturumu onaylanır. Bu teorik bir risk değil. Güvenlik araştırmacıları bu saldırıyı AWS SSO cihaz kodu kimlik doğrulamasında belgeledi.

Bu o kadar büyük bir risk ki AWS varsayılanı değiştirdi. AWS CLI v2.22.0'dan itibaren, aws sso login için varsayılan yöntem cihaz kodu akışından PKCE tabanlı yetkilendirme kodu akışına geçti. Cihaz kodu hala --use-device-code ile kullanılabilir, ama artık varsayılan yol değil.

Bu arada, Microsoft’un kendi tenant’ı cihaz kodu akışını tamamen engellemeye başladı koşullu erişim politikaları ile — bu da onların bunu yüksek riskli bir kimlik doğrulama yöntemi olarak gördüğünün açık bir göstergesi.

Sonuçta ilginç bir ayrışma var: Vercel cihaz kodu akışını Eylül 2025’te varsayılan olarak benimsedi, AWS ise bundan uzaklaştı. Genel desen: Cihaz kodu akışı gerçekten tarayıcı açamayan ortamlar için harika, ama lokal bir tarayıcı açabiliyorsan PKCE daha güvenli tercih.

Kimlik sağlayıcı tarafında da talep artıyor. Logto kısa süre önce OAuth 2.0 Device Authorization Grant desteği ekledi, böylece native uygulamalar için cihaz akışını etkinleştirebilirsin. Bu, CLI geliştiriyorsan önemlidir. RFC 8628’i düzgün uygulamak (kod süresi, hız limiti, yoklama mantığı, doğrulama sayfasında oturum açma UX’i) çoğu zaman beklediğinden daha zordur, sağlayıcının bunu yönetmesi senin yalnızca doğru HTTP çağrılarını yapman anlamına gelir.

RFC’den teknik detaylar#

Birkaç önemli nokta:

• expires_in değeri kimlik doğrulama sunucusu tarafından belirlenir. RFC 1800 saniye (30 dakika) örneği verir ama bu sabit değildir.
• Sunucu bir yoklama interval’ı belirtmediyse, istemciler varsayılan olarak 5 saniye kullanmalı.
• slow_down hatası alınırsa, interval’e 5 saniye daha ekle.
• Cihaz kodları tek kullanımlık ve hızlı sürede geçersiz olmalı.
• Tüm token değişimleri HTTPS üzerinden olmalı.

2. Tarayıcı tabanlı OAuth (localhost yönlendirme)#

Bu yöntem geliştiricinin lokal makinesindeki CLI’lar için en yaygın yöntemdir. login çalıştırırsın, tarayıcı açılır, oturum açarsın ve tarayıcı, CLI’nın geçici olarak başlattığı lokal sunucuya geri yönlenir. Modern uygulamalar PKCE ("pixie" okunur) ekler, bu da süreci çok daha güvenli hale getirir.

Kullananlar: Claude Code, gcloud CLI, Terraform CLI, AWS CLI v2.22+ (varsayılan PKCE ile SSO’da)

Nasıl çalışır#

1. cli login komutunu çalıştırırsın.
2. CLI, rastgele bir lokal portta geçici bir HTTP sunucusu başlatır (ör. http://127.0.0.1:8742)
3. Kimlik sağlayıcının izin endpoint’ine tarayıcıyı açar, yönlendirme URI’si olarak localhost adresini iletir
4. Tarayıcıda kimliğin doğrulanır (SSO, parola, passkey vs. sağlayıcı ne destekliyorsa)
5. Kimlik sağlayıcı, tarayıcıyı http://127.0.0.1:8742/callback?code=XXXX&state=YYYY adresine yönlendirir
6. Lokal sunucu yetkilendirme kodunu yakalar, arka kanal bir HTTPS isteği ile tokenlere çevirir
7. Tarayıcıda "Başarılı! Bu sekmeyi kapatabilirsiniz" mesajı görünür
8. CLI tokenleri depolar ve lokal sunucuyu kapatır

Kullanıcı deneyimi çok akıcı: Kod kopyalamak yok, URL yazmak yok, sadece açılan bir sekme ve kapanır.

Ne zaman çalışmaz#

Bu sadece CLI bir tarayıcı açabildiğinde ve localhost’a bağlanabildiğinde çalışır. Şu ortamlar hariç:

• Uzaktaki sunuculara SSH ile girişler
• Docker konteynerleri (port yönlendirmesi yapmıyorsan)
• CI/CD boru hatları
• Arayüzsüz sunucular
• Bazı kısıtlı şirket ortamları

Bu yüzden çoğu araç tarayıcı OAuth’u varsayılan alsa da genelde yedek olarak cihaz kodu akışı veya API anahtarları desteği de sunar.

Sürekli karşılaşılan 3 güvenlik açığı#

Sorun 1: 0.0.0.0 yerine 127.0.0.1’e bağlanmak

En sık yapılan ve çok ciddi hata. Callback sunucun tüm arayüzleri dinlerse, aynı ağdaki herkes yetkilendirme kodunu yakalayabilir.

Birçok prod CLI’da bunu gördüm. Çünkü çoğu HTTP sunucu kütüphanesi varsayılan olarak 0.0.0.0 kullanır.

Sorun 2: State parametresi doğrulaması olmaması

state parametresi CSRF korumandır. Olmazsa, saldırgan CLI’nı kandırıp başka bir oturumdan gelen yetkilendirme kodunu kabul ettirebilir.

Sorun 3: PKCE kullanmamak

OAuth akışında PKCE (Proof Key for Code Exchange) yoksa, yetkilendirme kodu ele geçirilebilir ve yeniden oynatılabilir.

Normal yetkilendirme kodu akışında, eğer saldırgan authorization kodunu (ağdan veya yönlendirme URL'sinden okurken) ele geçirirse bunu token için kullanabilir. PKCE ise token değişiminin kimliği başlatan ile aynı istemciden geldiğini ispatlar ve kodu tamamlamak için gerekli olan code_verifier saldırganda olmaz.

PKCE’nin sürece ekledikleri:

1. Akış başlamadan CLI rastgele bir code_verifier üretir (yüksek entropili dize)
2. Hashleyerek code_challenge oluşturur (SHA-256 ile)
3. code_challenge ilk istekle gönderilir
4. Kod token’a dönüştürülürken CLI code_verifier’ı gönderir
5. Sunucu doğrular ki verifier ve challenge eşleşiyor mu

Yetkilendirme kodunu ele geçiren saldırganın code_verifier’ı olmadığı için akışı tamamlayamaz.

Bu yüzden AWS CLI v2.22+ SSO’da PKCE’yi varsayılan yaptı ve cihaz kodu akışından uzaklaştı. CLI lokal tarayıcı açabiliyorsa, tarayıcı OAuth + PKCE cihaz kodu akışından daha güvenli ve aynı kullanıcı deneyimini sunar. Cihaz kodu akışı ise tarayıcı aynı makinede olamıyorsa (SSH, konteynerler, uzaktan geliştirme) hâlâ en iyi seçenektir ama lokal geliştirme için yaygın durum bu değildir.

3. API anahtarları ve kişisel erişim tokenleri#

En basit yöntem: Web panelinden token üretirsin, CLI yapılandırmasına ya da ortam değişkenine yapıştırırsın, işlem tamam.

Kullananlar: Stripe CLI (giriş seçeneği olarak), npm, pip, çoğu AI kodlama aracı (Claude Code - ANTHROPIC_API_KEY, OpenAI - OPENAI_API_KEY, Aider)

Nasıl çalışır#

1. Servisin web panelinde oturum açarsın
2. Ayarlar → API anahtarları (ya da kişisel erişim tokenleri) bölümüne gidersin
3. Genelde uzun rastgele dize ve bir önek ile yeni anahtar üretirsin (ör: sk_live_, ghp_, npm_)
4. Bir ayar dosyasına (~/.config/stripe/config.toml, ~/.aws/credentials) ya da ortam değişkenine eklersin

CLI başlarken bunu okur ve API isteklerinde genellikle Authorization başlığında bir Bearer token olarak iletir.

Risklerine rağmen neden hâlâ popüler#

Otomasyon için API anahtarları çok pratiktir. CI/CD’de, konteynerde, scriptte, cron’da çalışır. Ortam değişkenini okuyabilen her yerde. Tarayıcı gerekmez. İnteraktif adım gerekmez. Token yenileme gerekmez.

Özellikle AI ajan akışlarında, API anahtarı en kolay entegrasyon noktasıdır. Claude Code veya Cursor bir API çağıracaksa, ortam değişkeniyle API anahtarı en basit yoldur.

Riskler gerçek#

• Sızıntı. API anahtarları git commit'lerine, loglara, hata mesajlarına, CI çıktısına sızar. GitHub her yıl milyonlarca token sızıntısını tarar ve raporlar.
• Aşırı ayrıcalık. Çoğu API anahtarı geniş erişim yetkisi sunar. Sızarsa veri patlama alanı büyüktür.
• MFA yok. API anahtarları, çok faktörlü kimlik doğrulamanı geçersiz kılar.
• Zor döndürme. Bir anahtarı döndürdüğünde her depolandığı yerde güncellenmeli. Takım halinde bu bir koordinasyon problemidir.

Modern geliştirme: geçici token takası#

API anahtarı kullanıyorsan akıllıca olan, onu çalışma anında kısa ömürlü token ile değiştirmektir.

AWS, STS (Security Token Service) ile bunu başlattı. Uzun ömürlü kimlik bilgileriniz yalnızca 1 saat ömürlü geçici kimlik bilgisi almak için kullanılır. aws-vault gibi araçlar bu süreci tamamen otomatikleştirir.

API anahtarı ile başlasan bile bu modeli eklemeyi düşün. Bir anahtarı sızdırmakla oluşabilecek zarar penceresini "fark edilene kadar"dan "bir saat"e indirirsiniz.

4. Client credentials flow#

Bu OAuth 2.0 akışı, makineden makineye (service-to-service) kimlik doğrulama için tasarlanmıştır: insansız servisler arası iletişim.

Kullanım alanı: CI/CD boru hatları, arka plan servisleri, otomatik araçlar

Nasıl çalışır#

Servis doğrudan kendi client_id ve client_secret’ini kimlik sunucusuna gönderir ve kısa ömürlü bir erişim token’ı alır. Tarayıcı yok, insan müdahalesi yok, yönlendirme yok.

Ne zaman kullanılır#

Şu durumlarda kullan:

• Bir servis veya bot kimlik doğrulaması yapacaksa, insan değilse
• CI/CD ortamındaysa
• Otomatik, gözetimsiz erişim gerekiyorsa
• "Kullanıcı" uygulamanın kendisiyse

İnsan kimlik doğrulaması için kullanılmaz. MFA, SSO veya interaktif doğrulamayı desteklemez.

Gerçek CLI’lar ne kullanıyor?#

Güncel dökümantasyon ve kaynak kod temel alınarak düzeltilmiş tablo. Yanlış bilgi çok çünkü araçlar sık sık varsayılanlarını değiştiriyor.

Eğilimi görmek kolay: lokal geliştirmede varsayılan tarayıcı tabanlı OAuth, arayüzsüz ortamda yedek olarak cihaz kodu akışı, otomasyon için API anahtarları. PKCE, tarayıcı olduğu sürece en güvenli yol olarak yaygınlaşıyor.

Token depolama: Ne kullanmalı, neye dikkat etmeli#

Kimlik doğrulamayı doğru yapmak, tokenleri yanlış depolarsan hiçbir işe yaramaz.

Doğru yol: OS anahtarlıkları#

Her büyük işletim sisteminde şifreli entegre kimlik bilgisi deposu vardır:

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

OS seviyesinde şifreleme, erişim kontrolü ve donanım güvenliği ile gelir. CLI’nın kendi şifrelemesini tasarlamasına gerek yoktur.

Yedek: Şifreli yapılandırma dosyaları#

Anahtarlık yoksa (konteyner, minimal Linux kurulumları), erişim izinleri kısıtlı şifreli yapılandırma dosyası kullan:

Kaçınılması gerekenler#

Düz metin dosyalar. Kulağa bariz geliyor ama hâlâ birçok araç düz metin token dosyası kullanıyor. Aynı kullanıcıyla çalışan her proses, her yedekleme aracı ve makineye geçici erişimi olan herkes buna erişebilir.

Uzun vadeli ortam değişkeni kullanımı. Ortam değişkenleri süreç listelerinde görünür, genellikle hata raporlarında loglanır, alt süreçlere miras kalır. CI/CD için uygundur (platform yönetir) ama lokal geliştirme için risklidir.

Tarayıcı localStorage. CLI'da web bileşeni varsa, tokenleri localStorage'da tutma. XSS açığıyla her şey açığa çıkar.

Token yaşam döngüsü yönetimi#

Erişim tokenleri#

Kısa ömürlü tut. Standart bir saatliktir. Token süresi bitince CLI şeffaf şekilde yenilemeli. Kullanıcı tekrar giriş yapmaya zorlanmamalı.

Yenileme tokenleri#

Yenileme tokenleri, tekrar kimlik doğrulaması olmadan yeni erişim tokeni almaya yarayan uzun ömürlü kimlik bilgileridir. Saldırganlar için yüksek değerli hedeflerdir (günlerce – aylarca yaşayabilirler).

Yenileme tokeni döndürme#

Modern sistemler her kullanımda refresh tokeni döndürür:

1. CLI, yenileme tokeni ile erişim tokeni ister
2. Sunucu yeni erişim ve yeni yenileme tokeni döndürür
3. Eski yenileme tokeni anında geçersizleşir
4. CLI yeni tokenleri kaydeder

Bir yenileme tokeni çalınırsa, bir sonraki kullanımda yasal kullanıcı altındaki yeni token çalışır; çalıntı tokeni kullanan saldırgan kalıcı erişime sahip olamaz, kullanıcı tekrar oturum açar ve saldırı bitsin.

Sık yapılan hatalar (örnek kod ile)#

1. Callback sunucusunu tüm arayüzlere bağlamak#

Yukarıda da anlatıldı, tekrarlamakta fayda var: Daima 127.0.0.1’e, asla 0.0.0.0’a bağla.

2. Tokenleri loglamak#

Çoğumuzdan daha sık oluyor. Debug log, hata işleyici, verbose mod…

3. Kimlik bilgilerini konteyner imajına gömmek#

Docker imajları gizli bilgi deposu değildir. Her layer ayrıştırılabilir.

4. Token süresi bitince düzgün işlememek#

Token süresi ortada biterse sadece 401 hatası vermek yerine önce otomatik yenilemeyi dene, ancak refresh tokeni de geçersizse yeniden giriş iste.

5. En dar yetkilendirme ilkesini görmezden gelmek#

admin:* izni isteme, sadece gerekli olanı (ör: repo:read) iste. Bu, hem OAuth izinleri hem de API anahtarlarının izinleri için geçerli.

Bir AI ajan CLI’nı kullanıyorsa, bu daha da önemli. Kod okuma için bir AI asistanına depo silme yetkisi vermek istemezsin.

AI ajan farkı#

2026 yılını 2023’ten farklı kılan: CLI'lar artık sadece insan komutları için değil. Claude Code, Codex, Cursor gibi AI kodlama ajanları CLI’ları programatik olarak çağırıyor. Bu yeni kimlik doğrulama sorunları doğuruyor:

Devirli izinler. Claude Code senin adına gh pr create çalıştırdığında senin GitHub kimlik bilgilerini kullanır. Ama bir AI ajanının seninle aynı yetkilere sahip olması gerekir mi? "En dar yetki" prensibi hayır diyor, ama çoğu araç bu imkanı desteklemez.

Kimlik bilgisi sızıntısı. API anahtarın ortam değişkenindeyse, AI ajanı alt süreç dâhil tüm süreçler görebilir. Claude Code gibi araçlar bu sorunu kısa ömürlü token üreten apiKeyHelper scriptleriyle çözüyor, ancak bu henüz yaygın değil.

Ajanlar için arayüzsüz kimlik doğrulama. Sandboxed ortamda çalışan bir AI ajanı tarayıcı açamaz. Cihaz kodu akışı burada işe yarar (insan başka cihazdan onaylar). Ama API anahtarı en çok kullanılan yoldur: sıfır etkileşimle çalışır.

Kayıt izleri. Bir AI ajan API çağrısı yaptığında audit logda sen yapmışsın gibi görünür. Şu anda "insan yaptı" ile "ajan insan adına yaptı" ayrımı yapmak için bir standart yok.

Bu alan hızlı evriliyor. Şu an yapabileceğin en iyi şey:

• Ajan iş akışları için asgari izinli, alanı daraltılmış token kullan
• Kısa ömürlü kimlik bilgilerini (geçici tokenler, uzun ömürlü API anahtarı değil) tercih et
• Ajanlar için kişisel bilgilerden ayrı kimlik bilgileri kullan
• API kullanımı olağan dışı desenler için izle

Karar çerçevesi#

Kimlik doğrulama yöntemi mi seçiyorsun? Kısa hali:

"Kullanıcılarım kendi lokal makinelerinde geliştirici" → PKCE’li tarayıcı OAuth’u (en güvenli + akıcı UX)

"CLI’m SSH oturumu ve konteynerlerde çalışmalı" → Birincil: tarayıcı OAuth; yedek: cihaz kodu akışı

"CI/CD ortamında insan müdahalesi olmadan çalışacak" → Client credentials akışı veya izinli API anahtarları

"En hızlı şekilde implementasyon istiyorum" → API anahtarı (daha sonra token döngüsü ekle)

"Kurumsal müşterilerde SSO ve MFA lazım" → Herhangi OAuth akışı (cihaz kodu ya da tarayıcı); tüm kurumsal kimlik doğrulamayı destekler

"AI ajanları bu CLI'yı kullanacak" → API anahtarı (kolay ajan entegrasyonu) + tarayıcı OAuth’u (insan için), izinli ve kısa ömürlü tokenlerle

Sıkça Sorulanlar (SSS)#

Cihaz kodu akışı güvenli mi?#

Çoğu saldırıya karşı güvenlidir, fakat bilinen bir phishing açığı vardır. Saldırgan bir kod oluşturup kullanıcıları bunu onaylatmaya kandırabilir. Bu yüzden AWS SSO girişinde varsayılanı PKCE yaptı. PKCE pratik değilse cihaz kodu akışı hala en iyi seçenektir. Sadece riskin farkında ol.

Tokenleri ortam değişkeninde mi saklamalıyım?#

CI/CD için: evet, çünkü platform onları şifreli saklar, runtime’da aktarır. Lokal geliştirme için: hayır. OS anahtarlık kullan. Ortam değişkenleri süreç listelerinde görünür, loga girer veya alt süreçlere sızabilir.

API anahtarı ile kişisel erişim tokeni arasında fark ne?#

Fonksiyonel olarak, çok az. İkisi de API isteklerini yetkilendiren uzun vadeli kimlik bilgileridir. Temelde API anahtarı genellikle proje/uygulama bazında, kişisel erişim tokeni kullanıcı hesabına özel olur. Bazı servislerde terimler birbirinin yerine de kullanılır.

Kimlik bilgilerini ne kadar sıklıkla döndürmeliyim?#

Erişim tokenleri: en fazla her saatte bir (otomatik token yenileme sürecine bırakmalısın). Yenileme tokenleri: her kullanımda döndürülür (kimlik sunucusu başa çıkmalı). API anahtarları: en az 90 günde bir, veya şüphelenirsen hemen. Gerçekte çoğu takım ancak sızıntıdan sonra döndürür, bu çok geçtir.

Docker konteynerlerinde kimlik doğrulama nasıl yönetilir?#

Üç tercih, önem sırasına göre:

1. İnteraktif kullanım için cihaz kodu akışı (tarayıcı farklı makinede olabilir)
2. Ortam değişkeni ile runtime’da aktarım (docker run -e API_KEY=${API_KEY}) — CI/CD için
3. Volume-mount kimlik bilgisi dosyası (docker run -v ~/.config/tool:/root/.config/tool:ro) — lokal geliştirme için

Kimlik bilgisini imaja gömme. Asla.

MCP (Model Context Protocol) kimlik doğrulaması nedir?#

MCP, AI ajanlarının harici araç ve servislerle bağlantı kurması için ortaya çıkan standarttır. Yeni bir boyut katar: ajan MCP sunucusuna bağlanmak için kimliğe ihtiyaç duyar; MCP de aşağıdaki API’lere erişmek için kimlik ister. Bu kısım hâlâ standartlaşmakta. Şimdilik çoğu MCP uygulaması yapılandırmada API anahtarı veya OAuth token geçer. Bunun çok hızlı evrilmesi bekleniyor.

---

CLI kimlik doğrulaması çok hızlı değişiyor. İki yıl önceki en iyi uygulamalar (cihaz kodu akışı varsayılan, düz metin kimlik dosyası) artık değişiyor. Bugün bir CLI’ya kimlik doğrulama ekliyorsan, insan için tarayıcı OAuth + PKCE, otomasyon için API anahtarıyla başla; AI ajanların ana kullanıcı olacağı geleceğe hazırlan.