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“ von Credential Manager funktioniert auf Geräten mit Android 9 und höher, Google Play-Diensten (GMS) in der Core-Version 24220000 oder höher und der Version 1.5.0 oder höher der Bibliothek androidx.credentials.

Vorbereitung

Richten Sie einen Server für die vertrauende Partei ein, der dem Server für Passkeys ähnelt. Wenn Sie bereits einen Server für die Authentifizierung mit Passkeys eingerichtet haben, 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"
}

Die Funktion „Anmeldedaten wiederherstellen“ ist ab Version 1.5.0 der Bibliothek androidx.credentials verfügbar. Wir empfehlen jedoch, 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 zur Erstellung 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 der Nutzer in Ihrer App angemeldet ist.
    4. Antwort zur 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 einem Wiederherstellungsschlüssel anmelden: Führen Sie die folgenden Schritte aus, um sich mit einem Wiederherstellungsschlüssel anzumelden:
    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 Credential Manager an, wenn der Nutzer ein neues Gerät einrichtet. So kann sich der Nutzer ohne zusätzliche Eingaben anmelden.
    3. Antwort zum Abrufen 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 einen neuen Kontoregistrierungsprozess abschließt.

Um die Leistung zu optimieren und den Aufwand für das Erstellen oder Überprüfen von Wiederherstellungsanmeldedaten bei jeder 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 zur Erstellung von Anmeldedaten von Ihrem App-Server abrufen

Verwenden Sie eine FIDO-konforme Bibliothek auf Ihrem App-Server, 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 zur Erstellung des öffentlichen Schlüssels geparst haben, erstellen Sie einen Wiederherstellungsschlüssel, indem Sie diese Optionen in ein CreateRestoreCredentialRequest Objekt einfügen und die createCredential() Methode 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 zur Erstellung von Anmeldedaten im Format der Web Authentication API für PublicKeyCredentialCreationOptionsJSON.

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

      • true: (Empfohlen) Mit diesem Wert wird die Sicherung von Wiederherstellungsschlüsseln in der Cloud aktiviert, wenn der Nutzer die Google-Sicherung und die Ende-zu-Ende-Verschlüsselung, z. B. eine Displaysperre, aktiviert hat.
      • 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 Wiederherstellung aus der Cloud auswählt.

Antwort zur 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 der Anmeldedaten für den öffentlichen Schlüssel im JSON-Format.

Senden Sie den öffentlichen Schlüssel von 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 Erstellung von Passkeys 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.

Verarbeiten 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 auf true gesetzt ist, das Gerät des Nutzers aber keine Datensicherung oder Ende-zu-Ende-Verschlüsselung, z. B. eine Displaysperre, hat.
    Damit die Wiederherstellungsanmeldedaten in allen Fällen erstellt werden, müssen Sie die E2eeUnavailableException explizit verarbeiten, indem Sie createCredential aufrufen und isCloudBackupEnabled auf true setzen. Wenn E2eeUnavailableException ausgelöst wird, fangen Sie sie ab und rufen Sie createCredential noch einmal auf, wobei isCloudBackupEnabled auf false gesetzt ist.
  • IllegalArgumentException: Diese Ausnahme tritt auf, wenn createRestoreRequest leer oder kein gültiges JSON ist oder wenn es keine gültige user.id enthält, die den WebAuthn-Spezifikationen entspricht.

Mit einem Wiederherstellungsschlüssel anmelden

Verwenden Sie die Funktion „Anmeldedaten wiederherstellen“, 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 Passkeys für diesen Schritt finden Sie unter Mit einem Passkey anmelden. Weitere Informationen zur serverseitigen Implementierung finden Sie in der serverseitigen Authentifizierungsanleitung.

Wiederherstellungsschlüssel abrufen

Rufen Sie die Methode getCredential() für das CredentialManager-Objekt auf, um den Wiederherstellungsschlüssel auf dem neuen Gerät abzurufen.

Wir empfehlen, den Wiederherstellungsschlüssel in beiden folgenden Szenarien abzurufen:

  • Beim ersten Start der App auf dem Gerät. Die Wiederherstellung von Anmeldedaten ist in diesem Szenario 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 Funktion getCredential innerhalb des Callbacks onRestoreFinished ausführen. Verwenden Sie nicht die onRestore Methode, da sie nur für Sicherungen von Schlüssel-Wert-Paaren 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, und sie können mit der App interagieren, ohne warten zu müssen, bis sie Ihre App öffnen. So kann Ihre App dem Nutzer beispielsweise Benachrichtigungen senden, bevor er die App zum ersten Mal auf dem neuen Gerät öffnet. Das ist besonders relevant für Messaging- oder Kommunikations-Apps.
// 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. Die in dieser Antwort enthaltenen Anmeldedaten sind explizit vom Typ RestoreCredential und enthalten den öffentlichen Schlüssel.

Antwort auf die Anmeldung verarbeiten

Senden Sie den öffentlichen Schlüssel von der App an den Server der vertrauenden Partei, der dann verwendet werden kann, um den Nutzer anzumelden. Auf dem Server ähnelt diese Aktion der Anmeldung mit einem Passkey. Mit demselben Code, der die Anmeldung mit Passkeys auf dem Server verarbeitet, können auch Anmeldungen mit Wiederherstellungsschlüsseln verarbeitet werden. Weitere Informationen zu der serverseitigen Implementierung für 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 die Methode clearCredentialState() auf, um einen Wiederherstellungsschlüssel zu löschen. Löschen Sie den Schlüssel aus Sicherheitsgründen immer, 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 wieder anmelden muss.

Die Deinstallation einer App wird als Absicht interpretiert, den entsprechenden Wiederherstellungsschlüssel von diesem Gerät zu löschen, ähnlich der 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 Abmeldung des Nutzers 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)