Anmeldedaten mit Credential Manager wiederherstellen

Auf dieser Seite wird beschrieben, wie Sie einen Wiederherstellungsschlüssel erstellen, sich damit anmelden und ihn löschen.

Versionskompatibilität

Die Funktion „Anmeldedaten wiederherstellen“ des Credential Manager funktioniert auf Geräten mit Android 9 (API‑Level 28) und höher, Google Play-Diensten (GMS) in der Core-Version 24220000 oder höher und der androidx.credentials-Bibliothek in Version 1.5.0 oder höher.

Vorbereitung

Richten Sie einen Server für die vertrauende Seite ein, der dem Server für Passkeys ähnelt. Wenn Sie bereits einen Server eingerichtet haben, um die Authentifizierung mit Passkeys zu verarbeiten, verwenden Sie dieselbe serverseitige Implementierung für Wiederherstellungsschlüssel.

Abhängigkeiten

Fügen Sie der Datei build.gradle Ihres App-Moduls die folgenden Abhängigkeiten hinzu:

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"
}

Anmeldedaten-Wiederherstellung ist ab Version 1.5.0 oder höher der androidx.credentials-Bibliothek verfügbar. Es wird jedoch empfohlen, nach Möglichkeit die neuesten stabilen Versionen der Abhängigkeiten zu verwenden.

Übersicht

  1. Wiederherstellungsschlüssel erstellen: Führen Sie die folgenden Schritte aus, um einen Wiederherstellungsschlüssel zu erstellen:
    1. Credential Manager instanziieren: Erstellen Sie ein CredentialManager-Objekt.
    2. Optionen zum Erstellen von Anmeldedaten vom App-Server abrufen: Senden Sie der Client-App die Details, die zum Erstellen des Wiederherstellungsschlüssels von Ihrem App-Server erforderlich sind.
    3. Wiederherstellungsschlüssel erstellen: Erstellen Sie einen Wiederherstellungsschlüssel für das Konto des Nutzers, wenn er in Ihrer App angemeldet ist.
    4. Antwort auf die Erstellung von Anmeldedaten verarbeiten: Senden Sie die Anmeldedaten von Ihrer Client-App zur Verarbeitung an Ihren App-Server und verarbeiten Sie alle Ausnahmen.
  2. Mit Wiederherstellungsschlüssel anmelden: So melden Sie sich mit einem Wiederherstellungsschlüssel an:
    1. Optionen zum Abrufen von Anmeldedaten vom App-Server abrufen: Senden Sie der Client-App die Details, die zum Abrufen des Wiederherstellungsschlüssels von Ihrem App-Server erforderlich sind.
    2. Wiederherstellungsschlüssel abrufen: Fordern Sie den Wiederherstellungsschlüssel von der Anmeldeinformationsverwaltung an, wenn der Nutzer ein neues Gerät einrichtet. So kann sich der Nutzer ohne zusätzliche Eingabe anmelden.
    3. Antwort auf den Abruf von Anmeldedaten verarbeiten: Senden Sie den Wiederherstellungsschlüssel von der Client-App an den App-Server, um den Nutzer anzumelden.
  3. Wiederherstellungsschlüssel löschen

Wiederherstellungsschlüssel erstellen

Ihre App sollte alle Fälle abdecken, in denen sich ein Nutzer anmeldet, damit für aktive Nutzer ein Wiederherstellungsschlüssel erstellt wird. Erstellen Sie den Wiederherstellungsschlüssel in den folgenden Szenarien:

  • Wenn der Nutzer angemeldet ist und noch kein Wiederherstellungsschlüssel erstellt wurde (z. B. in der Methode onCreate für die Haupt-Activity).
  • Wenn sich der Nutzer anmeldet oder die Registrierung für ein neues Konto abschließt.

Um die Leistung zu optimieren und den Aufwand für das Erstellen oder Prüfen von Wiederherstellungsanmeldedaten bei jeder einzelnen Anmeldung zu vermeiden, legen Sie ein boolean-Flag oder einen Zeitstempel für die Erstellung von Anmeldedaten im lokalen Speicher fest, z. B. has_synced_restore_credential, um zu verfolgen, ob der Schlüssel bereits erstellt wurde.

Credential Manager instanziieren

Verwenden Sie den Aktivitätskontext Ihrer App, um ein CredentialManager-Objekt zu instanziieren.

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

Optionen zum Erstellen von Anmeldedaten von Ihrem App-Server abrufen

Verwenden Sie auf Ihrem App-Server eine FIDO-kompatible Bibliothek, um Ihrer Client-App die Informationen zu senden, die zum Erstellen der Wiederherstellungsanmeldedaten erforderlich sind, z. B. Informationen zum Nutzer, zur App und zusätzliche Konfigurationseigenschaften. Weitere Informationen zur serverseitigen Implementierung finden Sie unter Serverseitige Anleitung.

Wiederherstellungsschlüssel erstellen

Nachdem Sie die vom Server gesendeten Optionen zum Erstellen des öffentlichen Schlüssels geparst haben, erstellen Sie einen Wiederherstellungsschlüssel, indem Sie diese Optionen in ein CreateRestoreCredentialRequest-Objekt einfügen und die Methode createCredential() mit dem CredentialManager-Objekt aufrufen.

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

Wichtige Punkte zum Code

  • Das Objekt CreateRestoreCredentialRequest enthält die folgenden Felder:

    • requestJson: Die vom App-Server gesendeten Optionen zum Erstellen von Anmeldedaten im Web Authentication API-Format für PublicKeyCredentialCreationOptionsJSON.

    • isCloudBackupEnabled: Boolean-Feld, um festzustellen, ob der Wiederherstellungsschlüssel in der Cloud gesichert werden soll. Standardmäßig ist dieses Flag true. Dieses Feld kann die folgenden Werte enthalten:

      • true: (Empfohlen) Mit diesem Wert können Sicherungsschlüssel in der Cloud gesichert werden, wenn der Nutzer Google-Back-up und Ende-zu-Ende-Verschlüsselung aktiviert hat, z. B. eine Displaysperre.
      • false: Mit diesem Wert wird der Schlüssel lokal und nicht in der Cloud gespeichert. Der Schlüssel ist auf dem neuen Gerät nicht verfügbar, wenn der Nutzer die Daten aus der Cloud wiederherstellt.

Antwort auf die Erstellung von Anmeldedaten verarbeiten

Die Credential Manager API gibt eine Antwort vom Typ CreateRestoreCredentialResponse zurück. Diese Antwort enthält die Antwort auf die Registrierung von Anmeldedaten für den öffentlichen Schlüssel im JSON-Format.

Senden Sie den öffentlichen Schlüssel Ihrer App an den Server der vertrauenden Partei. Dieser öffentliche Schlüssel ähnelt dem öffentlichen Schlüssel, der beim Erstellen eines Passkeys generiert wird. Mit demselben Code, der die Passkey-Erstellung auf dem Server verarbeitet, kann auch die Erstellung von Wiederherstellungsschlüsseln verarbeitet werden. Weitere Informationen zur serverseitigen Implementierung finden Sie in der Anleitung für Passkeys.

Behandeln Sie während der Erstellung des Wiederherstellungsschlüssels die folgenden Ausnahmen:

  • CreateRestoreCredentialDomException: Diese Ausnahme tritt auf, wenn requestJson ungültig ist und nicht dem WebAuthn-Format für PublicKeyCredentialCreationOptionsJSON entspricht.
  • E2eeUnavailableException: Diese Ausnahme tritt auf, wenn isCloudBackupEnabled true ist, das Gerät des Nutzers aber keine Datensicherung oder Ende-zu-Ende-Verschlüsselung wie eine Displaysperre hat.
    Damit in allen Fällen Anmeldedaten-Wiederherstellung erstellt werden, müssen Sie E2eeUnavailableException explizit verarbeiten, indem Sie createCredential mit isCloudBackupEnabled auf true aufrufen. Wenn E2eeUnavailableException ausgelöst wird, fangen Sie sie ab und rufen Sie createCredential noch einmal auf. Setzen Sie isCloudBackupEnabled auf false.
  • IllegalArgumentException: Diese Ausnahme tritt auf, wenn createRestoreRequest leer oder kein gültiges JSON ist oder wenn es kein gültiges user.id enthält, das den WebAuthn-Spezifikationen entspricht.

Mit einem Wiederherstellungsschlüssel anmelden

Verwenden Sie die Anmeldedaten-Wiederherstellung, um den Nutzer während der Geräteeinrichtung im Hintergrund anzumelden.

Optionen zum Abrufen von Anmeldedaten vom App-Server abrufen

Senden Sie der Client-App die Optionen, die zum Abrufen des Wiederherstellungsschlüssels vom Server erforderlich sind. Eine ähnliche Anleitung für diesen Schritt finden Sie unter Mit einem Passkey anmelden. Weitere Informationen zur serverseitigen Implementierung finden Sie im Leitfaden zur serverseitigen Authentifizierung.

Wiederherstellungsschlüssel abrufen

Rufen Sie zum Abrufen des Wiederherstellungsschlüssels auf dem neuen Gerät die Methode getCredential() für das Objekt CredentialManager auf.

Es wird empfohlen, den Wiederherstellungsschlüssel in den folgenden beiden Szenarien abzurufen:

  • Beim ersten Start der App auf dem Gerät. Die Wiederherstellung von Anmeldedaten in diesem Szenario ist unabhängig von der Wiederherstellung der App-Daten.
  • Wenn die Sicherung und Wiederherstellung von App-Daten aktiviert ist, rufen Sie den Wiederherstellungsschlüssel sofort nach der Wiederherstellung der App-Daten ab. Verwenden Sie BackupAgent, um die Sicherung Ihrer App zu konfigurieren, und stellen Sie sicher, dass Sie die getCredential-Funktionalität innerhalb des onRestoreFinished-Callbacks abschließen. Verwenden Sie nicht die Methode onRestore, da sie nur für Schlüssel/Wert-Sicherungen aufgerufen wird, während onRestoreFinished zuverlässig für jede Art von Sicherungswiederherstellung aufgerufen wird. So werden potenzielle Verzögerungen vermieden, wenn Nutzer ihr neues Gerät zum ersten Mal öffnen. Außerdem können Nutzer mit der App interagieren, ohne dass sie sie öffnen müssen. Ihre App kann dem Nutzer beispielsweise Benachrichtigungen senden, bevor er die App zum ersten Mal auf dem neuen Gerät öffnet. Das ist besonders für Messaging- oder Kommunikations-Apps relevant.

Wenn Sie ein neues BackupAgent erstellen und die Sicherung zuvor mit allowBackup="true" aktiviert war, legen Sie den booleschen Wert android:fullBackupOnly="true" im Manifest Ihrer App fest. So wird sichergestellt, dass das Verhalten Ihrer App beim Sichern und Wiederherstellen beibehalten wird.

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

Die Credential Manager APIs geben eine Antwort vom Typ GetCredentialResponse zurück. Das in dieser Antwort enthaltene Anmeldedatenobjekt ist explizit vom Typ RestoreCredential, der den öffentlichen Schlüssel enthält.

Anmeldeantwort verarbeiten

Senden Sie den öffentlichen Schlüssel aus der App an den Server der vertrauenden Partei, der dann verwendet werden kann, um den Nutzer anzumelden. Auf der Serverseite ist diese Aktion mit der Anmeldung mit einem Passkey vergleichbar. Mit demselben Code, der die Anmeldung mit Passkeys auf dem Server verarbeitet, können auch Anmeldungen mit Wiederherstellungsschlüsseln verarbeitet werden. Weitere Informationen zur serverseitigen Implementierung von Passkeys finden Sie unter Mit einem Passkey anmelden.

Wiederherstellungsschlüssel löschen

Credential Manager ist zustandslos und kennt keine Nutzeraktivitäten. Daher werden Wiederherstellungsschlüssel nach der Verwendung nicht automatisch gelöscht. Rufen Sie zum Löschen eines Wiederherstellungsschlüssels die Methode clearCredentialState auf. Aus Sicherheitsgründen sollten Sie den Schlüssel löschen, wenn sich ein Nutzer abmeldet. So wird sichergestellt, dass der Nutzer beim nächsten Öffnen der App auf demselben Gerät abgemeldet wird und sich noch einmal anmelden muss.

Die Deinstallation einer App wird als Absicht interpretiert, den entsprechenden Wiederherstellungsschlüssel von diesem Gerät zu löschen, ähnlich wie die Absicht des Nutzers beim Abmelden.

Wiederherstellungsschlüssel werden nur in den folgenden Situationen entfernt:

  • Aktionen auf Systemebene: Nutzer deinstallieren die App oder löschen ihre Daten.
  • Aufrufe auf App-Ebene: Löschen Sie den Schlüssel programmatisch, indem Sie clearCredentialState() aufrufen, wenn Sie die Nutzerabmeldung im Code Ihrer App verarbeiten.

Wenn sich der Nutzer von Ihrer App abmeldet, rufen Sie die Methode clearCredentialState() für das CredentialManager-Objekt auf.

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