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) ab Version 24220000 und der Bibliothek androidx.credentials ab Version 1.5.0.

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-alpha01")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha01"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha01"
}

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

Erstellen Sie den Wiederherstellungsschlüssel, nachdem sich der Nutzer in Ihrer App authentifiziert hat – entweder direkt nach der Anmeldung oder bei einem späteren Start der App, wenn er bereits angemeldet ist.

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 Anmeldedaten für die Wiederherstellung erforderlich sind, z. B. Informationen zum Nutzer, zur App und zusätzliche Konfigurationseigenschaften. Weitere Informationen zur serverseitigen Implementierung finden Sie in der Anleitung für die Serverseite.

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 Informationen zum Code

  • Das Objekt CreateRestoreCredentialRequest enthält die folgenden Felder:

    • requestJson: Die Optionen zur Erstellung von Anmeldedaten, die vom App-Server im Format der Web Authentication API für PublicKeyCredentialCreationOptionsJSON gesendet werden.

    • isCloudBackupEnabled: Boolean-Feld, um zu bestimmen, ob der Wiederherstellungsschlüssel in der Cloud gesichert werden soll. Standardmäßig ist dieses Flag auf true gesetzt. 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 eine Ende-zu-Ende-Verschlüsselung wie 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 beim Erstellen 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 wie eine Displaysperre hat.
  • 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.

Sie können den Wiederherstellungsschlüssel in den folgenden Szenarien abrufen:

  • (Empfohlen) Unmittelbar nach der Wiederherstellung der App-Daten. Konfigurieren Sie die Sicherung Ihrer App mit BackupAgent und vervollständigen Sie die getCredential Funktion im onRestore-Callback, damit die Anmeldedaten der App sofort nach der Wiederherstellung der App-Daten wiederhergestellt werden. So werden potenzielle Verzögerungen vermieden, wenn Nutzer ihr neues Gerät zum ersten Mal öffnen, und sie können interagieren, ohne warten zu müssen, bis sie Ihre App öffnen.
  • Beim ersten Start der App auf dem Gerät.

Wenn Sie Nutzern Notifications senden möchten, bevor sie die APP zum ersten Mal auf einem neuen Gerät öffnen, rufen Sie den Wiederherstellungsschlüssel im onRestore-Callback von BackupAgent ab. Dies ist besonders für Messaging- oder Kommunikations-Apps relevant.

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

Die Credential Manager APIs geben eine Antwort vom Typ GetCredentialResponse zurück. Diese Antwort enthält 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 der Serverseite ä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 ist und aufgefordert wird, sich noch einmal anzumelden.

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 Fällen 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)