Poprawne uwierzytelnianie w CLI: kompletny przewodnik po wszystkich 4 metodach

Każde deweloperskie CLI ma login jako pierwszą komendę. I każde rozwiązuje uwierzytelnianie inaczej.

GitHub pokazuje kod i otwiera przeglądarkę do potwierdzenia. AWS uruchamia przeglądarkę dla jednokrotnego logowania SSO opartego na PKCE. Stripe każe potwierdzić kod parujący na dashboardzie. Nowsze narzędzia AI (Claude Code, OpenAI Codex CLI, Cursor) wybrały jeszcze inne podejścia.

Jeśli tworzysz CLI, uwierzytelnianie to jedna z pierwszych rzeczy, które musisz rozgryźć. Wybierz złą metodę, a usłyszysz o tym: sfrustrowani użytkownicy, audyty bezpieczeństwa albo oba. Wraz z falą agentów kodujących AI, które wywołują narzędzia CLI programistycznie, stawka rośnie: nie uwierzytelniasz już tylko człowieka. Możesz oddać poświadczenia autonomicznemu procesowi.

Oto cztery metody uwierzytelniania, które się liczą, sposoby ich wdrażania w najpopularniejszych narzędziach oraz błędy, których warto unikać.

Cztery metody w skrócie#

Zanim przejdziemy do szczegółów, krótkie porównanie:

Każda metoda ma swoje wady i zalety. Oto najważniejsze informacje o każdej z nich.

1. OAuth device code flow (RFC 8628)#

To ta metoda, w której CLI wyświetla kod jak ABCD-1234 i adres URL, po czym każe ci otworzyć ten URL na dowolnym urządzeniu i wprowadzić kod.

Kto używa: GitHub CLI (domyślnie), Azure CLI (przez --use-device-code), Vercel CLI (niedawno zmieniło na domyślne), OpenAI Codex CLI (opcjonalnie, beta)

Jak to działa#

1. Uruchamiasz cli login
2. CLI żąda kodu urządzenia od serwera autoryzacyjnego, przesyłając swój client_id i wymagane scope'y
3. Serwer zwraca trzy rzeczy: device_code (wewnętrzny identyfikator), user_code (krótki kod do wpisania) oraz verification_uri (gdzie się udać)
4. CLI pokazuje kod i link, a następnie zaczyna odpytywać serwer co 5+ sekund
5. Otwierasz link na dowolnym urządzeniu (telefonie, laptopie, innej maszynie), wpisujesz kod i uwierzytelniasz się dowolną metodą (hasło, SSO, klucze sprzętowe, MFA)
6. Po zatwierdzeniu kolejny odczyt zwraca token dostępu i odświeżania
7. CLI zapisuje je i jesteś zalogowany

Dlaczego deweloperzy to lubią#

Największa zaleta: działa wszędzie. Sesja SSH na zdalnym serwerze? Działa. W kontenerze Docker? Działa. Cloud IDE bez przeglądarki lokalnej? Działa. Przeglądarka nie musi być na tej samej maszynie co CLI.

Obsługuje pełne uwierzytelnianie korporacyjne (SAML, OIDC, MFA), bo całość odbywa się w przeglądarce, nie w terminalu. CLI nigdy nie widzi twojego hasła.

Najczęstszy problem z bezpieczeństwem#

Device code flow jest podatny na phishing. Atakujący może zainicjować żądanie kodu urządzenia, uzyskać prawidłowy kod użytkownika i oszukać cię, byś go wpisał, autoryzując w ten sposób sesję atakującego. To nie teoria. Badacze bezpieczeństwa udokumentowali taki atak przeciwko AWS SSO device code auth.

To tak poważny problem, że AWS zmieniło domyślne ustawienia. Od AWS CLI v2.22.0 domyślnie dla aws sso login stosowany jest już nie device code flow, tylko Authorization Code Flow z PKCE. Device code nadal jest dostępny przez --use-device-code, ale nie jest już domyślną ścieżką.

Jednocześnie sam Microsoft zaczął blokować device code flow przez polityki accessu warunkowego – to wyraźny sygnał wysokiego ryzyka tej metody.

Mamy ciekawy rozkład: Vercel wdrożyło device code flow jako domyślne we wrześniu 2025, AWS się wycofało. Wzorzec wydaje się jasny: device code flow jest świetny w środowiskach, gdzie naprawdę nie da się otworzyć przeglądarki, ale jeśli możesz ją otworzyć lokalnie, PKCE jest bezpieczniejsze.

Jeśli chodzi o dostawców autoryzacji – zapotrzebowanie rośnie. Logto właśnie wdrożyło wsparcie OAuth 2.0 Device Authorization Grant dla aplikacji natywnych w v1.38.0 (open source) oraz Logto Cloud, więc możesz już aktywować device flow jako opcję autoryzacji dla każdej aplikacji natywnej. To istotne, jeśli budujesz CLI. Poprawna implementacja RFC 8628 (wygasanie kodów, limitowanie żądań, logika odpytywania, UX logowania na stronie weryfikacji) to więcej pracy niż większość zespołów przewiduje, a jeśli obsługuje to dostawca autoryzacji, musisz tylko zrobić odpowiednie zapytania HTTP.

Szczegóły techniczne z RFC#

Kilka ważnych rzeczy z RFC 8628:

• Wartość expires_in dla kodów urządzenia ustawia serwer autoryzacji. RFC podaje 1800 sekund (30 minut) jako przykład, ale to nie jest wymóg.
• Jeśli serwer nie podaje interwału odpytywania, klient powinien domyślnie przyjąć 5 sekund.
• Przy błędzie slow_down dodaj 5 sekund do interwału.
• Kody urządzenia powinny być jednokrotnego użytku i szybko wygasać.
• Wymiana tokenów wyłącznie przez HTTPS.

2. OAuth przez przeglądarkę (localhost redirect)#

To najpopularniejsza metoda CLI uruchamianego na lokalnej maszynie dewelopera. Uruchamiasz login, otwiera się przeglądarka, uwierzytelniasz się, przeglądarka wraca na lokalny serwer, który CLI właśnie podniosło. Nowoczesne implementacje dodają PKCE (wym. "piksi"), co znacznie utrudnia ataki.

Kto używa: Claude Code, gcloud CLI, Terraform CLI, AWS CLI v2.22+ (dla SSO, PKCE domyślnie)

Jak to działa#

1. Uruchamiasz cli login
2. CLI uruchamia tymczasowy serwer HTTP na losowym lokalnym porcie (np. http://127.0.0.1:8742)
3. Otwiera domyślną przeglądarkę na endpoint autoryzacji dostawcy auth, przekazując adres localhost jako redirect URI
4. Uwierzytelniasz się w przeglądarce (SSO, hasło, klucze sprzętowe…)
5. Provider przekierowuje przeglądarkę na http://127.0.0.1:8742/callback?code=XXXX&state=YYYY
6. Serwer lokalny przechwytuje kod autoryzacji i wymienia go na tokeny po kanale HTTPS
7. Przeglądarka pokazuje stronę "Sukces! Możesz zamknąć kartę"
8. CLI zapisuje tokeny i wyłącza lokalny serwer

Doświadczenie dla użytkownika jest płynne. Żadnych kodów do przepisywania, żadnych linków do ręcznego otwierania. Po prostu otwiera się strona w przeglądarce.

Kiedy to nie działa#

Metoda działa tylko, gdy CLI może otworzyć przeglądarkę i nasłuchiwać na localhost. Odpada więc:

• Sesje SSH na zdalnych serwerach
• Kontenery Docker (chyba że żonglujesz portami)
• Pipeline'y CI/CD
• Serwery bez interfejsu
• Ograniczone środowiska korporacyjne

Dlatego większość narzędzi z domyślnym OAuth przez przeglądarkę wspiera fallback, zwykle device code flow albo klucze API.

Trzy typowe błędy z bezpieczeństwem#

Błąd 1: Nasłuchiwanie na 0.0.0.0 zamiast 127.0.0.1

Najczęstszy i bardzo poważny. Jeśli twój serwer callback nasłuchuje na wszystkich interfejsach, każdy w tej samej sieci może przechwycić kod autoryzacji.

Widziałem to w produkcyjnych CLI. Łatwo popełnić ten błąd, bo wiele bibliotek HTTP domyślnie nasłuchuje na 0.0.0.0.

Błąd 2: Brak walidacji parametru state

Parametr state to twoja ochrona przed CSRF. Bez niego atakujący może podsunąć CLI kod autoryzacyjny ze złośliwej sesji.

Błąd 3: Brak PKCE

Jeśli nie korzystasz z PKCE (Proof Key for Code Exchange), kod autoryzacyjny może zostać przechwycony i użyty ponownie.

W standardowym Authorization Code Flow, jeśli atakujący przechwyci kod autoryzacyjny (w sieci, odczytując URL), może wymienić go na tokeny. PKCE zapobiega temu – trzeba udowodnić, że wymiana tokenu jest inicjowana przez tego samego klienta, co zapytanie o autoryzację.

Co PKCE wnosi do flow:

1. Przed rozpoczęciem, CLI generuje losowy code_verifier (ciąg wysokiej entropii)
2. Tworzy code_challenge przez hash SHA-256 verifiera
3. Challenge wysyła z żądaniem autoryzacji
4. Przy wymianie kodu na tokeny, CLI przesyła oryginalny code_verifier
5. Serwer autoryzacji sprawdza czy verifier pasuje do challenge

Atakujący, który przechwyci kod autoryzacji, nie posiada code_verifier, więc nie zakończy wymiany.

Dlatego AWS CLI v2.22+ domyślnie wymaga PKCE dla SSO, rezygnując z device code flow. Gdy CLI otwiera przeglądarkę na tej samej maszynie, OAuth przez przeglądarkę z PKCE zawsze wygrywa z device code flow — identyczne UX, silniejsze bezpieczeństwo, brak wektora phishingu. Device code flow jest dobrym wyborem tylko wtedy, gdy przeglądarka nie może być na tej samej maszynie (SSH, kontenery, środowiska zdalne), co nie jest normą dla lokalnego developmentu.

3. Klucze API i personal access tokens#

Najprostsze rozwiązanie. Generujesz token na dashbordzie webowym, wklejasz do configu CLI lub do zmiennej środowiskowej i gotowe.

Kto używa: Stripe CLI (jako opcja logowania), npm, pip, większość narzędzi AI jako fallback (Claude Code przez ANTHROPIC_API_KEY, narzędzia OpenAI przez OPENAI_API_KEY, Aider)

Jak to działa#

1. Zaloguj się do panelu webowego usługi
2. Idź do settings → API keys (lub personal access tokens, developer tokens)
3. Wygeneruj nowy klucz, zwykle długi losowy ciąg z prefiksem (np. sk_live_, ghp_, npm_)
4. Zapisz go w pliku konfiguracyjnym (~/.config/stripe/config.toml, ~/.aws/credentials) lub w zmiennej środowiskowej

CLI odczytuje go przy starcie i dołącza do zapytań API jako token Bearer w nagłówku Authorization.

Dlaczego nadal są popularne mimo ryzyka#

Do automatyzacji klucze API są niezastąpione. Działają w CI/CD, w kontenerach, w skryptach, w cronie. Wszędzie tam, gdzie można odczytać zmienną środowiskową. Bez przeglądarki, bez interakcji, bez odświeżania tokenu.

Dla agentowych workflow AI klucze API są najprostszą drogą. Gdy Claude Code czy Cursor musi wywołać API, zmienna środowiskowa z kluczem API to najłatwiejsza integracja.

Ryzyka są realne#

• Wycieki. Klucze API trafiają do commitów, logów, komunikatów o błędach i outputu CI. GitHub skanuje pod kątem wycieków secretów i raportuje ponad milion rocznie.
• Zbyt szerokie uprawnienia. Większość kluczy API daje szeroki dostęp. Po wycieku zakres szkód jest ogromny.
• Brak MFA. Klucze API omijają twoje starannie ustawione MFA.
• Trudne rotowanie. Każda rotacja klucza wymaga aktualizacji we wszystkich miejscach jego użycia. Z zespołem to już wyzwanie koordynacyjne.

Nowoczesne ulepszenie: wymiana na czasowe tokeny#

Dobry ruch przy korzystaniu z kluczy API: wymieniaj je na tokeny krótkoterminowe w runtime.

AWS zapoczątkowało to z STS (Security Token Service). Twoje długowieczne poświadczenia służą tylko do żądania tymczasowych, wygasających po godzinie. Narzędzia typu aws-vault całkowicie to automatyzują.

Nawet zaczynając od kluczy API, warto dodać ten wzorzec. Ograniczasz wtedy okno szkód z "do wykrycia" do "1 godziny".

4. Client credentials flow#

Ta metoda OAuth 2.0 jest zaprojektowana dla komunikacji maszyna-maszyna: serwisy rozmawiające ze sobą, bez udziału człowieka.

Wykorzystanie: Pipeline'y CI/CD, procesy w tle, narzędzia automatyczne

Jak to działa#

Serwis przesyła swój client_id i client_secret bezpośrednio do serwera autoryzacji i otrzymuje krótkoterminowy access token. Bez przeglądarki, bez interakcji, bez przekierowań.

Kiedy używać#

Używaj client credentials gdy:

• Autoryzować musi serwis lub bot, nie człowiek
• Pracujesz w CI/CD
• Potrzebny jest automatyczny, bezobsługowy dostęp
• "Użytkownikiem" jest sama aplikacja

Nie używaj tego dla ludzi. Ta metoda nie wspiera MFA, SSO ani weryfikacji interaktywnej.

Czego naprawdę używają CLI#

Oto poprawiony przegląd na bazie aktualnej dokumentacji i źródła. Wiele artykułów się myli, bo domyślne opcje często się zmieniają.

Trend jest jasny: OAuth przez przeglądarkę dominuje dla lokalnego developmentu, device code flow jako zapas dla headless, a klucze API dla automatyzacji. PKCE szybko zyskuje jako najbezpieczniejsza opcja mając przeglądarkę.

Przechowywanie tokenów: co używać, czego unikać#

Dobre uwierzytelnienie nic nie daje, jeśli źle przechowujesz tokeny.

Poprawna droga: keychain systemowy#

Każdy większy system operacyjny ma zaszyfrowany wbudowany system przechowywania credentiali:

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

Zapewniają one szyfrowanie sprzętowe, kontrolę dostępu i integrację z zabezpieczeniami. Nie musisz implementować własnej kryptografii.

Zapas: szyfrowane pliki konfiguracyjne#

Gdy keychain jest niedostępny (kontenery, minimalny Linux), używaj szyfrowanych plików z restrykcyjnymi uprawnieniami:

Czego unikać#

Pliki tekstowe. To oczywiste, ale sporo narzędzi nadal tak robi. Taki plik jest dostępny dla każdego procesu użytkownika, dla każdego narzędzia backupu i wszystkich, którzy czasowo uzyskali dostęp do maszyny.

Zmienne środowiskowe do długotrwałego przechowywania. Zmienne env są widoczne w process listings, często logowane przez narzędzia crash reporting, dziedziczone przez podprocesy. Są OK w CI/CD (gdzie platforma zarządza sekretem), ale ryzykowne lokalnie.

localStorage przeglądarki. Jeśli twój CLI ma komponent webowy, nie przechowuj tam tokenów. Jedna luka XSS i wszystko wypłynie.

Zarządzanie cyklem życia tokenu#

Access tokeny#

Trzymaj je krótkoterminowo. Godzina to standard. Gdy token wygasa, CLI powinno odświeżyć go przez refresh, bez wymagania ponownego logowania do zwykłych operacji.

Refresh tokeny#

Tokeny odświeżania to długowieczne poświadczenia pozwalające uzyskać nowe access tokeny bez ponownej autoryzacji. Są cennym celem atakujących – ich cykl życia to dni lub miesiące.

Rotacja tokenu odświeżania#

Nowoczesne systemy auth rotują refresh tokeny przy każdym użyciu:

1. CLI przesyła refresh token by uzyskać dostęp
2. Auth serwer daje nowy access token i nowy refresh token
3. Stary refresh token jest natychmiast nieważny
4. CLI zapisuje oba nowe tokeny

To ogranicza szkody po kradzieży refresh tokenu. Jeśli atakujący spróbuje użyć tokenu odświeżania, który CLI już wykorzystało, serwer auth wykryje powtórne użycie i unieważni całą rodzinę tokenów. Zarówno token atakującego jak i twój przestają działać, co wymusza relogowanie i uniemożliwia utrzymanie dostępu przez atakującego.

Najczęstsze błędy (z kodem)#

1. Nasłuchiwanie callback servera na wszystkich interfejsach#

Już omówione – zawsze nasłuchuj na 127.0.0.1, nigdy 0.0.0.0.

2. Logowanie tokenów#

Dzieje się częściej niż ludzie przyznają. Log debug, error handler dumpujący headers, verbose tryb wypisujący wszystko.

3. Wrzucanie poświadczeń do obrazów kontenerów#

Obrazy Dockera nie są skarbcami na sekrety. Każda warstwa jest do odczytu.

4. Brak obsługi wygasania tokenów#

Gdy token wygasa w trakcie operacji, nie rzucaj 401 od razu. Spróbuj odświeżyć, a proś o relogowanie tylko gdy refresh token też nie działa.

5. Ignorowanie zasady minimalnych uprawnień#

Nie żądaj zakresu admin:* jeśli wystarczy repo:read. Dotyczy to zarówno scope'ów OAuth jak i uprawnień API key.

Gdy agent AI korzysta z twojego CLI, to szczególnie istotne. Nie chcesz, by asystent AI dostał uprawnienia kasowania repo tylko po to, by czytać kod.

Czynnik agentów AI#

Co odróżnia 2026 od 2023: CLI nie służą już tylko ludziom wpisującym komendy. Agenci kodujący AI typu Claude Code, Codex czy Cursor agent mode uruchamiają CLI programistycznie. To generuje nowe wyzwania dla auth:

Delegowane uprawnienia. Gdy Claude Code wykonuje gh pr create w twoim imieniu, używa twoich poświadczeń GitHub. Ale czy AI agent powinien mieć takie uprawnienia jak ty? Zasada minimalnych uprawnień mówi nie, ale większość narzędzi nie daje na razie mechanizmów ograniczania uprawnień agenta.

Ekspozycja poświadczeń. Jeśli trzymasz API key w zmiennej env, każdy proces może go odczytać – także podproces agenta AI. Narzędzia typu Claude Code rozwiązały to przez skrypty apiKeyHelper generujące krótkoterminowe tokeny na żądanie, ale to nie jest jeszcze standard.

Headless auth dla agentów. AI agent uruchomiony w sandboxie nie otworzy przeglądarki. Device code flow sprawdza się tu (człowiek autoryzuje na innym urządzeniu), ale klucze API są częstszym wyborem ze względu na brak interakcji.

Logi audytu. Operacje API wykonane przez agenta z twoimi poświadczeniami zapisują się w logu audytu jako twoje. Nie ma obecnie standardu rozróżniającego "człowiek to zrobił" od "agent zrobił to w imieniu człowieka".

To nadal się rozwija. Najlepsze co możesz robić:

• Używaj tokenów ze scope'em minimum dla workflow agentów
• Preferuj krótkoterminowe poświadczenia (tokeny tymczasowe, a nie długowieczne API key)
• Stosuj oddzielne poświadczenia dla agentów, niezależne od twoich osobistych
• Monitoruj użycie API pod kątem anomalii

Ramy wyboru metody#

Wybierasz metodę auth? Skrót:

"Moi użytkownicy to deweloperzy na ich lokalnych maszynach" → OAuth przez przeglądarkę z PKCE (najlepsze bezpieczeństwo + wygoda)

"CLI ma działać w SSH i w kontenerach" → Device code flow jako fallback, OAuth przez przeglądarkę jako priorytet

"To działa w CI/CD bez udziału człowieka" → Client credentials flow lub scope'owane klucze API

"Muszę wdrożyć najszybciej jak się da" → Klucze API (później rotacja tokenów)

"Klienci korporacyjni potrzebują SSO i MFA" → Dowolny flow OAuth (device code lub browser), wspiera pełen stack enterprise auth

"Agenci AI będą używać tego CLI" → Wsparcie kluczy API (dla prostoty agentów) + OAuth przez przeglądarkę (dla ludzi), scope'owane uprawnienia i krótkoterminowe tokeny

FAQ#

Czy device code flow jest bezpieczny?#

Jest bezpieczny przed większością ataków, ale ma znaną podatność na phishing. Atakujący może wygenerować device code i podsunąć go użytkownikom do autoryzacji. Dlatego AWS zmienił domyślną metodę na PKCE dla loginu SSO. W środowiskach headless, gdzie PKCE nie wchodzi w grę, device code to nadal najlepsza opcja — trzeba tylko liczyć się z ryzykiem phishingu.

Czy przechowywać tokeny w zmiennych środowiskowych?#

Dla CI/CD: tak, bo platforma CI szyfruje je w spoczynku i wstrzykuje w runtime. Lokalnie: nie. Trzymaj tokeny w keychain OS. Zmienne env są widoczne w process listings oraz mogą trafić do logów czy podprocesów przez przypadek.

Jaka jest różnica między API key i personal access token?#

W praktyce niewielka. Obydwa to długoterminowe poświadczenia do autoryzacji zapytań API. Różnica jest zwykle organizacyjna: API key często przypisany jest do projektu lub aplikacji, PAT – do konta użytkownika. Niektóre usługi używają tych nazw zamiennie.

Jak często rotować poświadczenia?#

Access tokeny: co godzinę lub częściej (zwykle przez flow odświeżania, automatycznie). Refresh tokeny: rotacja przy każdym użyciu (powinna być obsługiwana przez serwer autoryzacji). Klucze API: minimum co 90 dni lub natychmiast po podejrzeniu wycieku. W praktyce większość zespołów rotuje klucze API dopiero po incydencie, co jest już za późno.

Jak obsługiwać auth w kontenerach Docker?#

Trzy opcje, od najlepszej:

1. Device code flow do użytku interaktywnego (przeglądarka może być na innej maszynie)
2. Zmienne środowiskowe podawane w runtime (docker run -e API_KEY=${API_KEY}) w CI/CD
3. Kredensale przez volume (docker run -v ~/.config/tool:/root/.config/tool:ro) dla developmentu lokalnego

Nigdy nie wrzucaj poświadczeń do obrazu. Nigdy.

A co z auth MCP (Model Context Protocol)?#

MCP to powstający standard łączenia agentów AI z zewnętrznymi narzędziami i usługami. Wprowadza nowy wymiar auth: agent potrzebuje uwierzytelnienia do MCP servera, a ten do dalszych API. Standard dopiero się klaruje. Na razie większość implementacji MCP korzysta z kluczy API albo tokenów OAuth przekazywanych przez konfigurację MCP. Spodziewaj się szybkiej ewolucji w tej dziedzinie.

---

Auth CLI zmienia się szybko. To, co było dobrym standardem dwa lata temu (device code flow domyślnie, pliki tekstowe credentiali), już ustępuje nowym wzorcom. Jeśli dziś implementujesz auth w CLI, startuj z OAuth przez przeglądarkę + PKCE dla ludzi, kluczami API dla automatyzacji — i myśl o dniu, gdy to AI agenci będą twoimi głównymi użytkownikami.