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

Voraussetzungen

Richten Sie einen Server für vertrauende Seiten 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.

Hinweis :Die serverseitige Implementierung ist für Passkeys und Wiederherstellungsschlüssel identisch. Ihre clientseitige App kann Wiederherstellungsschlüssel unterstützen, ohne Passkeys zu unterstützen. Da Wiederherstellungsschlüssel unabhängig von der Authentifizierungsmethode in Ihrer App funktionieren (z. B. Passwörter oder „Mit Google anmelden“), müssen Sie keine zusätzlichen Änderungen an den vorhandenen Authentifizierungsmethoden im Code Ihrer App vornehmen.

Abhängigkeiten

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

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

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

Hinweis :Die Funktion „Anmeldedaten wiederherstellen“ funktioniert unabhängig davon, ob allowBackup in manifest festgelegt ist.

Übersicht

1. Wiederherstellungsschlüssel erstellen: So erstellen Sie einen Wiederherstellungsschlüssel:
   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 der Nutzer 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

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

Hinweis :Ein Wiederherstellungsschlüssel ist an den eindeutigen Paketnamen einer Anwendung gebunden. Wenn die Haupt-App und die untergeordneten Apps Ihrer Organisation unterschiedliche Paketnamen haben, erstellen Sie für jede App einen separaten Wiederherstellungsschlüssel.

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.

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)

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 werden Sicherungsschlüssel in der Cloud gesichert, wenn der Nutzer Google-Back-up 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 Daten aus der Cloud wiederherstellt.
  Achtung: Es wird empfohlen, isCloudBackupEnabled auf true festzulegen. Wenn die Cloud-Sicherung deaktiviert ist und der Nutzer Daten aus einer Cloud-Sicherung wiederherstellt, schlägt der Aufruf zum Abrufen des Wiederherstellungsschlüssels fehl. Nutzer, die Ihre App mit einer Cloud-Sicherung wiederherstellen, erhalten den Wiederherstellungsschlüssel nicht und werden nicht automatisch angemeldet.

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 öffentliche 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.
• 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 „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 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.

Sie können den Wiederherstellungsschlüssel in den folgenden Fällen abrufen:

• Empfohlen: Unmittelbar nach der Wiederherstellung der App-Daten. Verwenden Sie BackupAgent, um die Sicherung Ihrer App zu konfigurieren und die getCredential-Funktionalität im onRestore-Callback zu vervollständigen, 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. Außerdem können Nutzer mit dem Gerät interagieren, ohne darauf warten zu müssen, dass sie Ihre App öffnen.
• Beim ersten Start der App auf dem Gerät.

Wenn Sie einem Nutzer Benachrichtigungen senden möchten, bevor er die App zum ersten Mal auf einem neuen Gerät öffnet, rufen Sie den Wiederherstellungsschlüssel im BackupAgent-Callback von onRestore ab. Das ist besonders bei Messaging- oder Kommunikations-Apps wichtig.

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

Die Credential Manager APIs geben eine Antwort vom Typ GetCredentialResponse zurück. Diese Antwort enthält den öffentlichen Schlüssel.

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.

Hinweis :Obwohl Wiederherstellungsschlüssel und Passkeys dieselbe zugrunde liegende Serverimplementierung verwenden, sollten Sie sie beim Speichern in der Datenbank Ihres App-Servers unterscheiden. Diese Unterscheidung ist wichtig, wenn eine Seite zur Verwaltung von Passkeys vorhanden ist, da Nutzer selbst erstellte Passkeys direkt verwalten können, während Wiederherstellungsschlüssel vom System verwaltet werden und auf der Seite zur Verwaltung von Passkeys ausgeblendet sind.

Wiederherstellungsschlüssel löschen

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

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