Implementowanie przywracania danych logowania za pomocą Menedżera danych logowania

Na tej stronie dowiesz się, jak utworzyć klucz przywracania, zalogować się za jego pomocą i go usunąć.

Zgodność wersji

Funkcja przywracania danych logowania w Credential Manager działa na urządzeniach z Androidem 9 lub nowszym, Usługami Google Play (GMS) w wersji 24220000 lub nowszej oraz biblioteką androidx.credentials w wersji 1.5.0 lub nowszej.

Wymagania wstępne

Skonfiguruj serwer strony ufającej podobny do serwera dla kluczy dostępu. Jeśli masz już serwer skonfigurowany do obsługi uwierzytelniania za pomocą kluczy dostępu, użyj tej samej implementacji po stronie serwera w przypadku kluczy przywracania.

Zależności

Dodaj te zależności do pliku build.gradle modułu aplikacji:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha02"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02"
}

Funkcja przywracania danych logowania jest dostępna w bibliotece androidx.credentials w wersji 1.5.0 lub nowszej. Zalecamy jednak, aby w miarę możliwości używać najnowszych stabilnych wersji zależności.

Przegląd

  1. Utwórz klucz przywracania: aby utworzyć klucz przywracania, wykonaj te czynności:
    1. Utwórz instancję Credential Manager: utwórz obiekt CredentialManager.
    2. Pobierz opcje tworzenia danych logowania z serwera aplikacji: wyślij do aplikacji klienckiej szczegóły wymagane do utworzenia klucza przywracania z serwera aplikacji.
    3. Utwórz klucz przywracania: utwórz klucz przywracania na koncie użytkownika, jeśli użytkownik jest zalogowany w aplikacji.
    4. Obsłuż odpowiedź na utworzenie danych logowania: wyślij dane logowania z aplikacji klienckiej na serwer aplikacji w celu przetworzenia i obsłuż wszelkie wyjątki.
  2. Zaloguj się za pomocą klucza przywracania: aby zalogować się za pomocą klucza przywracania, wykonaj te czynności:
    1. Pobierz opcje pobierania danych logowania z serwera aplikacji: wyślij do aplikacji klienckiej szczegóły wymagane do pobrania klucza przywracania z serwera aplikacji.
    2. Pobierz klucz przywracania: gdy użytkownik skonfiguruje nowe urządzenie, poproś Credential Manager o klucz przywracania. Dzięki temu użytkownik może się zalogować bez dodatkowych danych.
    3. Obsłuż odpowiedź na pobranie danych logowania: wyślij klucz przywracania z aplikacji klienckiej na serwer aplikacji, aby zalogować użytkownika.
  3. Usuń klucz przywracania.

Tworzenie klucza przywracania

Aplikacja powinna obejmować wszystkie przypadki logowania się użytkownika, aby mieć pewność, że aktywni użytkownicy mają utworzony klucz przywracania. Utwórz klucz przywracania w tych sytuacjach:

  • Jeśli użytkownik jest zalogowany, a klucz przywracania nie został jeszcze utworzony (np. w metodzie onCreate głównego Activity).
  • Gdy użytkownik się loguje lub rejestruje nowe konto.

Aby zoptymalizować wydajność i uniknąć obciążenia związanego z tworzeniem lub sprawdzaniem danych logowania przywracania przy każdym logowaniu, ustaw flagę boolean lub sygnaturę czasową utworzenia danych logowania w pamięci lokalnej, np. has_synced_restore_credential, aby śledzić, czy klucz został już utworzony.

Tworzenie instancji Credential Manager

Aby utworzyć instancję obiektu CredentialManager, użyj kontekstu aktywności aplikacji.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

Pobieranie opcji tworzenia danych logowania z serwera aplikacji

Użyj biblioteki zgodnej z FIDO na serwerze aplikacji, aby wysłać do aplikacji klienckiej informacje wymagane do utworzenia danych logowania przywracania, takie jak informacje o użytkowniku, aplikacji i dodatkowych właściwościach konfiguracji. Więcej informacji o implementacji po stronie serwera znajdziesz w przewodniku po stronie serwera.

Tworzenie klucza przywracania

Po przeanalizowaniu opcji tworzenia klucza publicznego wysłanych przez serwer utwórz klucz przywracania, umieszczając te opcje w CreateRestoreCredentialRequest obiekcie i wywołując createCredential() metodę za pomocą CredentialManager obiektu.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

Najważniejsze informacje o kodzie

  • Obiekt CreateRestoreCredentialRequest zawiera te pola:

    • requestJson: opcje tworzenia danych logowania wysłane przez serwer aplikacji w formacie Web Authentication API dla PublicKeyCredentialCreationOptionsJSON.

    • isCloudBackupEnabled: pole Boolean, które określa, czy klucz przywracania ma być zapisywany w chmurze. Domyślnie ta flaga ma wartość true. To pole ma te wartości:

      • true(zalecane): ta wartość umożliwia zapisywanie kluczy przywracania w chmurze, jeśli użytkownik ma włączoną kopię zapasową Google i pełne szyfrowanie, np. blokadę ekranu.
      • false: ta wartość zapisuje klucz lokalnie, a nie w chmurze. Jeśli użytkownik zdecyduje się na przywrócenie z chmury, klucz nie będzie dostępny na nowym urządzeniu.

Obsługa odpowiedzi na utworzenie danych logowania

Interfejs Credential Manager API zwraca odpowiedź typu CreateRestoreCredentialResponse. Ta odpowiedź zawiera odpowiedź na rejestrację danych logowania klucza publicznego w formacie JSON.

Wyślij klucz publiczny z aplikacji na serwer strony ufającej. Ten klucz publiczny jest podobny do klucza publicznego wygenerowanego podczas tworzenia klucza dostępu. Ten sam kod, który obsługuje tworzenie klucza dostępu na serwerze, może też obsługiwać tworzenie klucza przywracania. Więcej informacji o implementacji po stronie serwera znajdziesz w the przewodniku dotyczącym kluczy dostępu.

Podczas procesu tworzenia klucza przywracania obsłuż te wyjątki:

  • CreateRestoreCredentialDomException: ten wyjątek występuje, jeśli requestJson jest nieprawidłowy i nie jest zgodny z formatem WebAuthn dla PublicKeyCredentialCreationOptionsJSON.
  • E2eeUnavailableException: ten wyjątek występuje, jeśli isCloudBackupEnabled ma wartość true, ale urządzenie użytkownika nie ma kopii zapasowej danych ani pełnego szyfrowania, np. blokady ekranu.
    Aby mieć pewność, że dane logowania przywracania są tworzone we wszystkich przypadkach, musisz wyraźnie obsłużyć wyjątek E2eeUnavailableException, wywołując metodę createCredential z wartością isCloudBackupEnabled ustawioną na true. Jeśli zostanie zgłoszony wyjątek E2eeUnavailableException, przechwyć go i ponownie wywołaj metodę createCredential z wartością isCloudBackupEnabled ustawioną na false.
  • IllegalArgumentException: ten wyjątek występuje, jeśli createRestoreRequest jest pusty lub nie jest prawidłowym formatem JSON albo jeśli nie ma prawidłowego pola user.id które jest zgodne ze specyfikacjami WebAuthn.

Logowanie się za pomocą klucza przywracania

Użyj funkcji przywracania danych logowania, aby automatycznie zalogować użytkownika podczas konfigurowania urządzenia.

Pobieranie opcji pobierania danych logowania z serwera aplikacji

Wyślij do aplikacji klienckiej opcje wymagane do pobrania klucza przywracania z serwera. Podobne wskazówki dotyczące kluczy dostępu na tym etapie znajdziesz w artykule Logowanie się za pomocą klucza dostępu. Więcej informacji o implementacji po stronie serwera znajdziesz w przewodniku po uwierzytelnianiu po stronie serwera.

Pobieranie klucza przywracania

Aby pobrać klucz przywracania na nowym urządzeniu, wywołaj metodę getCredential() na obiekcie CredentialManager.

Zalecamy pobieranie klucza przywracania w obu tych przypadkach:

  • Przy pierwszym uruchomieniu aplikacji na urządzeniu. Przywracanie danych logowania w tym przypadku jest niezależne od przywracania danych aplikacji.
  • Jeśli włączono zapisywanie i przywracanie danych aplikacji, pobierz klucz przywracania natychmiast po przywróceniu danych aplikacji. Użyj BackupAgent, aby skonfigurować kopię zapasową aplikacji i upewnić się, że funkcja getCredential jest wykonywana w wywołaniu zwrotnym onRestoreFinished. Nie używaj metody onRestore, ponieważ jest ona wywoływana tylko w przypadku kopii zapasowych par klucz-wartość, natomiast onRestoreFinished jest wywoływana niezawodnie w przypadku przywracania dowolnego rodzaju kopii zapasowej. Pozwala to uniknąć potencjalnych opóźnień, gdy użytkownicy po raz pierwszy otwierają nowe urządzenie, i umożliwia im korzystanie z aplikacji bez czekania na jej otwarcie. Dzięki temu aplikacja może na przykład wysyłać użytkownikowi powiadomienia, zanim otworzy on aplikację po raz pierwszy na nowym urządzeniu, co jest szczególnie istotne w przypadku aplikacji do przesyłania wiadomości lub komunikacji.
// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

Interfejsy API Credential Manager zwracają odpowiedź typu GetCredentialResponse. Dane logowania zawarte w tej odpowiedzi są wyraźnie typu RestoreCredential, który zawiera klucz publiczny.

Obsługa odpowiedzi na logowanie

Wyślij klucz publiczny z aplikacji na serwer strony ufającej, który może go użyć do zalogowania użytkownika. Po stronie serwera ta czynność jest podobna do logowania się za pomocą klucza dostępu. Ten sam kod, który obsługuje logowanie się za pomocą kluczy dostępu na serwerze, może też obsługiwać logowanie się za pomocą kluczy przywracania. Więcej informacji o implementacji po stronie serwera w przypadku kluczy dostępu znajdziesz w artykule Logowanie się za pomocą klucza dostępu.

Usuwanie klucza przywracania

Credential Manager jest bezstanowy i nie wie o aktywności użytkownika, więc nie usuwa automatycznie kluczy przywracania po ich użyciu. Aby usunąć klucz przywracania, wywołaj metodę clearCredentialState(). Ze względów bezpieczeństwa usuwaj klucz za każdym razem, gdy użytkownik się wylogowuje. Dzięki temu, gdy użytkownik następnym razem otworzy aplikację na tym samym urządzeniu, zostanie wylogowany i poproszony o ponowne zalogowanie się.

Odinstalowanie aplikacji jest interpretowane jako zamiar usunięcia odpowiedniego klucza przywracania z tego urządzenia, podobnie jak zamiar użytkownika podczas wylogowywania się.

Klucze przywracania są usuwane tylko w tych sytuacjach:

  • Działania na poziomie systemu: użytkownicy odinstalowują aplikację lub czyszczą jej dane.
  • Wywołania na poziomie aplikacji: programowo usuń klucz, wywołując metodę clearCredentialState() podczas obsługi wylogowania użytkownika w kodzie aplikacji.

Gdy użytkownik wyloguje się z aplikacji, wywołaj metodę clearCredentialState() na obiekcie CredentialManager.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)