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 Menedżerze danych logowania działa na urządzeniach z Androidem 9 (poziom interfejsu API 28) lub nowszym, podstawową wersją usług Google Play (GMS) 24220000 lub nowszą oraz biblioteką androidx.credentials w wersji 1.5.0 lub nowszej.

Wymagania wstępne

Skonfiguruj serwer jednostki uzależnionej podobny do serwera 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 Przywracanie danych uwierzytelniających jest dostępna w bibliotece androidx.credentials w wersji 1.5.0 i nowszej. Zalecamy jednak używanie w miarę możliwości 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 z serwera aplikacji opcje tworzenia danych logowania: wyślij do aplikacji klienta szczegóły wymagane do utworzenia klucza przywracania z serwera aplikacji.
    3. Utwórz klucz przywracania: utwórz klucz przywracania dla konta użytkownika, jeśli jest on zalogowany w Twojej aplikacji.
    4. Obsługa odpowiedzi 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 odzyskiwania danych logowania z serwera aplikacji: wyślij do aplikacji klienta szczegóły wymagane do pobrania klucza przywracania z serwera aplikacji.
    2. Pobieranie klucza przywracania: poproś Menedżera poświadczeń o klucz przywracania, gdy użytkownik skonfiguruje nowe urządzenie. Dzięki temu użytkownik może zalogować się bez dodatkowych danych.
    3. Obsługa odpowiedzi dotyczącej pobierania danych logowania: wyślij klucz przywracania z aplikacji klienta na serwer aplikacji, aby zalogować użytkownika.
  3. Usuń klucz przywracania.

Tworzenie klucza przywracania

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

  • Jeśli użytkownik jest zalogowany, a klucz przywracania nie został jeszcze utworzony (np. w przypadku metody onCreate dla głównego Activity).
  • Gdy użytkownik loguje się lub przechodzi proces rejestracji nowego konta.

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

Tworzenie instancji Menedżera danych logowania

Użyj kontekstu aktywności aplikacji, aby utworzyć instancję obiektu CredentialManager.

// 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 na serwerze aplikacji biblioteki zgodnej z FIDO, aby wysłać do aplikacji klienckiej informacje wymagane do utworzenia danych logowania do przywracania, takie jak informacje o użytkowniku, aplikacji i dodatkowe właściwości konfiguracyjne. Więcej informacji o implementacji po stronie serwera znajdziesz w tym przewodniku.

Tworzenie klucza przywracania

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

// 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 określające, czy klucz przywracania powinien być przechowywany w chmurze. Domyślnie ta flaga ma wartość true. To pole ma te wartości:

      • true: (Zalecane) Ta wartość umożliwia tworzenie kopii zapasowych kluczy przywracania w chmurze, jeśli użytkownik ma włączoną kopię zapasową Google i szyfrowanie end-to-end, np. blokadę ekranu.
      • false: ta wartość zapisuje klucz lokalnie, a nie w chmurze. Klucz nie jest dostępny na nowym urządzeniu, jeśli użytkownik zdecyduje się przywrócić dane z chmury.

Obsługa odpowiedzi na żądanie utworzenia danych logowania

Interfejs Credential Manager API zwraca odpowiedź typu CreateRestoreCredentialResponse. Ta odpowiedź zawiera odpowiedź rejestracyjną dotyczącą danych logowania klucza publicznego w formacie JSON.

Wyślij klucz publiczny z aplikacji na serwer podmiotu ufającego. Ten klucz publiczny jest podobny do klucza publicznego generowanego 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 wdrażaniu po stronie serwera znajdziesz w tym przewodniku.

Podczas tworzenia klucza przywracania obsługuj 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 Przywracanie danych uwierzytelniających jest tworzone we wszystkich przypadkach, musisz obsłużyć E2eeUnavailableException, wywołując createCredential z parametrem isCloudBackupEnabled ustawionym na true. Jeśli zostanie zgłoszony wyjątek E2eeUnavailableException, przechwyć go i ponownie wywołaj funkcję createCredential, ustawiając wartość isCloudBackupEnabled na false.
  • IllegalArgumentException: ten wyjątek występuje, jeśli createRestoreRequest jest pusty lub nie jest prawidłowym plikiem JSON albo jeśli nie zawiera prawidłowego elementu user.id, który jest zgodny ze specyfikacjami WebAuthn.

Logowanie się za pomocą klucza przywracania

Użyj funkcji Przywracanie danych uwierzytelniających, aby w sposób niezauważalny dla użytkownika zalogować go podczas procesu konfiguracji urządzenia.

Pobieranie opcji odzyskiwania danych logowania z serwera aplikacji

Wysyłanie do aplikacji klienckiej opcji wymaganych do pobrania klucza przywracania z serwera. Podobne wskazówki dotyczące kluczy dostępu znajdziesz w artykule Logowanie się za pomocą klucza dostępu. Więcej informacji o wdrażaniu po stronie serwera znajdziesz w przewodniku po uwierzytelnianiu po stronie serwera.

Pobieranie klucza przywracania

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

Zalecamy pobranie klucza przywracania w obu tych przypadkach:

  • przy pierwszym uruchomieniu aplikacji na urządzeniu; Przywracanie danych logowania w tym scenariuszu jest niezależne od przywracania danych aplikacji.
  • Jeśli tworzenie i przywracanie kopii zapasowej danych aplikacji jest włączone, klucz przywracania zostanie pobrany natychmiast po przywróceniu danych aplikacji. Użyj BackupAgent, aby skonfigurować kopię zapasową aplikacji i upewnić się, że funkcja getCredential została zaimplementowana w wywołaniu zwrotnym onRestoreFinished. Nie używaj metody onRestore, ponieważ jest ona wywoływana tylko w przypadku kopii zapasowych typu klucz-wartość, a metoda 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 konieczności jej otwierania. Na przykład aplikacja może wysyłać użytkownikowi powiadomienia, zanim po raz pierwszy otworzy on aplikację na nowym urządzeniu. Jest to szczególnie istotne w przypadku aplikacji do przesyłania wiadomości lub komunikacji.

Jeśli tworzysz nowy BackupAgent, a wcześniej miałeś włączoną kopię zapasową za pomocą allowBackup="true", ustaw wartość logiczną android:fullBackupOnly="true" w pliku manifestu aplikacji. Dzięki temu zachowanie aplikacji podczas tworzenia i przywracania kopii zapasowej zostanie zachowane.

// 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 menedżera danych logowania 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 być następnie używany do logowania użytkownika. Po stronie serwera to działanie jest podobne do logowania za pomocą klucza dostępu. Ten sam kod, który obsługuje logowanie za pomocą kluczy dostępu na serwerze, może też obsługiwać logowanie za pomocą kluczy przywracania. Więcej informacji o wdrażaniu kluczy dostępu po stronie serwera znajdziesz w artykule Logowanie się za pomocą klucza dostępu.

Usuń klucz przywracania

Menedżer danych logowania nie przechowuje stanu i nie śledzi 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ę wyloguje. Dzięki temu następnym razem, gdy użytkownik otworzy aplikację na tym samym urządzeniu, zostanie wylogowany i poproszony o ponowne zalogowanie się.

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

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 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)