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

Vorbereitung

Richten Sie einen Relying Party-Server ein, der dem Server für Passkeys ähnelt. Wenn du bereits einen Server für die Authentifizierung mit Passkeys eingerichtet hast, verwende 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 zur Wiederherstellung von Anmeldedaten ist ab Version 1.5.0 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: So erstellen Sie einen Wiederherstellungsschlüssel:
    1. Credential Manager instanziieren: Erstellen Sie ein CredentialManager-Objekt.
    2. Optionen für die Erstellung von Anmeldedaten vom Anwendungsserver abrufen: Senden Sie der Client-App die Details, die zum Erstellen des Wiederherstellungsschlüssels von Ihrem Anwendungsserver erforderlich sind.
    3. Wiederherstellungsschlüssel erstellen: Erstelle einen Wiederherstellungsschlüssel für das Konto des Nutzers, wenn der Nutzer in deiner App angemeldet ist.
    4. Antwort auf die Erstellung von Anmeldedaten verarbeiten: Senden Sie die Anmeldedaten von Ihrer Client-App zur Verarbeitung an Ihren Anwendungsserver und behandeln Sie alle Ausnahmen.
  2. Mit einem Wiederherstellungsschlüssel anmelden: So melden Sie sich mit einem Wiederherstellungsschlüssel an:
    1. Optionen zum Abrufen von Anmeldedaten vom Anwendungsserver abrufen: Senden Sie der Client-App die Details, die zum Abrufen des Wiederherstellungsschlüssels von Ihrem Anwendungsserver erforderlich sind.
    2. Wiederherstellungsschlüssel abrufen: Fordern Sie den Wiederherstellungsschlüssel vom Credential Manager an, wenn der Nutzer ein neues Gerät einrichtet. So kann sich der Nutzer ohne zusätzliche Eingabe anmelden.
    3. Antwort auf den Abruf der 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 Fällen:

  • 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 ein neues Konto registriert.

Um die Leistung zu optimieren und den Aufwand für das Erstellen oder Prüfen von Wiederherstellungs-Anmeldedaten 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 für die Erstellung von Anmeldedaten vom Anwendungsserver abrufen

Verwenden Sie eine FIDO-konforme Bibliothek auf Ihrem Anwendungsserver, um Ihrer Client-App die Informationen zu senden, die zum Erstellen der Wiederherstellungs-Anmeldedaten erforderlich sind, z. B. Informationen zum Nutzer, zur App und zusätzliche Konfigurationseigenschaften. Weitere Informationen zur serverseitigen Implementierung finden Sie im Leitfaden für die serverseitige Implementierung.

Wiederherstellungsschlüssel erstellen

Nachdem Sie die vom Server gesendeten Optionen für die Erstellung des öffentlichen Schlüssels geparst haben, erstellen Sie einen Wiederherstellungsschlüssel. Dazu verpacken Sie diese Optionen in ein CreateRestoreCredentialRequest-Objekt und rufen die Methode createCredential() mit dem CredentialManager-Objekt auf.

// 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 Optionen für die Erstellung von Anmeldedaten, die vom Anwendungsserver im Format der Web Authentication API für PublicKeyCredentialCreationOptionsJSON gesendet werden.

    • isCloudBackupEnabled: Feld Boolean, um festzulegen, 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 Google Backup 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 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 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 Seite. Dieser öffentliche Schlüssel ähnelt dem öffentlichen Schlüssel, der beim Erstellen eines Passkeys generiert wird. Der gleiche Code, der die Passkey-Erstellung auf dem Server verarbeitet, kann auch die Erstellung des Wiederherstellungsschlüssels verarbeiten. Weitere Informationen zur serverseitigen Implementierung finden Sie im Leitfaden 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 den Wert true hat, das Gerät des Nutzers aber keine Datensicherung oder Ende-zu-Ende-Verschlüsselung wie eine Displaysperre hat.
    Damit in allen Fällen Anmeldedaten für die Wiederherstellung erstellt werden, müssen Sie E2eeUnavailableException explizit verarbeiten. Rufen Sie dazu createCredential auf und setzen Sie isCloudBackupEnabled auf true. Wenn E2eeUnavailableException ausgelöst wird, fangen Sie den Fehler 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 hat, die den WebAuthn-Spezifikationen entspricht.

Mit einem Wiederherstellungsschlüssel anmelden

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

Optionen zum Abrufen von Anmeldedaten vom Anwendungsserver 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

Wenn du den Wiederherstellungsschlüssel auf dem neuen Gerät abrufen möchtest, rufe die Methode getCredential() für das Objekt CredentialManager auf.

In den folgenden beiden Szenarien wird empfohlen, den Wiederherstellungsschlüssel 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 achten Sie darauf, dass Sie die getCredential-Funktion im onRestoreFinished-Callback ausführen. 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, und Nutzer können mit der App interagieren, ohne dass sie die App öffnen müssen. Beispielsweise kann Ihre App dem Nutzer 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 zuvor die Sicherung mit allowBackup="true" aktiviert hatten, legen Sie im Manifest Ihrer App den booleschen Wert android:fullBackupOnly="true" fest. So wird sichergestellt, dass das Sicherungs- und Wiederherstellungsverhalten Ihrer App 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 APIs des Anmeldedatenmanagers geben eine Antwort vom Typ GetCredentialResponse zurück. Der in dieser Antwort enthaltene Berechtigungsnachweis ist explizit vom Typ RestoreCredential, der den öffentlichen Schlüssel enthält.

Anmeldeantwort verarbeiten

Senden Sie den öffentlichen Schlüssel von der App an den Server der vertrauenden Seite, der dann zur Anmeldung des Nutzers verwendet werden kann. Auf der Serverseite ähnelt diese Aktion der Anmeldung mit einem Passkey. Der Code, der die Anmeldung mit Passkeys auf dem Server verarbeitet, kann auch für die Anmeldung mit Wiederherstellungsschlüsseln verwendet werden. Weitere Informationen zur serverseitigen Implementierung von Passkeys finden Sie unter Mit einem Passkey anmelden.

Wiederherstellungsschlüssel löschen

Der Credential Manager ist zustandslos und hat keine Informationen über 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. Löschen Sie den Schlüssel aus Sicherheitsgründen, wenn sich ein Nutzer abmeldet. So wird dafür gesorgt, dass der Nutzer beim nächsten Öffnen der App auf demselben Gerät abgemeldet ist und aufgefordert wird, sich wieder anzumelden.

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 Abmeldung des Nutzers im Code Ihrer App verarbeiten.

Wenn sich der Nutzer von Ihrer App abmeldet, rufen Sie die Methode clearCredentialState() für das Objekt CredentialManager 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)