Bevor sich Ihre Nutzer mit Passkeys authentifizieren können, muss Ihre App zuerst den Passkey für ihr Konto registrieren oder erstellen.
Um den Passkey zu erstellen, rufen Sie die erforderlichen Details von Ihrem App-Server ab und rufen Sie dann die Credential Manager API auf. Diese gibt ein öffentliches und privates Schlüsselpaar zurück. Der zurückgegebene private Schlüssel wird in einem Anmeldedatenanbieter wie dem Google Passwortmanager als Passkey gespeichert. Der öffentliche Schlüssel wird auf Ihrem App-Server gespeichert.
Voraussetzungen
Richten Sie Digital Asset Links ein und richten Sie Ihre App auf Geräte mit Android 9 (API‑Level 28) oder höher aus.
Übersicht
In diesem Leitfaden geht es um die Änderungen, die in Ihrer Client-App der vertrauenden Partei erforderlich sind, um einen Passkey zu erstellen. Außerdem wird die Implementierung des Servers der App der vertrauenden Partei kurz beschrieben. Weitere Informationen zur serverseitigen Integration finden Sie unter Serverseitige Passkey-Registrierung.
- Abhängigkeiten zu Ihrer App hinzufügen: Fügen Sie die erforderlichen Credential Manager-Bibliotheken hinzu.
- Credential Manager instanziieren: Erstellen Sie eine Credential Manager-Instanz.
- Optionen zum Erstellen von Anmeldedaten vom App-Server abrufen: Senden Sie von Ihrem App-Server die Details, die zum Erstellen des Passkeys erforderlich sind, an die Client-App, z. B. Informationen zur App, zum Nutzer sowie einen
challengeund andere Felder. - Passkey anfordern: Verwenden Sie in Ihrer App die vom App-Server empfangenen Details, um ein
GetPublicKeyCredentialOption-Objekt zu erstellen. Rufen Sie dann mit diesem Objekt die MethodecredentialManager.getCredential()auf, um einen Passkey zu erstellen. - Antwort auf die Passkey-Erstellung verarbeiten: Wenn Sie die Anmeldedaten in Ihrer Client-App erhalten, müssen Sie den öffentlichen Schlüssel codieren, serialisieren und dann an den App-Server senden. Sie müssen auch alle Ausnahmen behandeln, die bei der Passkey-Erstellung auftreten können.
- Öffentlichen Schlüssel auf dem Server bestätigen und speichern: Führen Sie die serverseitigen Schritte aus, um den Ursprung der Anmeldedaten zu bestätigen, und speichern Sie dann den öffentlichen Schlüssel.
- Nutzer benachrichtigen: Benachrichtigen Sie den Nutzer, dass sein Passkey erstellt wurde.
1. Abhängigkeiten zur App hinzufügen
Fügen Sie der Datei build.gradle Ihres App-Moduls die folgenden Abhängigkeiten hinzu:
Kotlin
dependencies { implementation("androidx.credentials:credentials:1.6.0-beta03") implementation("androidx.credentials:credentials-play-services-auth:1.6.0-beta03") }
Groovy
dependencies { implementation "androidx.credentials:credentials:1.6.0-beta03" implementation "androidx.credentials:credentials-play-services-auth:1.6.0-beta03" }
2. Credential Manager instanziieren
Erstellen Sie ein CredentialManager-Objekt mit Ihrer App oder Ihrem Aktivitätskontext.
// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)
3. Optionen zum Erstellen von Anmeldedaten von Ihrem App-Server abrufen
Wenn der Nutzer auf die Schaltfläche „Passkey erstellen“ klickt oder sich ein neuer Nutzer registriert, senden Sie eine Anfrage von Ihrer App an Ihren App-Server, um die Informationen abzurufen, die zum Starten der Passkey-Registrierung erforderlich sind.
Verwenden Sie auf Ihrem App-Server eine FIDO-kompatible Bibliothek, um Ihrer Client-App die Informationen zu senden, die zum Erstellen eines Passkeys erforderlich sind, z. B. Informationen zum Nutzer, zur App und zusätzliche Konfigurationseigenschaften. Weitere Informationen zur serverseitigen Passkey-Registrierung
Decodieren Sie in der Client-App die vom App-Server gesendeten Optionen zur Erstellung des öffentlichen Schlüssels. Diese werden in der Regel im JSON-Format dargestellt. Weitere Informationen dazu, wie die Decodierung für Webclients erfolgt, finden Sie unter Codierung und Decodierung. Bei Android-Client-Apps müssen Sie die Decodierung separat vornehmen.
Das folgende Snippet zeigt die Struktur der vom App-Server gesendeten Optionen zum Erstellen öffentlicher Schlüssel:
{
"challenge": "<base64url-encoded challenge>",
"rp": {
"name": "<relying party name>",
"id": "<relying party host name>"
},
"user": {
"id": "<base64url-encoded user ID>",
"name": "<user name>",
"displayName": "<user display name>"
},
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"attestation": "none",
"excludeCredentials": [
{
"id": "<base64url-encoded credential ID to exclude>",
"type": "public-key"
}
],
"authenticatorSelection": {
"requireResidentKey": true,
"residentKey": "required",
"userVerification": "required"
}
}
Zu den wichtigsten Feldern in den Optionen zur Erstellung öffentlicher Schlüssel gehören:
challenge: Ein vom Server generierter zufälliger String, der verwendet wird, um Replay-Angriffe zu verhindern.rp: Details zur App.rp.name: Der Name der App.rp.id: Die Domain oder Subdomain der App.
user: Details zum Nutzer.id: Die eindeutige ID des Nutzers. Dieser Wert darf keine personenidentifizierbaren Informationen wie E‑Mail-Adressen oder Nutzernamen enthalten. Sie können einen zufälligen 16‑Byte-Wert verwenden.name: Eine eindeutige Kennung für das Konto, das der Nutzer kennt, z. B. seine E-Mail-Adresse oder sein Nutzername. Dieser wird in der Kontoauswahl angezeigt. Wenn Sie einen Nutzernamen verwenden, verwenden Sie denselben Wert wie bei der Passwortauthentifizierung.displayName: Ein optionaler, nutzerfreundlicher Name für das Konto, der in der Kontoauswahl angezeigt werden soll.
authenticatorSelection: Details zum Gerät, das für die Authentifizierung verwendet wird.authenticatorAttachment: Gibt den bevorzugten Authenticator an. Folgende Werte sind möglich: –platform: Dieser Wert wird für einen Authentifikator verwendet, der in das Gerät des Nutzers eingebaut ist, z. B. ein Fingerabdrucksensor. –cross-platform: Dieser Wert wird für Roaming-Geräte wie Sicherheitsschlüssel verwendet. Sie wird normalerweise nicht im Kontext von Passkeys verwendet. – Nicht angegeben (empfohlen): Wenn Sie diesen Wert nicht angeben, können Nutzer Passkeys auf ihren bevorzugten Geräten erstellen. In den meisten Fällen ist es am besten, den Parameter nicht anzugeben.requireResidentKey: Wenn Sie einen Passkey erstellen möchten, legen Sie den Wert diesesBoolean-Felds auftruefest.residentKey: Wenn Sie einen Passkey erstellen möchten, legen Sie den Wert aufrequiredfest.userVerification: Hiermit werden die Anforderungen für die Nutzerbestätigung bei der Passkey-Registrierung angegeben. Die möglichen Werte sind: –preferred: Verwenden Sie diesen Wert, wenn Sie die Nutzerfreundlichkeit gegenüber dem Schutz priorisieren, z. B. in Umgebungen, in denen die Nutzerbestätigung mehr Probleme als Schutz verursacht. –required: Verwenden Sie diesen Wert, wenn eine auf dem Gerät verfügbare Methode zur Nutzerbestätigung aufgerufen werden muss. –discouraged: Verwenden Sie diesen Wert, wenn die Verwendung einer Methode zur Nutzerbestätigung nicht empfohlen wird.
Weitere Informationen zuuserVerificationfinden Sie unter Nutzerbestätigung – im Detail.
excludeCredentials: Listen Sie Anmeldedaten-IDs in einem Array auf, um die Erstellung eines doppelten Passkeys zu verhindern, wenn bereits einer mit demselben Anmeldedatenanbieter vorhanden ist.
4. Passkey anfordern
Nachdem Sie die Optionen zum Erstellen des serverseitigen öffentlichen Schlüssels geparst haben, erstellen Sie einen Passkey, indem Sie diese Optionen in ein CreatePublicKeyCredentialRequest-Objekt einfügen und createCredential() aufrufen.
Die createPublicKeyCredentialRequest enthält Folgendes:
requestJson: Die vom App-Server gesendeten Optionen zum Erstellen von Anmeldedaten.preferImmediatelyAvailableCredentials: Dies ist ein optionales boolesches Feld, das definiert, ob zum Ausführen der Anfrage nur lokal verfügbare oder vom Anmeldedatenanbieter synchronisierte Anmeldedaten verwendet werden sollen, anstatt Anmeldedaten von Sicherheitsschlüsseln oder hybriden Schlüsselabläufen. Folgende Verwendungen sind möglich:false(Standard): Verwenden Sie diesen Wert, wenn der Aufruf von Credential Manager durch eine explizite Nutzeraktion ausgelöst wurde.true: Verwenden Sie diesen Wert, wenn Credential Manager opportunistisch aufgerufen wird, z. B. beim ersten Öffnen der App.
Wenn Sie den Wert auftruefestlegen und keine sofort verfügbaren Anmeldedaten vorhanden sind, zeigt Credential Manager keine Benutzeroberfläche an und die Anfrage schlägt sofort fehl. Für „get“-Anfragen wird „NoCredentialException“ und für „create“-AnfragenCreateCredentialNoCreateOptionExceptionzurückgegeben.
origin: Dieses Feld wird automatisch für Android-Apps festgelegt. Für Browser und ähnlich privilegierte Apps, dieoriginfestlegen müssen, finden Sie weitere Informationen unter Credential Manager-Aufrufe im Namen anderer Parteien für privilegierte Apps ausführen.isConditional: Dies ist ein optionales Feld, das standardmäßig auffalsefestgelegt ist. Wenn Sie diese Option auftruefestlegen und ein Nutzer keinen Passkey hat, wird beim nächsten Mal, wenn er sich mit einem gespeicherten Passwort anmeldet, automatisch ein Passkey für ihn erstellt. Der Passkey wird im Anmeldedatenanbieter des Nutzers gespeichert. Für die Funktion zum bedingten Erstellen ist die aktuelle Version vonandroidx.credentialserforderlich.
Durch Aufrufen der Funktion createCredential() wird die integrierte Bottom-Sheet-Benutzeroberfläche von Credential Manager gestartet, in der der Nutzer aufgefordert wird, einen Passkey zu verwenden und einen Anmeldedatenanbieter und ein Konto für die Speicherung auszuwählen. Wenn isConditional jedoch auf true festgelegt ist, wird die Bottom-Sheet-Benutzeroberfläche nicht angezeigt und der Passkey wird automatisch erstellt.
5. Antwort verarbeiten
Nachdem der Nutzer über die Displaysperre des Geräts bestätigt wurde, wird ein Passkey erstellt und im ausgewählten Anmeldedatenanbieter des Nutzers gespeichert.
Die Antwort nach einem erfolgreichen Aufruf von createCredential() ist ein PublicKeyCredential-Objekt.
Die PublicKeyCredential sieht so aus:
{
"id": "<identifier>",
"type": "public-key",
"rawId": "<identifier>",
"response": {
"clientDataJSON": "<ArrayBuffer encoded object with the origin and signed challenge>",
"attestationObject": "<ArrayBuffer encoded object with the public key and other information.>"
},
"authenticatorAttachment": "platform"
}
Serialisieren Sie das Objekt in der Client-App und senden Sie es an den App-Server.
Fügen Sie Code hinzu, um Fehler zu verarbeiten, wie im folgenden Snippet gezeigt:
fun handleFailure(e: CreateCredentialException) {
when (e) {
is CreatePublicKeyCredentialDomException -> {
// Handle the passkey DOM errors thrown according to the
// WebAuthn spec.
}
is CreateCredentialCancellationException -> {
// The user intentionally canceled the operation and chose not
// to register the credential.
}
is CreateCredentialInterruptedException -> {
// Retry-able error. Consider retrying the call.
}
is CreateCredentialProviderConfigurationException -> {
// Your app is missing the provider configuration dependency.
// Most likely, you're missing the
// "credentials-play-services-auth" module.
}
is CreateCredentialCustomException -> {
// You have encountered an error from a 3rd-party SDK. If you
// make the API call with a request object that's a subclass of
// CreateCustomCredentialRequest using a 3rd-party SDK, then you
// should check for any custom exception type constants within
// that SDK to match with e.type. Otherwise, drop or log the
// exception.
}
else -> Log.w(TAG, "Unexpected exception type ${e::class.java.name}")
}
}
6. Öffentlichen Schlüssel auf dem App-Server prüfen und speichern
Auf dem App-Server müssen Sie die Anmeldedaten für den öffentlichen Schlüssel überprüfen und dann den öffentlichen Schlüssel speichern.
Um den Ursprung der Anmeldedaten für den öffentlichen Schlüssel zu überprüfen, vergleichen Sie sie mit einer Zulassungsliste genehmigter Apps. Wenn ein Schlüssel einen unbekannten Ursprung hat, lehnen Sie ihn ab.
So erhalten Sie den SHA256-Fingerabdruck der App:
Drucken Sie das Signaturzertifikat der Release-App, indem Sie den folgenden Befehl in einem Terminal ausführen:
keytool -list -keystore <path-to-apk-signing-keystore>Suchen Sie in der Antwort nach dem SHA256-Fingerabdruck des Signaturzertifikats, der als
Certificate fingerprints block:SHA256angegeben ist.Codieren Sie den SHA256-Fingerabdruck mit Base64url-Codierung. In diesem Python-Beispiel wird gezeigt, wie der Fingerabdruck richtig codiert wird:
import binascii import base64 fingerprint = '<SHA256 finerprint>' # your app's SHA256 fingerprint print(base64.urlsafe_b64encode(binascii.a2b_hex(fingerprint.replace(':', ''))).decode('utf8').replace('=', ''))Fügen Sie
android:apk-key-hash: am Anfang der Ausgabe aus dem vorherigen Schritt ein, sodass Sie etwas erhalten, das dem Folgenden ähnelt:android:apk-key-hash:<encoded SHA 256 fingerprint>Das Ergebnis muss mit einem zulässigen Ursprung auf Ihrem App-Server übereinstimmen. Wenn Sie mehrere Signaturzertifikate haben, z. B. Zertifikate für Debugging und Release, oder mehrere Apps, wiederholen Sie den Vorgang und akzeptieren Sie alle Ursprünge als gültig auf dem App-Server.
7. Nutzer benachrichtigen
Nachdem der Passkey erfolgreich erstellt wurde, benachrichtigen Sie Ihre Nutzer darüber und informieren Sie sie, dass sie ihre Passkeys über die App ihres Anmeldedatenanbieters oder in den App-Einstellungen verwalten können. Nutzer über ein benutzerdefiniertes Dialogfeld, eine Benachrichtigung oder eine Snackbar benachrichtigen. Da eine unerwartete Passkey-Erstellung durch eine böswillige Einheit einen sofortigen Sicherheitsalarm erfordert, sollten Sie diese In-App-Methoden durch externe Kommunikation wie eine E-Mail ergänzen.
Nutzererfahrung verbessern
Um die Nutzerfreundlichkeit bei der Implementierung der Registrierung mit Credential Manager zu verbessern, sollten Sie Funktionen zum Wiederherstellen von Anmeldedaten und zum Unterdrücken von Autofill-Dialogfeldern hinzufügen.
Funktion zum Wiederherstellen von Anmeldedaten auf einem neuen Gerät hinzufügen
Damit sich Nutzer auf einem neuen Gerät nahtlos in ihren Konten anmelden können, implementieren Sie die Funktion Anmeldedaten wiederherstellen. Wenn Sie Wiederherstellungsanmeldedaten mit BackupAgent hinzufügen, werden Nutzer angemeldet, wenn sie Ihre wiederhergestellte App auf einem neuen Gerät öffnen. So können sie Ihre App sofort verwenden.
Autofill in Feldern für Anmeldedaten unterdrücken (optional)
Fügen Sie für App-Bildschirme, auf denen Nutzer die Bottom-Sheet-Benutzeroberfläche von Credential Manager zur Authentifizierung verwenden sollen, das Attribut isCredential den Feldern für Nutzername und Passwort hinzu. Dadurch wird verhindert, dass sich die Dialogfelder zum automatischen Ausfüllen (FillDialog und SaveDialog) mit der Bottom-Sheet-Benutzeroberfläche von Credential Manager überschneiden.
Das Attribut isCredential wird unter Android 14 und höher unterstützt.
Das folgende Beispiel zeigt, wie Sie das Attribut isCredential den relevanten Feldern für Nutzername und Passwort in den relevanten Ansichten für Ihre App hinzufügen können:
<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:isCredential="true" />