Opublikowano: 9 maja 2025 r., ostatnia aktualizacja: 22 grudnia 2025 r.
Klucze dostępu zapewniają silne uwierzytelnianie odporne na phishing. Jednak zachęcenie użytkowników do ich używania może być trudne. Dzięki automatycznemu tworzeniu kluczy dostępu możesz tworzyć klucze dostępu dla użytkowników w odpowiednim momencie, o ile mają oni już zapisane hasło do Twojej witryny. Warunkowe tworzenie, które umożliwia automatyczne tworzenie kluczy dostępu, jest częścią specyfikacji WebAuthn.
Jak to działa
Aby ułatwić użytkownikom korzystanie z kluczy dostępu, użyj funkcji interfejsu WebAuthn API o nazwie Conditional Create. Warunkowe tworzenie umożliwia witrynie poproszenie użytkownika o klucz dostępu bez konieczności podejmowania przez niego żadnych działań.
Ten proces działa, gdy spełnione są te warunki:
- Użytkownik ma zapisane hasło w domyślnym menedżerze haseł.
- Hasło było niedawno używane. Najlepiej wywołać warunkowe tworzenie natychmiast po udanym logowaniu za pomocą hasła.
Jeśli oba warunki są spełnione, możesz poprosić menedżera haseł o utworzenie klucza dostępu dla użytkownika, wywołując warunkowe tworzenie. Po utworzeniu klucza dostępu użytkownik otrzymuje powiadomienie w zależności od menedżera haseł.
Zgodność
Warunkowe tworzenie jest obsługiwane przez Safari w macOS i wszystkie przeglądarki w iOS, a także Chrome na komputerach i Chrome na Androidzie.
Oznacza to, że działa ono w przypadku domyślnych dostawców kluczy dostępu: pęku kluczy iCloud (Hasła) w Safari w macOS i iOS oraz Menedżera haseł Google w Chrome na komputerach i Androidzie.
Ponieważ iOS 18 lub nowszy i Android 14 lub nowszy obsługują dostawców kluczy dostępu innych firm, niezależnie od przeglądarki używanej przez użytkownika, obsługa warunkowego tworzenia zależy od dostawcy kluczy dostępu. Jeśli wybrany dostawca kluczy dostępu nie obsługuje warunkowego tworzenia, nowy klucz dostępu nie zostanie utworzony.
Implementowanie warunkowego tworzenia
Automatyczne tworzenie kluczy dostępu opiera się na funkcji interfejsu WebAuthn API o nazwie Conditional Create. Są to zwykłe żądania WebAuthn create() z parametrem
mediation ustawionym na "conditional", który działa podobnie jak automatyczne wypełnianie kluczy dostępu
w przypadku żądań get().
Użyj warunkowego tworzenia po zalogowaniu się użytkownika za pomocą hasła. Powodzenie tworzenia zależy od menedżera haseł i spełnienia określonych warunków. Warunki te mogą się różnić w zależności od menedżera haseł i mogą się z czasem zmieniać. Na przykład w Chrome z Menedżerem haseł Google użytkownik musi się niedawno zalogować za pomocą zapisanego hasła do witryny.
Jeśli przeglądarce uda się utworzyć klucz dostępu, zwróci ona dane uwierzytelniające klucza publicznego. Wyślij te dane uwierzytelniające do backendu aby dokończyć rejestrację i włączyć przyszłe uwierzytelnianie.
Wykrywanie funkcji
Możesz sprawdzić, czy warunkowe tworzenie jest dostępne w przeglądarce, wywołując PublicKeyCredential.getClientCapabilities(). Sprawdź, czy zwrócony obiekt zawiera wartość true w przypadku właściwości conditionalCreate.
if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) {
const capabilities = await PublicKeyCredential.getClientCapabilities();
if (capabilities.conditionalCreate) {
// Conditional create is available
}
}
Jeśli getClientCapabilities jest niedostępne, warunkowe tworzenie też jest niedostępne.
Warunkowe tworzenie klucza dostępu
Aby automatycznie utworzyć klucz dostępu, wywołaj
navigator.credentials.create() z parametrem mediation: "conditional" w ten sposób.
const cred = await navigator.credentials.create({
publicKey: options,
// Request conditional creation
mediation: 'conditional'
});
Automatyczne tworzenie kluczy dostępu należy stosować natychmiast po zalogowaniu się użytkownika, aby zwiększyć szanse na spełnienie kryteriów automatycznego tworzenia przez menedżera haseł.
Możesz wysłać uzyskane dane uwierzytelniające klucza publicznego na serwer, aby zweryfikować i zarejestrować klucz dostępu. Upewnij się, że użytkownik jest zalogowany na serwerze.
Zastrzeżenia
Samo warunkowe tworzenie nie jest trudne do wdrożenia, ale podczas integracji tej funkcji z istniejącym systemem należy pamiętać o kilku zastrzeżeniach.
Ignorowanie obecności i weryfikacji użytkownika na serwerze
Odpowiedź rejestracji zwraca zarówno "User Presence" i "User Verified" jako
false, dlatego serwer powinien ignorować te flagi podczas weryfikacji danych uwierzytelniających.
Przerywanie trwającego wywołania WebAuthn przed automatycznym utworzeniem klucza dostępu
Gdy RP oczekuje, że użytkownik zaloguje się za pomocą klucza dostępu lub hasła, najlepszym rozwiązaniem jest wykonanie warunkowego pobrania. Może to spowodować anulowanie wywołania warunkowego pobrania przed wykonaniem warunkowego utworzenia.
Aby to zrobić, musisz użyć AbortController i wywołać .abort().
// To abort a WebAuthn call, instantiate an AbortController.
const controller = new AbortController();
const cred = await navigator.credentials.get({
publicKey: options,
signal: controller.signal,
// Request conditional get
mediation: 'conditional'
});
// Abort the call
controller.abort();
Ignorowanie wyjątków
Podczas warunkowego tworzenia klucza dostępu należy ignorować wyjątki w tych przypadkach:
InvalidStateError: klucz dostępu już istnieje u dostawcy kluczy dostępu. Pamiętaj, aby określićexcludeCredentials.NotAllowedError: utworzenie klucza dostępu nie spełnia warunku.AbortError: wywołanie WebAuthn zostało przerwane.
Wyświetlanie błędów w tych przypadkach może wprowadzać użytkownika w błąd, ponieważ przeglądarka obsługuje je w sposób niewidoczny: powiadomienie jest wyświetlane tylko w przypadku powodzenia, a błędy nie powodują wyświetlania widocznych komunikatów.
Sygnalizowanie nieudanej rejestracji klucza dostępu
Gdy klucz dostępu zostanie utworzony, ale nie uda się go zarejestrować na serwerze, użytkownik zobaczy komunikat o nieudanej próbie logowania. Może się tak zdarzyć, gdy lista kluczy dostępu jest niespójna między dostawcą kluczy dostępu a serwerem.
Aby uniknąć takich sytuacji, użyj interfejsu Signal API, aby zachować spójność.
Uaktualnienie z logowania bez hasła nie jest obsługiwane
W tym momencie warunkowe utworzenie klucza dostępu jest możliwe tylko wtedy, gdy użytkownik wpisze prawidłowe hasło. Oznacza to, że metody logowania bez hasła, takie jak linki magiczne, weryfikacja numeru telefonu czy federacja tożsamości, nie spełnią tego warunku.
Podsumowanie
Automatyczne tworzenie kluczy dostępu może przyspieszyć ich wdrażanie w Twojej witrynie, pomagając użytkownikom przejść od haseł do bezpieczniejszej metody uwierzytelniania.
Aby dowiedzieć się więcej o kluczach dostępu, zacznij od artykułu Logowanie bez hasła za pomocą kluczy dostępu.