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

Z tego artykułu dowiesz się, jak utworzyć klucz przywracania, zalogować się za jego pomocą i go usunąć.

Zgodność wersji

Przywracanie danych logowania w Menedżerze danych logowania działa na urządzeniach z Androidem 9 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.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

Przywracanie danych logowania jest dostępne w bibliotece androidx.credentials w wersji 1.5.0 lub nowszej. Zalecamy jednak używanie w miarę możliwości najnowszych stabilnych wersji zależności.

Omówienie

  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 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 pobierania danych logowania z serwera aplikacji: wyślij do aplikacji klienckiej szczegóły wymagane do pobrania klucza przywracania z serwera aplikacji.
    2. Pobieranie klucza przywracania: żądanie klucza przywracania od Menedżera poświadczeń, gdy użytkownik konfiguruje 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

Utwórz klucz przywracania po uwierzytelnieniu użytkownika w aplikacji – natychmiast po zalogowaniu się lub podczas kolejnego uruchomienia aplikacji, jeśli użytkownik jest już zalogowany.

Utwórz instancję 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)

Uzyskiwanie 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.

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
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 na potrzeby 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. Jeśli użytkownik zdecyduje się na przywrócenie danych z chmury, klucz nie będzie dostępny na nowym urządzeniu.

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.
  • 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 pola user.id, które jest zgodne ze specyfikacjami WebAuthn.

Logowanie się za pomocą klucza przywracania

Użyj funkcji Przywróć dane logowania, aby podczas konfiguracji urządzenia zalogować użytkownika w trybie cichym.

Pobieranie opcji odzyskiwania danych logowania z serwera aplikacji

Wysyła do aplikacji klienckiej opcje wymagane 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.

Klucz przywracania możesz pobrać w tych sytuacjach:

  • (Zalecane) Bezpośrednio po przywróceniu danych aplikacji. Użyj funkcji BackupAgent, aby skonfigurować kopię zapasową aplikacji i dokończyć getCredential funkcję w wywołaniu zwrotnym onRestore, aby zapewnić przywrócenie danych logowania aplikacji natychmiast po przywróceniu danych aplikacji. Pozwala to uniknąć potencjalnych opóźnień, gdy użytkownicy po raz pierwszy otwierają nowe urządzenie, i umożliwia im interakcję bez czekania na otwarcie aplikacji.
  • przy pierwszym uruchomieniu aplikacji na urządzeniu;

Aby wysyłać użytkownikowi powiadomienia, zanim po raz pierwszy otworzy aplikację na nowym urządzeniu, pobierz klucz przywracania w wywołaniu zwrotnym BackupAgentonRestore. Jest to szczególnie istotne w przypadku aplikacji do obsługi wiadomości i komunikatorów.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

Interfejsy API menedżera danych logowania zwracają odpowiedź typu GetCredentialResponse. Ta odpowiedź zawiera klucz publiczny.

Obsługa odpowiedzi na logowanie

Wyślij klucz publiczny z aplikacji na serwer podmiotu ufającego, który może go użyć do zalogowania użytkownika. Po stronie serwera to działanie jest podobne do logowania się 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 ma stanu 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ę 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)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)