Von FIDO2 zum Credential Manager migrieren

Der Credential Manager unterstützt Passkeys, föderierte Anmeldung und Drittanbieter-Authentifizierung und ist die empfohlene API für die Authentifizierung unter Android. Er bietet eine sichere und bequeme Umgebung, in der Nutzer ihre Anmeldedaten synchronisieren und verwalten können. Entwickler, die lokale FIDO2-Anmeldedaten verwenden, sollten ihre App so aktualisieren, dass die Passkey-Authentifizierung unterstützt wird. Dazu müssen sie die Credential Manager API einbinden. In diesem Dokument wird beschrieben, wie Sie Ihr Projekt von FIDO2 zu Credential Manager migrieren.

Gründe für die Migration von FIDO2 zu Credential Manager

In den meisten Fällen sollten Sie den Authentifizierungsanbieter Ihrer Android-App zu Credential Manager migrieren. Gründe für die Migration zum Credential Manager:

  • Passkey-Unterstützung: Der Credential Manager unterstützt Passkeys, einen neuen, passwortlosen Authentifizierungsmechanismus, der sicherer und einfacher zu verwenden ist als Passwörter.
  • Mehrfachanmeldung: Der Credential Manager unterstützt mehrere Anmeldemethoden, darunter Passwörter, Passkeys und föderierte Anmeldemethoden. Dies erleichtert Nutzern die Authentifizierung bei Ihrer App, unabhängig von ihrer bevorzugten Authentifizierungsmethode.
  • Unterstützung von Drittanbietern von Anmeldedaten: Unter Android 14 und höher unterstützt der Credential Manager mehrere Drittanbieter von Anmeldedaten. Das bedeutet, dass sich Ihre Nutzer mit ihren vorhandenen Anmeldedaten von anderen Anbietern in Ihrer Anwendung anmelden können.
  • Konsistente Nutzererfahrung: Der Credential Manager bietet eine konsistentere Nutzererfahrung für die Authentifizierung über Apps und Anmeldemechanismen hinweg. So können Nutzer den Authentifizierungsablauf Ihrer App leichter verstehen und verwenden.

So migrieren Sie von FIDO2 zu Credential Manager:

Abhängigkeiten aktualisieren

  1. Aktualisieren Sie das Kotlin-Plug-in in der Datei „build.gradle“ Ihres Projekts auf Version 1.8.10 oder höher.

      plugins {
        //…
          id 'org.jetbrains.kotlin.android' version '1.8.10' apply false
        //…
      }
    
  2. Aktualisieren Sie in der build.gradle-Datei Ihres Projekts die Abhängigkeiten, um die aktuelle Versionen der Credential Manager- und Play-Dienste Authentication-Bibliotheken zu verwenden.

      dependencies {
        // ...
        // Credential Manager:
        implementation 'androidx.credentials:credentials:<latest-version>'
    
        // Play Services Authentication:
        // Optional - needed for credentials support from play services, for devices running
        // Android 13 and lower:
        implementation 'androidx.credentials:credentials-play-services-auth:<latest-version>'
        // ...
      }
    
  3. Ersetzen Sie die FIDO-Initialisierung durch die Credential Manager-Initialisierung. Fügen Sie diese Deklaration in der Klasse hinzu, die Sie für die Passkey-Erstellung und die Anmeldemethoden verwenden:

    val credMan = CredentialManager.create(context)
    

Passkeys erstellen

Sie müssen einen neuen Passkey erstellen, ihn mit dem Konto eines Nutzers verknüpfen und den öffentlichen Schlüssel des Passkeys auf Ihrem Server speichern, bevor sich der Nutzer damit anmelden kann. Aktualisieren Sie die Funktionsaufrufe für die Registrierung, um diese Funktion in Ihrer App einzurichten.

Abbildung 1. Diese Abbildung zeigt, wie Daten zwischen App und Server ausgetauscht werden, wenn ein Passkey mit dem Credential Manager erstellt wird.
  1. Wenn Sie die erforderlichen Parameter abrufen möchten, die während der Passkey-Erstellung an die Methode createCredential() gesendet werden, fügen Sie Ihrem registerRequest()-Serveraufruf name("residentKey").value("required") hinzu, wie in der WebAuthn-Spezifikation beschrieben.

    suspend fun registerRequest() {
        // ...
        val call = client.newCall(
            Builder()
                .method(
                    "POST",
                    jsonRequestBody {
                        name("attestation").value("none")
                        name("authenticatorSelection").objectValue {
                            name("residentKey").value("required")
                        }
                    }
                ).build()
        )
        // ...
    }
    
  2. Legen Sie den Typ return für registerRequest() und alle untergeordneten Funktionen auf JSONObject fest.

    suspend fun registerRequest(sessionId: String): ApiResult<JSONObject> {
        val call = client.newCall(
            Builder()
                .url("$BASE_URL/<your api url>")
                .addHeader("Cookie", formatCookie(sessionId))
                .method(
                    "POST",
                    jsonRequestBody {
                        name("attestation").value("none")
                        name("authenticatorSelection").objectValue {
                            name("authenticatorAttachment").value("platform")
                            name("userVerification").value("required")
                            name("residentKey").value("required")
                        }
                    }
                ).build()
        )
        val response = call.await()
        return response.result("Error calling the api") {
            parsePublicKeyCredentialCreationOptions(
                body ?: throw ApiException("Empty response from the api call")
            )
        }
    }
    
  3. Entfernen Sie alle Methoden, die Intent-Launcher- und Aktivitätsergebnisaufrufe verarbeiten, sicher aus Ihrer Ansicht.

  4. Da registerRequest() jetzt ein JSONObject zurückgibt, müssen Sie kein PendingIntent erstellen. Ersetzen Sie den zurückgegebenen Intent durch einen JSONObject. Aktualisieren Sie Ihre Intent-Launcher-Aufrufe, um createCredential() über die Credential Manager API aufzurufen. Rufen Sie die API-Methode createCredential() auf.

    suspend fun createPasskey(
        activity: Activity,
        requestResult: JSONObject
    ): CreatePublicKeyCredentialResponse? {
        val request = CreatePublicKeyCredentialRequest(requestResult.toString())
        var response: CreatePublicKeyCredentialResponse? = null
        try {
            response = credMan.createCredential(
                request = request as CreateCredentialRequest,
                context = activity
            ) as CreatePublicKeyCredentialResponse
        } catch (e: CreateCredentialException) {
    
            showErrorAlert(activity, e)
    
            return null
        }
        return response
    }
    
  5. Sobald der Aufruf erfolgreich ist, senden Sie die Antwort an den Server zurück. Die Anfrage und Antwort für diesen Aufruf ähneln der FIDO2-Implementierung, sodass keine Änderungen erforderlich sind.

Mit Passkeys authentifizieren

Nachdem Sie die Passkey-Erstellung eingerichtet haben, können Sie Ihre App so konfigurieren, dass sich Nutzer mit ihren Passkeys anmelden und authentifizieren können. Dazu aktualisieren Sie Ihren Authentifizierungscode, um die Ergebnisse des Credential Managers zu verarbeiten, und implementieren eine Funktion zur Authentifizierung über Passkeys.

Abbildung 2: Authentifizierungsablauf für Passkeys im Credential Manager.
  1. Der Aufruf der Anmeldeanfrage an den Server, um die erforderlichen Informationen für die getCredential()-Anfrage zu erhalten, ist mit der FIDO2-Implementierung identisch. Es sind keine Änderungen erforderlich.
  2. Ähnlich wie beim Aufruf der Registrierungsanfrage hat die zurückgegebene Antwort das JSONObject-Format.

    /**
     * @param sessionId The session ID to be used for the sign-in.
     * @param credentialId The credential ID of this device.
     * @return a JSON object.
     */
    suspend fun signinRequest(): ApiResult<JSONObject> {
        val call = client.newCall(
            Builder().url(
                buildString {
                    append("$BASE_URL/signinRequest")
                }
            ).method("POST", jsonRequestBody {})
                .build()
        )
        val response = call.await()
        return response.result("Error calling /signinRequest") {
            parsePublicKeyCredentialRequestOptions(
                body ?: throw ApiException("Empty response from /signinRequest")
            )
        }
    }
    
    /**
     * @param sessionId The session ID to be used for the sign-in.
     * @param response The JSONObject for signInResponse.
     * @param credentialId id/rawId.
     * @return A list of all the credentials registered on the server,
     * including the newly-registered one.
     */
    suspend fun signinResponse(
        sessionId: String,
        response: JSONObject,
        credentialId: String
    ): ApiResult<Unit> {
    
        val call = client.newCall(
            Builder().url("$BASE_URL/signinResponse")
                .addHeader("Cookie", formatCookie(sessionId))
                .method(
                    "POST",
                    jsonRequestBody {
                        name("id").value(credentialId)
                        name("type").value(PUBLIC_KEY.toString())
                        name("rawId").value(credentialId)
                        name("response").objectValue {
                            name("clientDataJSON").value(
                                response.getString("clientDataJSON")
                            )
                            name("authenticatorData").value(
                                response.getString("authenticatorData")
                            )
                            name("signature").value(
                                response.getString("signature")
                            )
                            name("userHandle").value(
                                response.getString("userHandle")
                            )
                        }
                    }
                ).build()
        )
        val apiResponse = call.await()
        return apiResponse.result("Error calling /signingResponse") {
        }
    }
    
  3. Entferne alle Methoden, die den Intent-Launcher und die Aufrufe von Aktivitätsergebnissen verarbeiten, sicher aus deiner Ansicht.

  4. Da signInRequest() jetzt ein JSONObject zurückgibt, müssen Sie kein PendingIntent erstellen. Ersetzen Sie den zurückgegebenen Intent durch einen JSONObject und rufen Sie getCredential() über Ihre API-Methoden auf.

    suspend fun getPasskey(
        activity: Activity,
        creationResult: JSONObject
    ): GetCredentialResponse? {
        Toast.makeText(
            activity,
            "Fetching previously stored credentials",
            Toast.LENGTH_SHORT
        )
            .show()
        var result: GetCredentialResponse? = null
        try {
            val request = GetCredentialRequest(
                listOf(
                    GetPublicKeyCredentialOption(
                        creationResult.toString(),
                        null
                    ),
                    GetPasswordOption()
                )
            )
            result = credMan.getCredential(activity, request)
            if (result.credential is PublicKeyCredential) {
                val publicKeycredential = result.credential as PublicKeyCredential
                Log.i("TAG", "Passkey ${publicKeycredential.authenticationResponseJson}")
                return result
            }
        } catch (e: Exception) {
            showErrorAlert(activity, e)
        }
        return result
    }
    
  5. Sobald der Aufruf erfolgreich ist, senden Sie die Antwort zur Validierung und Authentifizierung des Nutzers an den Server zurück. Die Anfrage- und Antwortparameter für diesen API-Aufruf ähneln der FIDO2-Implementierung, sodass keine Änderungen erforderlich sind.

Zusätzliche Ressourcen