Testowanie interfejsu API: natychmiastowe zapośredniczenie WebAuthn w celu bezproblemowego logowania

José Luis Zapata

Data publikacji: 19 sierpnia 2025 r.

Natychmiastowe pośrednictwo WebAuthn to nowa funkcja internetowa, która ma na celu uproszczenie procesów logowania użytkowników. Ten okres próbny pochodzenia zawiera omówienie funkcji, jej zalet i szczegółów implementacji. Zapraszamy do udziału w nim i pomocy w kształtowaniu przyszłości uwierzytelniania w internecie.

Tło

Uwierzytelnianie w internecie często powoduje problemy i utrudnia logowanie użytkownikom. Obecne procesy WebAuthn, choć zaawansowane, mają problemy z przyciskami „Zaloguj się”, zwłaszcza gdy dane logowania nie są od razu dostępne, co prowadzi do standardowych formularzy rezerwowych.

Ta nowa funkcja wprowadza łatwy proces logowania, podobny do interfejsów API preferImmediatelyAvailableCredentials na urządzeniach mobilnych. Upraszcza logowanie, często przed standardowymi formularzami logowania, poprzez zmniejszenie tarcia i poprawę wrażeń użytkownika.

Jak to działa

Natychmiastowe pośrednictwo WebAuthn umożliwia bardziej bezpośrednie i wydajne logowanie. Umożliwia przeglądarce natychmiastowe oferowanie dostępnych danych logowania lub natychmiastowe sygnalizowanie ich braku bez wyświetlania prośby o uwierzytelnianie na różnych urządzeniach lub za pomocą klucza bezpieczeństwa, co upraszcza wdrożenie dla programistów.

immediate Rodzaj zapośredniczenia

Wprowadzamy typ zapośredniczenia immediate w przypadku żądań navigator.credentials.get(). Jeśli ta opcja jest ustawiona, obietnica odrzuca NotAllowedError, jeśli nie znaleziono lokalnie dostępnych danych logowania. Jeśli dane logowania są obecne, przeglądarka obsługuje proces uwierzytelniania w normalny sposób.

Ta elastyczność umożliwia witrynom dostosowywanie procesu logowania i płynne udostępnianie alternatywnych metod, gdy natychmiastowe dane logowania są niedostępne.

Co ważne, przeglądarki mogą nadal zwracać NotAllowedError, aby chronić prywatność i bezpieczeństwo użytkowników, zapobiegając problemom takim jak fingerprinting czy śledzenie.

Wykrywanie cech

Aby sprawdzić, czy dostępna jest natychmiastowa mediacja, użyj tego kodu:PublicKeyCredential.getClientCapabilities() Programiści mogą sprawdzić możliwość immediateGet w zwróconym obiekcie capabilities.

async function checkImmediateMediationAvailability() {
  try {
    const capabilities = await PublicKeyCredential.getClientCapabilities();
    if (capabilities.immediateGet && window.PasswordCredential) {
      console.log("Immediate Mediation with passwords supported.");
    } else if (capabilities.immediateGet) {
      console.log("Immediate Mediation without passwords supported.");
    } else { console.log("Immediate Mediation unsupported."); }
  } catch (error) {
    console.error("Error getting client capabilities:", error);
  }
}

Uwaga: aby zapewnić szerszą obsługę przeglądarek, w repozytorium WebAuthn Polyfills w GitHubie dostępny jest polyfill dla elementu getClientCapabilities().

Przykładowa implementacja

Aby użyć interfejsu API, wywołaj metodę navigator.credentials.get() z parametrem mediation: 'immediate'. Zalecamy uwzględnienie w prośbie wartości password: true, ponieważ większość użytkowników ma obecnie zapisane hasło i może od razu skorzystać z tej funkcji.

button.addEventListener('click', async (event) => {
  event.preventDefault();
  event.stopPropagation();
  const cred = await navigator.credentials.get({
    password: true,
    publicKey: {
      challenge, // Your server-generated challenge
      rpId: 'example.com' // Your Relying Party ID
    },
    mediation: 'immediate',
  });
});

Deweloperzy powinni obsługiwać NotAllowedError w bloku catch, aby zapewnić płynne logowanie w przypadku błędu.

Szczegółowy proces dotyczący natychmiastowego zapośredniczenia

Natychmiastowe pośrednictwo WebAuthn obsługuje 2 główne przypadki użycia, które usprawniają logowanie użytkowników: włączenie specjalnego przycisku „Zaloguj się za pomocą klucza dostępu”, który pomija niechciane opcje rezerwowe, oraz ułatwienie dynamicznego procesu logowania, który proaktywnie oferuje dane logowania przed wykonaniem przez użytkownika krytycznej czynności.

Przypadek użycia 1. Jawne logowanie za pomocą przycisku logowania

Ten scenariusz koncentruje się na udostępnieniu specjalnego przycisku logowania, który zapewnia przejrzystość i wygodę użytkowania bez nieoczekiwanych monitów i konieczności przechodzenia przez stronę logowania.

1. Użytkownik inicjuje logowanie: użytkownik klika przycisk „Zaloguj się”. Usługa zaufana wywołuje wtedy funkcję navigator.credentials.get() z parametrem mediation: "immediate".
2. Przeglądarka wyświetla prośbę o wybranie danych logowania (jeśli są dostępne): przeglądarka sprawdza, czy są dostępne lokalnie klucze dostępu lub żądane hasła. Jeśli znajdzie jakieś konta, natychmiast wyświetli interfejs modalny, w którym użytkownik może wybrać konto. Konta są sortowane według sygnatury czasowej ostatniego użycia, a następnie alfabetycznie. Uwaga: jeśli dla tego samego konta zostaną znalezione zarówno hasła, jak i klucze dostępu z różnych menedżerów haseł, przeglądarka nada priorytet kluczom dostępu. Jeśli na tym samym koncie jest kilka kluczy dostępu od różnych dostawców, priorytet ma ostatnio użyty klucz dostępu.
3. Udane logowanie: użytkownik wybiera klucz dostępu w interfejsie przeglądarki. Jeśli przeglądarka wymaga weryfikacji, prosi użytkownika o potwierdzenie tożsamości za pomocą wcześniej skonfigurowanej metody (np. kodu PIN, danych biometrycznych lub wzoru). Logowanie zostało zakończone.
4. Ścieżka rezerwowa: brak klucza dostępu lub odrzucenie przez użytkownika: jeśli dla witryny nie są dostępne lokalne klucze dostępu ani żądane hasła lub jeśli użytkownik odrzuci interfejs przeglądarki, przeglądarka wyśle do podmiotu polegającego NotAllowedError i nie wyświetli żadnego interfejsu opcji dotyczących urządzeń ani kluczy bezpieczeństwa. Strona ufająca może wtedy przejść do standardowej strony logowania lub zaoferować alternatywne mechanizmy uwierzytelniania.

Przypadek użycia 2. Proces logowania niejawnego przed działaniem użytkownika

Ten scenariusz umożliwia proaktywne logowanie, oferując klucze dostępu i hasła, zanim użytkownik wykona działanie wymagające uwierzytelnienia, takie jak płatność.

1. Użytkownik inicjuje działanie wymagające zalogowania: użytkownik klika przycisk działania, które wymaga zalogowania (np. przycisk „Zapłać”). Podmiot ufający wywołuje wtedy funkcję navigator.credentials.get() z parametrem mediation: "immediate".

2. Przeglądarka wyświetla prośbę o wybranie danych logowania (jeśli są dostępne): przeglądarka sprawdza, czy są dostępne lokalnie klucze dostępu lub hasła. Jeśli znajdzie takie konta, natychmiast wyświetli interfejs modalny, w którym użytkownik może wybrać konto. Konta są sortowane według sygnatury czasowej ostatniego użycia, a następnie alfabetycznie. Duplikaty są usuwane, aby wyświetlać tylko jeden wpis na konto. Uwaga: jeśli dla tego samego konta zostaną znalezione hasła i klucze dostępu z różnych menedżerów haseł, przeglądarka nada priorytet kluczom dostępu. Jeśli na tym samym koncie jest kilka kluczy dostępu od różnych dostawców, priorytet ma ostatnio użyty klucz dostępu.

3. Udane logowanie: użytkownik wybiera dane logowania w interfejsie przeglądarki. Jeśli przeglądarka wymaga weryfikacji, prosi użytkownika o potwierdzenie tożsamości za pomocą wcześniej skonfigurowanej metody (np. kodu PIN, danych biometrycznych lub wzoru). Logowanie zostało zakończone.

4. Ścieżka rezerwowa: brak danych logowania lub odrzucenie przez użytkownika: jeśli w przypadku witryny nie są dostępne lokalne dane logowania lub użytkownik odrzuci interfejs przeglądarki, przeglądarka zgłosi błąd NotAllowedError do podmiotu polegającego na tożsamości, a przeglądarka nie wyświetli żadnego interfejsu. Sposób logowania użytkownika pozostanie bez zmian. Strona ufająca może wtedy poprosić użytkownika o podanie dodatkowych informacji (np. adresu e-mail) lub wyświetlić alternatywne mechanizmy uwierzytelniania, takie jak formularz hasła, weryfikacja SMS-em lub modalne żądanie WebAuthn, które obsługuje uwierzytelnianie na różnych urządzeniach.

Zalety

Natychmiastowe pośrednictwo WebAuthn ma kilka kluczowych zalet dla programistów i użytkowników:

• Bezproblemowe logowanie: zapewnia płynniejsze i mniej uciążliwe logowanie użytkownikom, którzy mają natychmiast dostępne klucze dostępu lub hasła zapisane w przeglądarce lub menedżerze haseł.
• Inteligentne logowanie: interfejs API umożliwia proces logowania, gdy użytkownik chce wykonywać działania, które wymagają zalogowania się. Dostosowują się one inteligentnie do stanu certyfikatu użytkownika. Umożliwia natychmiastowe uwierzytelnianie, gdy jest to możliwe, co pozwala uniknąć niepotrzebnych przekierowań i upraszcza proces.
• Ulepszone zarządzanie danymi logowania: gdy kilku menedżerów haseł oferuje dane logowania do tego samego konta, przeglądarka inteligentnie wybiera najbardziej odpowiednią opcję, co upraszcza zarządzanie danymi logowania dla użytkowników.
• Mniejsze zamieszanie wśród użytkowników: dzięki bezpośredniemu wyświetlaniu znanych danych logowania funkcja minimalizuje zamieszanie wśród użytkowników, które często wiąże się z wieloma opcjami logowania lub standardowymi formularzami.
• Płynne przejście: zapewnia płynne przejście do standardowych stron logowania dla użytkowników, którzy nie mają natychmiastowych danych logowania, co oznacza, że ich wrażenia pozostają niezmienione w porównaniu z obecnymi procesami.

Prywatność i bezpieczeństwo

Natychmiastowe pośrednictwo WebAuthn umożliwia witrynom identyfikowanie obecności natychmiast dostępnych danych logowania, zanim użytkownik wyraźnie autoryzuje próbę zalogowania się. Aby chronić prywatność użytkowników i zapobiegać potencjalnym nadużyciom, stosujemy kilka kluczowych środków:

• Wymaganie dotyczące gestu użytkownika: wywołanie interfejsu API wymaga gestu użytkownika (dowolnej tymczasowej aktywacji użytkownika). Utrudnia to witrynom ciche sondowanie i odciski cyfrowe.
• Sesje incognito i prywatne: w sesjach incognito i prywatnych każde natychmiastowe żądanie mediacji zwraca błąd NotAllowedError.
• Ograniczenia dotyczące list allowCredentials: żądania korzystające z list allowCredentials zwracają błąd NotAllowedError. Zapobiega to wyciąganiu przez witryny wniosków na temat historii interakcji użytkownika lub śledzeniu go w różnych sesjach.
• Anulowanie: ustawienie parametru signal w przypadku żądania z natychmiastową mediacją jest nieprawidłowe. Zapobiega to programowemu zamykaniu przez witryny interfejsu przeglądarki.

Wypróbuj

Zachęcamy do wypróbowania natychmiastowego pośrednictwa WebAuthn.

Stan w Chrome

Ta funkcja jest w trakcie cyklu rozwoju Chromium:

• Komputery: wersja próbna dla programistów w Chrome 136, a wersja próbna origin w Chrome 139–141.
• Android: wersja próbna dla programistów w Chrome 140.

Testowanie lokalne

Aby przetestować lokalnie natychmiastowe zapośredniczenie WebAuthn:

1. Pobierz Chrome 139: pobierz i otwórz najnowszą wersję Chrome na komputerze.
2. Włącz flagę natychmiastowego pośrednictwa: na pasku adresu wpisz chrome://flags/#web-authentication-immediate-get i włącz flagę „Web Authentication Immediate Get”.
3. Przygotuj dane logowania: upewnij się, że masz zapisane klucze dostępu i hasła, których możesz użyć:
   • hasła zapisane w Menedżerze haseł Google;
   • Klucze dostępu zapisane w Menedżerze haseł Google (wymaga zalogowania się i synchronizacji Chrome z kontem Google), Windows Hello lub w pęku kluczy iCloud.

W przypadku testów publicznych (testowanie origin)

Aby przetestować natychmiastowe zapośredniczenie WebAuthn w ramach wersji próbnej origin w środowisku publicznym:

1. Zarejestruj się: otwórz stronę wersji próbnych origin w Chrome i zarejestruj się w wersji próbnej „WebAuthn immediate mediation”.
2. Dodaj token do nagłówków HTTP: umieść podany token testu pochodzenia w nagłówkach HTTP witryny:HTML Origin-Trial: [YOUR_TRIAL_TOKEN]

Uwaga: możesz też dostarczać tokeny programowo za pomocą JavaScriptu.

Scenariusze testów

Udostępniamy implementację referencyjną i zachęcamy do stworzenia własnego prototypu, aby przetestować różne scenariusze.

• Prezentacja referencyjna: możesz wypróbować implementację referencyjną na stronie https://deephand.github.io/webauthn-immediate-demo/.
  • Wdróż prototyp: wdrażając prototyp w witrynie, pamiętaj, aby wywoływać funkcję navigator.credentials.get() z parametrem mediation: 'immediate' po kliknięciu przez użytkownika (np. przycisku „Zaloguj się” lub dowolnej interakcji, która wymaga zalogowania się użytkownika).
• Ścieżka 1. Logowanie bez hasła lub klucza dostępu: jeśli nie masz kluczy dostępu ani haseł dostępnych w witrynie, kliknięcie „Zaloguj się” prowadzi bezpośrednio do standardowej strony logowania bez interfejsu przeglądarki.
• Ścieżka 2. Logowanie za pomocą lokalnego klucza dostępu dostępnego od razu: jeśli masz zapisany klucz dostępu do witryny, kliknięcie „Zaloguj się” powinno spowodować wyświetlenie interfejsu natychmiastowego pośrednictwa, który umożliwia wybranie klucza dostępu.
• Ścieżka 3. Logowanie za pomocą lokalnego klucza dostępu lub hasła: jeśli masz zapisane zarówno klucze dostępu, jak i hasła, włącz opcję „Poproś o hasło” (ustawiając w kodzie wartość password: true). Po kliknięciu „Zaloguj się” w interfejsie natychmiastowego zapośredniczenia powinny być dostępne zarówno klucz dostępu, jak i hasło.