Passkeys i WebAuthn w 2026: Praktyczny przewodnik wdrożeniowy dla programistów webowych
Passkeys obiecują logowanie bezhasłowe bez przechowywania sekretów hasła, ale prawidłowe wdrożenie WebAuthn wymaga więcej niż wywoływanie interfejsu API przeglądarki. Dowiedz się, jak rejestracja, uwierzytelnianie, weryfikacja po stronie serwera, wykrywalne poświadczenia i odzyskiwanie konta współgrają w bezpiecznej aplikacji internetowej.
Klucze dostępowe i WebAuthn w 2026 roku: Praktyczny przewodnik dla deweloperów webowych
Hasła były domyślnym mechanizmem uwierzytelniania dla aplikacji webowych przez dekady. Są także stałym źródłem problemów bezpieczeństwa.
Użytkownicy je ponownie wykorzystują. Atakujący kradną je poprzez phishing. Serwery muszą chronić hasła, zarządzać resetami i bronić się przed atakami typu credential-stuffing.
Klucze dostępowe oferują Fundamentalnie inny sposób podejścia.
Zamiast prosić użytkowników o zapamiętanie wspólnego tajemnika, klucze dostępowe korzystają z kryptografii klucza publicznego i uwierzytelniacza kontrolowanego przez użytkownika. Przeglądarka udostępnia standardowy interfejs poprzez WebAuthn, podczas gdy serwer weryfikuje kryptograficzne dowody, że użyto poprawnego poświadczenia.
Technologia nie jest już eksperymentalna. WebAuthn jest szeroko dostępny w nowoczesnych przeglądarkach, a metody JSON ułatwiające integrację znacznie uproszczyły proces.
Jednak budowanie bezpiecznego logowania z kluczami dostępowymi wymaga starania o odpowiednie projektowanie backendu.
Ten przewodnik wyjaśnia architekturę, demonstruje przepływy po stronie przeglądarki i identyfikuje serwerowe sprawdzenia, które deweloperzy nie mogą pominąć.
1. Co dokładnie jest kluczem dostępowym?
Klucz dostępowy to postrzegalne poświadczenie FIDO używane do uwierzytelniania użytkownika przy użyciu kryptografii klucza publicznego.
Podczas rejestracji uwierzytelniacz tworzy parę kluczy kryptograficznych.
Klucz prywatny pozostaje chroniony przez uwierzytelniacza lub jego ekosystem zarządzania poświadczeniami. Strona internetowa otrzymuje odpowiadający mu klucz publiczny i łączy go z kontem użytkownika.
Podczas uwierzytelniania serwer wystawia świeże wyzwanie. Uwierzytelniacz podpisuje dane powiązane z tym wyzwaniem, a serwer weryfikuje podpis przy użyciu przechowywanego klucza publicznego.
Nie ma ponownie wykorzystywanego hasła wysłanego do strony internetowej.
Uwierzytelniacz może być smartfonem, komputerem z Windows Hello, kluczem bezpieczeństwa lub menedżerem poświadczeń obsługującym zsynchronizowane klucze dostępowe.
Nie każdy klucz dostępowy jest zsynchronizowany pomiędzy urządzeniami. Niektóre poświadczenia pozostają powiązane z urządzeniem, podczas gdy inne mogą być bezpiecznie zbackupowane i udostępnione przez dostawcę poświadczeń.
Specyfikacje FIDO zostały zaprojektowane tak, aby opierały się na odporności na phishing, łącząc poświadczenia z domeną identyfikatora party zaufanej. Dane biometyczne, jeśli zostaną użyte, są przetwarzane lokalnie na urządzeniu, a nie przesyłane do strony internetowej.
2. WebAuthn to przeglądarkowe API za tłem kluczy dostępowych
WebAuthn to przeglądarkowe API platformy webowej umożliwiające stronom internetowym tworzenie i korzystanie z poświadczeń klucza publicznego.
Dwie metody przeglądarki tworzą podstawę:
navigator.credentials.create()
navigator.credentials.get()
Pierwsza tworzy poświadczenie. Druga żąda uwierzytelniania przy użyciu istniejącego poświadczenia.
Obie metody działają z opcją publicKey i wymagają bezpiecznego kontekstu, zwykle HTTPS.
Ważne jest, że przeglądarka nie decyduje, czy użytkownik jest uwierzytelniony. Zwraca dane, które backend musi zweryfikować.
Pomyślny komunikat przeglądarki nie jest dowodem, że logowanie powinno zostać zaakceptowane.
Serwer pozostaje odpowiedzialny za weryfikację wyzwacza, pochodzenia, identyfikatora party zaufanej i kryptograficznych dowodów.
3. Zrozum pełną architekturę
Typowa implementacja zawiera cztery komponenty:
- Frontend aplikacji webowej, który wywołuje WebAuthn.
- Backend aplikacji, który generuje wyzwania i weryfikuje odpowiedzi.
- Uwierzytelniacz lub dostawca kluczy dostępowych, który chroni klucz prywatny.
- Baza danych, która przechowuje metadane poświadczenia i klucze publiczne.
Przepływ rejestracji to: aplikacja webowa żąda opcji rejestracji; backend generuje wyzwanie i dane użytkownika; przeglądarka i uwierzytelniacz tworzą poświadczenie i parę kluczy; a backend weryfikuje wynik i przechowuje klucz publiczny.
Serwer nigdy nie może ufać danym rejestracji jedynie dlatego, że zostały zwrócone przez przeglądarkę.
Złośliwy klient może przesłać dowolne żądania HTTP bez użycia oczekiwanej przeglądarki.
Dlatego weryfikacja należy do serwera.
4. Generuj opcje rejestracji po stronie serwera
Przed wywołaniem WebAuthn backend generuje wyzwanie rejestracyjne i opcje.
Przykładowy obiekt opcji wygląda tak:
{
"rp": {
"name": "Example Application",
"id": "example.com"
},
"user": {
"id": "dXNlci0xMjM",
"name": "alex@example.com",
"displayName": "Alex"
},
"challenge": "SERVER_GENERATED_BASE64URL_CHALLENGE",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"authenticatorSelection": {
"residentKey": "required",
"userVerification": "required"
},
"attestation": "none",
"timeout": 300000
}
To ilustracyjne JSON, nie kompletna odpowiedź produkcyjna.
Kilka pól ma znaczenie.
rp.id identyfikuje party zaufanego. Na przykład example.com może być użyte dla odpowiednich poddomen tej domeny, podlegających regułom walidacji RP ID w WebAuthn.
user.id powinien być stabilnym, niewidocznym identyfikatorem konta zakodowanym jako base64url dla transportu JSON. Nie powinien ujawniać niepotrzebnych informacji osobowych.
challenge musi zostać wygenerowany przy użyciu kryptograficznie bezpiecznego źródła losowego na serwerze.
residentKey: "required" żąda poświadczenia wyszukiwalnego, które jest niezbędne dla świadczenia klucza dostępowego.
userVerification: "required" żąda lokalnej weryfikacji użytkownika, takiej jak PIN urządzenia lub uwierzytelnianie biometryczne. Backend później musi sprawdzić, czy weryfikacja rzeczywiście się odbyła.
Przewodnik Google po stronie serwera opisuje te pola i zaleca użycie utrzymywanego WebAuthn biblioteki do generowania i weryfikacji danych rejestracyjnych.
5. Utwórz klucz dostępowy w JavaScript
Nowoczesne przeglądarki udostępniają użyteczną metodę:
PublicKeyCredential.parseCreationOptionsFromJSON()
Przekształca ona reprezentację JSON zawierającą pola zakodowane jako base64url do struktury oczekiwanej przez WebAuthn.
To eliminuje konieczność pisania własnej logiki konwersji base64url do ArrayBuffer dla każdego pola.
Oto uproszczona przykładowa funkcja rejestracji po stronie przeglądarki:
async function registerPasskey() {
const optionsResponse = await fetch(
'/api/passkeys/register/options',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrfToken
}
}
);
if (!optionsResponse.ok) {
throw new Error('Unable to start registration');
}
const optionsJson = await optionsResponse.json();
const publicKey =
PublicKeyCredential.parseCreationOptionsFromJSON(
optionsJson
);
const credential = await navigator.credentials.create({
publicKey
});
if (!credential) {
throw new Error('No credential was created');
}
const verifyResponse = await fetch(
'/api/passkeys/register/verify',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrfToken
},
body: JSON.stringify(credential.toJSON())
}
);
if (!verifyResponse.ok) {
throw new Error('Registration verification failed');
}
return await verifyResponse.json();
}
Zmienna csrfToken reprezentuje token anty-CSRF zapewniony przez aplikację. Serwer musi go zweryfikować. Przykład zakłada również, że strona jest już powiązana z bezpiecznie uwierzytelnionym użytkownikiem.
credential.toJSON() zapewnia reprezentację JSON zwróconego poświadczenia, unikając kolejnej warstwy ręcznej serializacji binarnej.
Te udogodnienia są dostępne w aktualnych przeglądarkach, choć aplikacje obsługujące starsze wersje przeglądarek powinny zapewnić obsługę kompatybilności.
Powyższy kod to jedynie strona przeglądarki. Nie jest to kompletna implementacja uwierzytelniania.
6. Co serwer musi zweryfikować podczas rejestracji
Gdy przeglądarka zwraca nowe poświadczenie, backend musi zweryfikować je przed przechowaniemiem czegokolwiek.
Co najmniej proces weryfikacji musi ustalić, że:
- Zwrócone wyzwanie pasuje do tego wygenerowanego dla tego próba rejestracji.
- Wyzwanie jest świeże i nie zostało już zużyte.
- Zgłaszane pochodzenie odpowiada wyraźnie zaufanemu pochodzeniu aplikacji.
- Dane uwierzytelniacza odpowiadają oczekiwanemu identyfikatorowi party zaufanej.
- Warunki obecności użytkownika i weryfikacji użytkownika są spełnione.
- Klucz publiczny i identyfikator poświadczenia można wyodrębnić i zweryfikować.
- Rejestracja jest powiązana z poprawnym uwierzytelnionym kontem.
W zależności od polityki aplikacji, dodatkowe sprawdzenia mogą obejmować obsługiwane algorytmy, unikalność poświadczenia i wymogi przywołania.
Pomyślna rejestracja zazwyczaj przechowuje:
| Pole | Cel |
|---|---|
credential_id |
Identyfikuje poświadczenie |
user_id |
Łączy je z kontem |
public_key |
Weryfikuje przyszłe podpisy |
sign_count |
Śledzi dane licznika uwierzytelniacza |
transports |
Opcjonalne wskazówki transportu uwierzytelniacza |
created_at |
Znacznik czasu rejestracji |
last_used_at |
Zarządzanie kontem i audyt |
backup_eligible / backup_state |
Opcjonalne metadane powiązane z backupem |
Dokładna reprezentacja bazy danych zależy od biblioteki weryfikacyjnej i aplikacji.
Nie implementuj parsowania CBOR, weryfikacji przywołania ani weryfikacji podpisu od razu, chyba że masz wyjątkowy powód i wystarczającą wiedzę, aby utrzymać to samodzielnie.
Specyfikacja W3C definiuje szczegółowe procedury rejestracji i weryfikacji uwierzytelniania.
7. Uwierzytelnij istniejącego użytkownika
Uwierzytelnianie podąża za podobną strukturą, ale nie tworzy nowej pary kluczy.
Serwer generuje nowe wyzwanie i wysyła opcje uwierzytelniania do przeglądarki.
Dla logowania zsynchronizowanym klucza dostępowego, te opcje mogą zawierać:
{
"challenge": "NEW_SERVER_GENERATED_CHALLENGE",
"rpId": "example.com",
"userVerification": "required",
"timeout": 300000
}
Przeglądarka może wtedy poprosić o poświadczenie:
async function authenticateWithPasskey() {
const optionsResponse = await fetch(
'/api/passkeys/login/options',
{
credentials: 'same-origin'
}
);
if (!optionsResponse.ok) {
throw new Error('Unable to start authentication');
}
const optionsJson = await optionsResponse.json();
const publicKey =
PublicKeyCredential.parseRequestOptionsFromJSON(
optionsJson
);
const credential = await navigator.credentials.get({
publicKey
});
if (!credential) {
throw new Error('Authentication was cancelled');
}
const verifyResponse = await fetch(
'/api/passkeys/login/verify',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(credential.toJSON())
}
);
if (!verifyResponse.ok) {
throw new Error('Authentication failed');
}
return await verifyResponse.json();
}
Ten przykład zakłada, że backend łączy wydane wyzwanie z krótkotrwałą, anonimową transakcją logowania, stosuje odpowiednie ograniczenia tempoowe i ustanawia nową sesję uwierzytelnioną tylko po pomyślnej weryfikacji.
Serwer musi znaleźć identyfikator poświadczenia, zweryfikować podpisane stwierdzenie przy użyciu przechowywanego klucza publicznego, potwierdzić wyzwanie i pochodzenie oraz egzekwować swoją politykę weryfikacji użytkownika.
Tylko wtedy powinien ustanowić sesję użytkownika.
parseRequestOptionsFromJSON() jest częścią nowoczesnego API WebAuthn i eliminuje potrzebę ręcznego dekodowania pól binarnych w powszechnych integracjach po stronie przeglądarki.
8. Dodaj klucze dostępowe do istniejących formularzy logowania z mediacją warunkową
Jedna z najprzydatniejszych funkcji WebAuthn to mediacja warunkowa, czasami nazywana autouzupełnianiem klucza dostępowego.
Zamiast pokazywać osobne okno dialogowe natychmiast, przeglądarka może zaproponować dostępny klucz dostępowy obok innych zapisanych poświadczeń, gdy użytkownik interaguje z polem logowania.
HTML input może używać:
<input
type="text"
name="username"
autocomplete="username webauthn"
>
Aplikacja może sprawdzić obsługę:
const supported =
await PublicKeyCredential.isConditionalMediationAvailable();
if (supported) {
// Request authentication with mediation: 'conditional'.
}
Podczas wywoływania navigator.credentials.get(), aplikacja używa:
{
publicKey,
mediation: 'conditional'
}
Dla autouzupełniania poświadczenia wyszukiwalnego, opcje serwera nie powinny ograniczać żądania do konkretnej listy identyfikatorów poświadczenia.
Mediacja warunkowa jest szczególnie przydatna podczas stopniowej migracji z haseł, ponieważ użytkownicy nie muszą pamiętać, czy dane konto ma klucz dostępowy.
Przeglądarka może przedstawić odpowiednie opcje w znajomej formie logowania.
9. Dlaczego sprawdzenia wyzwacza i pochodzenia są kluczowe
Klucze dostępowe są odporne na phishing, ale to nie oznacza, że aplikacja może zignorować swój protokół uwierzytelniania.
Wyzwanie chroni przed atakami replay.
Bez świeżego, nieprzewidywalnego wyzwacza, atakujący mógłby spróbować ponownie użyć danych uwierzytelniania z poprzedniej sesji.
Sprawdzenia pochodzenia i RP ID zapewniają, że poświadczenia są używane w intencjonalnym kontekście strony internetowej.
Na przykład klucz dostępowy utworzony dla example.com nie może po prostu zostać ponownie użyty przez fałszywą stronę phishingową, taką jak examp1e.com.
Przeglądarka i uwierzytelniacz egzekwują ważne części tego wiązania domenowego, podczas gdy backend samodzielnie weryfikuje otrzymane dowody.
Dobra implementacja używa krótkotrwałych wyzwać, zużywa każde wyzwanie raz i nigdy nie akceptuje dowolnych pochodzeń ze względu na familiarne wyglądanie nazwy hosta.
MDN zaleca generowanie wyzwać w zaufanym środowisku i unieważnianie ich po krótkim okresie, generalnie nie dłużej niż około dziesięciu minut.
10. Nie zamykaj błędnie liczników podpisu
Uwierzytelniacze WebAuthn mogą zawierać licznik podpisu.
Historycznie liczniki pomagali wykrywać potencjalnie sklonowane uwierzytelniacze. Jeśli licznik nieoczekiwanie przestaje rosnąć, party zaufanego może uznać to za sygnał ryzyka.
Jednak nie każdy uwierzytelniacz utrzymuje znaczący licznik.
Niektóre poświadczenia zawsze raportują zero. Zsynchronizowane poświadczenia mogą także complicate interpretację licznika, ponieważ wiele urządzeń może używać kopii tego samego poświadczenia.
Specyfikacja W3C jawnie traktuje nieoczekiwane zachowanie licznika jako możliwy sygnał, a nie definitywne dowody klonowania.
Dlatego deweloperzy nie powinni beztroskowo odrzucać każdego logowania, którego licznik jest zerem lub niezmieniony.
Używaj licznika zgodnie z zachowaniem uwierzytelniacza, wskazówkami biblioteki weryfikacji WebAuthn i polityką bezpieczeństwa aplikacji.
11. Odzyskiwanie konta jest częścią bezpieczeństwa klucza dostępowego
Implementacja klucza dostępowego jest niejednoznaczna bez strategii odzyskiwania.
Co się stanie, gdy użytkownik straci urządzenie?
Co jeśli usunie jedyny klucz dostępowy?
Co jeśli zmieni dostawcę poświadczeń lub nie będzie mógł uzyskać dostępu do zsynchronizowanego poświadczenia?
Sensowny projekt pozwala użytkownikom na rejestrację wielu kluczy dostępowych i zarządzanie nimi z poziomu ustawień konta.
Interfejs zarządzania powinien wyświetlać rozpoznawalne nazwy poświadczeń, daty ich utworzenia i niedawną aktywność, gdzie dostępne.
Użytkownicy powinni móc odwołać poświadczenia, które już nie ufają.
Ale mechanizm odzyskiwania zasługuje na szczególną uwagę.
Jeśli atakujący może obejść uwierzytelnianie kluczem dostępowym za pomocą słabego procesu odzyskiwania e-mailem, całe konto jest tylko tak bezpieczne, jak ta ścieżka odzyskiwania.
Dla kont o wyższym ryzyku rozważ silniejszą weryfikację odzyskiwania, kody odzyskiwania, dodatkowe zarejestrowane uwierzytelniacze oraz powiadomienia o wrażliwych zmianach konta.
Przewodnik UX Google zaleca ustanowienie metody odzyskiwania i wsparcie wielu kluczy dostępowych, gdzie to odpowiednie.
12. Typowe błędy implementacyjne
Wielokrotnie powtarzające się błędy podważają inaczej obiecujące integracje klucza dostępowego.
Traktowanie powodzenia przeglądarki jako uwierzytelniania serwera. Rozwiązane poleczenie navigator.credentials.get() nie zastępuje kryptograficznej weryfikacji po stronie serwera.
Generowanie wyzwać w JavaScript. Wyzwania powinny pochodzić z zaufanego serwera i być powiązane z odpowiednią transakcją uwierzytelniania.
Użycie niewłaściwego RP ID. Govorzenie domenowe jest cechą bezpieczeństwa, a nie ustawieniem graficznym. Środowiska produkcyjne, etapowe i lokalne deweloperskie wymagają celowej konfiguracji.
Założenie, że wszystkie klucze dostępowe są zsynchronizowane. Powiązane z urządzeniem poświadczenia pozostają ważną częścią ekosystemu.
zapominanie o odwoływaniu poświadczeń. Użytkownicy potrzebują sposobu usunięcia utraconego lub skompromitowanego uwierzytelniacza z konta.
Tworzenie słabej alternatywy. Uwierzytelnianie odrzucające phishing traci dużą część swojej wartości, jeśli odzyskiwanie konta może być łatwo wykorzystane.
Ignorowanie starych przeglądarek. Nowe metody JSON ułatwiające zmniejszają złożoność, ale aplikacje z wymaganiami starszych wersji przeglądarek nadal mogą potrzebować kodu kompatybilności.
Pominięcie ochrony CSRF i sesji. Operacje rejestracji i zarządzania poświadczeniami są wrażliwymi zmianami konta. Potrzebują takiej samej ochrony, jak inne wysokopoziomowe działania konta.
Pisanie własnej weryfikacji kryptograficznej bez potrzeby. Zazwyczaj bezpieczniejszy wybór to utrzymywana biblioteka WebAuthn serwera, niż implementacja specyfikacji bezpośrednio.
13. Czy każda strona internetowa powinna natychmiast zastąpić hasła?
Niekoniecznie.
Klucze dostępowe mogą poprawić zarówno użyteczność, jak i bezpieczeństwo, ale strategia migracji ma znaczenie.
Dla nowej aplikacji, rejestracja bez hasła może być rozsądnym domyślnym ustawieniem, jeśli produkt ma dobrze zaprojektowany przepływ odzyskiwania i wspiera swoje docelowe platformy.
Dla istniejącej aplikacji z tysiącami użytkowników, stopniowa adoptacja często jest bezpieczniejsza.
Rozpocznij, pozwalając użytkownikom uwierzytelnionym zarejestrować klucze dostępowe w ustawieniach konta.
Następnie dodaj logowanie kluczem dostępowym obok istniejącego systemu uwierzytelniania.
Wprowadź mediację warunkową, gdzie jest to możliwe.
Mierz powodzenie rejestracji, niepowodzenia uwierzytelniania, kompatybilność urządzeń i żądania odzyskiwania.
W końcu, rozważ uczynienie kluczy dostępowych metodą uwierzytelniania preferowaną, gdy przepływ użytkownika i mechanizmy odzyskiwania będą wystarczająco dojrzałe.
Stopniowa implementacja także ułatwia identyfikację problemów specyficznych dla przeglądarek bez blokowania lojalnych użytkowników.
14. Lista kontrolna gotowości do produkcji
Przed włączeniem kluczy dostępowych do produkcji zweryfikuj następujące rzeczy:
- Wszystkie operacje WebAuthn działają w odpowiednim bezpiecznym kontekście.
- Identyfikatory RP i reputowane pochodzenia są jawno skonfigurowane.
- Wyzwania są kryptograficznie losowe, krótkotrwałe i jednorazowe.
- Rejestracja wymaga odpowiedniej autoryzacji konta.
- Weryfikacja po stronie serwera postępuje zgodnie z specyfikacją WebAuthn.
- Klucze publiczne i identyfikatory poświadczeń są bezpiecznie przechowywane.
- Logowanie ustanawia sesję tylko po pomyślnej weryfikacji.
- Wymagania weryfikacji użytkownika są egzekwowane po stronie serwera.
- Usuwanie poświadczeń i odzyskiwanie konta są chronione.
- Wspierane są wiele poświadczeń na konto tam, gdzie jest to odpowiednie.
- Nieudane uwierzytelniania i wrażliwe zmiany konta są monitorowane.
- Sceny mobilne, desktopowe, cross-urządzeniowe i klucze sprzętowe są testowane.
Te sprawdzenia mają znaczenie większe niż to, czy frontend może wyświetlić atrakcyjny pulsometr biometryczny logowania.
Wniosek: klucze dostępowe to architektura uwierzytelniania, a nie tylko cecha przeglądarki
WebAuthn umożliwia dostęp do publicznego uwierzytelniania dla zwykłych aplikacji webowych.
Nowoczesne API przeglądarki usunęło wiele części pracy serializacyjnej, które wcześniej czyniły integrację klucza dostępowego uciążliwą.
Jednak przeglądarka jest tylko jedną częścią systemu.
Rzeczywista praca implementacyjna leży w zarządzaniu wyzwaczy, weryfikacji po stronie serwera, przechowywaniu poświadczeń, konfiguracji domeny, mechanizmie odzyskiwania i bezpiecznych podróżach użytkownika.
Dla deweloperów tworzących nowoczesne aplikacje w PHP, JavaScript, Pythonie lub innych środowiskach backendowych, klucze dostępowe coraz częściej są warto rozważyć jako praktyczną alternatywę wobec tradycyjnych haseł.
Najlepszym punktem wyjścia nie jest zastąpienie całego systemu uwierzytelniania na nocny świt.
To jest zaimplementowanie jednego w pełni poprawnie zweryfikowanego przepływu rejestracji i logowania, a następnie zbudowanie bezpiecznej strategii migracji wokół niego.