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 als Passkey in einem Anmeldedatenanbieter wie dem Google Passwortmanager gespeichert. Der öffentliche Schlüssel wird auf Ihrem App-Server gespeichert.
Vorbereitung
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 dieser Anleitung geht es hauptsächlich 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 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 abfangen, die bei der Erstellung von Passkeys 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.
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.7.0-alpha02") implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02") }
Groovy
dependencies { implementation "androidx.credentials:credentials:1.7.0-alpha02" implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02" }
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)
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 eine FIDO-kompatible Bibliothek auf Ihrem App-Server, 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 finden Sie unter Serverseitige Passkey-Registrierung.
Decodieren Sie in der Client-App die vom App-Server gesendeten Optionen zum Erstellen des öffentlichen Schlüssels. Diese werden in der Regel im JSON-Format dargestellt. Weitere Informationen zum Decodieren für Webclients finden Sie unter Codierung und Decodierung. Für 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 zum Erstellen ö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. Sie 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 integriert 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: Wird verwendet, um die Anforderungen für die Nutzerbestätigung während einer Passkey-Registrierung anzugeben. 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 Nutzerüberprüfung 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 UserVerification – 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.
Passkey erstellen
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 angibt, 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. Informationen zum Festlegen vonoriginfür Browser und ähnlich privilegierte Apps finden Sie unter Credential Manager-Aufrufe im Namen anderer Parteien für privilegierte Apps ausführen.isConditional: Dies ist ein optionales Feld, für das standardmäßigfalsefestgelegt ist. Weitere Informationen finden Sie unter Passkey automatisch erstellen.
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 Ansicht am unteren Rand nicht angezeigt und der Passkey wird automatisch erstellt.
Passkey automatisch erstellen
Sie können automatisch einen Passkey für einen Nutzer erstellen, nachdem er sich mit einem Passwort angemeldet hat. Dazu müssen Sie beim Erstellen eines Passkeys den Parameter isConditional in Ihrem CreatePublicKeyCredentialRequest auf true festlegen. Wenn der Nutzer noch keinen Passkey hat, versucht Ihre App automatisch, einen im Hintergrund zu erstellen und im Anmeldedatenanbieter des Nutzers zu speichern, z. B. im Google Passwortmanager. Ein Beispiel für die Implementierung finden Sie im öffentlichen Beispiel.
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}")
}
}
Ö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 des Public-Key-Anmeldedaten zu überprüfen, vergleichen Sie sie mit einer Zulassungsliste genehmigter Apps. Wenn ein Schlüssel einen unbekannten Ursprung hat, lehnen Sie ihn ab.
So rufen Sie den SHA‑256-Fingerabdruck der App ab:
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>Ermitteln Sie in der Antwort den SHA256-Fingerabdruck des Signaturzertifikats, der als
Certificate fingerprints block:SHA256angegeben ist.Codieren Sie den SHA256-Fingerabdruck mit der 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 das Debugging und die Veröffentlichung, oder mehrere Apps, wiederholen Sie den Vorgang und akzeptieren Sie alle Ursprünge als gültig auf dem App-Server.
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 Sicherheitswarnung 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
Wenn Sie Nutzern ermöglichen möchten, sich nahtlos auf einem neuen Gerät in ihren Konten anzumelden, implementieren Sie die Funktion Anmeldedaten wiederherstellen. Wenn Sie Anmeldedaten mit BackupAgent wiederherstellen, werden Nutzer angemeldet, wenn sie Ihre wiederhergestellte App auf einem neuen Gerät öffnen. So können sie Ihre App sofort verwenden.
Autofill für Felder mit 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 Nutzernamen und Passwort hinzu. Dadurch wird verhindert, dass sich die Autofill-Dialogfelder (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 entsprechenden Feldern für Nutzernamen 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" />