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
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 //… }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>' // ... }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.
Wenn Sie die erforderlichen Parameter abrufen möchten, die während der Passkey-Erstellung an die Methode
createCredential()gesendet werden, fügen Sie IhremregisterRequest()-Serveraufrufname("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() ) // ... }Legen Sie den Typ
returnfürregisterRequest()und alle untergeordneten Funktionen aufJSONObjectfest.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") ) } }Entfernen Sie alle Methoden, die Intent-Launcher- und Aktivitätsergebnisaufrufe verarbeiten, sicher aus Ihrer Ansicht.
Da
registerRequest()jetzt einJSONObjectzurückgibt, müssen Sie keinPendingIntenterstellen. Ersetzen Sie den zurückgegebenen Intent durch einenJSONObject. Aktualisieren Sie Ihre Intent-Launcher-Aufrufe, umcreateCredential()über die Credential Manager API aufzurufen. Rufen Sie die API-MethodecreateCredential()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 }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.
- 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. Ä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") { } }Entferne alle Methoden, die den Intent-Launcher und die Aufrufe von Aktivitätsergebnissen verarbeiten, sicher aus deiner Ansicht.
Da
signInRequest()jetzt einJSONObjectzurückgibt, müssen Sie keinPendingIntenterstellen. Ersetzen Sie den zurückgegebenen Intent durch einenJSONObjectund rufen SiegetCredential()ü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 }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
- Beispielreferenz für den Credential Manager
- Codelab zum Credential Manager
- Nahtlose Authentifizierung in Ihren Apps mit Passkeys über die Credential Manager API
- FIDO2-Codelab