Credential Manager – Inhaber API

Mit der Credential Manager – Holder API können Android-Apps digitale Anmeldedaten verwalten und Prüfern präsentieren.

Erste Schritte

Wenn Sie die Credential Manager – Holder API verwenden möchten, fügen Sie dem Build-Skript Ihres App-Moduls die folgenden Abhängigkeiten hinzu:

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha01"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

Anmeldedaten beim Anmeldedaten-Manager registrieren

Für eine Wallet müssen Anmeldedaten-Metadaten registriert werden, damit Credential Manager sie filtern und in der Anmeldedatenauswahl anzeigen kann, wenn eine Anfrage eingeht.

Abbildung 1: Die Benutzeroberfläche für digitale Anmeldedaten.

Benutzeroberfläche für die Auswahl des Anmeldedaten-Managers

Das Format für diese Metadaten wird an ein RegisterCredentialsRequest übergeben. Erstellen Sie ein [RegistryManager][1] und registrieren Sie die Anmeldedaten:

In diesem Beispiel werden die Metadaten aus einer Datenbank mit Anmeldedateneinträgen zusammengestellt. In unserem Beispiel-Wallet finden Sie einen Verweis, mit dem die Metadaten beim Laden der App registriert werden. In Zukunft wird die Zusammensetzung der Anmeldedatenbank von der Jetpack API unterstützt. An diesem Punkt können Sie die Anmeldedaten-Metadaten als wohldefinierte Datenstrukturen registrieren.

Die Registrierung bleibt auch nach Neustarts des Geräts erhalten. Wenn Sie dasselbe Register mit derselben ID und demselben Typ noch einmal registrieren, wird der vorherige Registrierungseintrag überschrieben. Daher müssen Sie sich nur dann neu registrieren, wenn sich Ihre Anmeldedaten geändert haben.

Optional: Matcher erstellen

Credential Manager ist protokollunabhängig. Die Metadatenregistrierung wird als undurchsichtiger Blob behandelt und ihr Inhalt wird nicht überprüft. Daher muss die Wallet einen Matcher bereitstellen, ein ausführbares Binärprogramm, das die eigenen Daten der Wallet verarbeiten und die Anzeigemetadaten auf Grundlage einer eingehenden Anfrage generieren kann. Credential Manager führt den Abgleich in einer Sandbox-Umgebung ohne Netzwerk- oder Festplattenzugriff aus, damit nichts an ein Wallet weitergegeben wird, bevor die Benutzeroberfläche für den Nutzer gerendert wird.

Die Credential Manager API bietet Matcher für gängige Protokolle, derzeit OpenID4VP. Er ist noch nicht offiziell veröffentlicht. Verwenden Sie daher vorerst unseren Beispiel-Matcher für das OpenID4VP-Protokoll.

Mit ausgewählten Anmeldedaten arbeiten

Als Nächstes muss die Wallet darauf reagieren, wenn ein Nutzer Anmeldedaten auswählt. Sie können eine Aktivität definieren, die auf den Intent-Filter androidx.credentials.registry.provider.action.GET_CREDENTIAL wartet. In unserem Beispiel-Wallet wird dieses Verfahren veranschaulicht.

Der Intent, mit dem die Aktivität gestartet wird, enthält die Prüferanfrage und den Aufruferursprung, die mit der Funktion PendingIntentHandler.retrieveProviderGetCredentialRequest extrahiert werden können. Die API gibt ein ProviderGetCredentialRequest mit allen Informationen zurück, die mit der angegebenen Anfrage des Prüfers verknüpft sind. Es gibt drei Hauptkomponenten:

• Die App, die die Anfrage gestellt hat. Sie können sie mit getCallingAppInfo abrufen.
• Die ausgewählten Anmeldedaten. Über die Erweiterungsmethode selectedEntryId können Sie Informationen dazu abrufen, welchen Kandidaten der Nutzer ausgewählt hat. Dies entspricht der von Ihnen registrierten Anmeldedaten-ID.
• Alle spezifischen Anfragen des Prüfers. Sie können sie mit der Methode getCredentialOptions abrufen. In diesem Fall sollte in dieser Liste ein GetDigitalCredentialOption mit der Anfrage für digitale Berechtigungsnachweise enthalten sein.

In den meisten Fällen stellt der Prüfer eine Anfrage zur Präsentation digitaler Anmeldedaten, die Sie mit dem folgenden Beispielcode verarbeiten können:

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

Ein Beispiel hierfür finden Sie in unserem Beispiel-Wallet.

Wallet-Benutzeroberfläche rendern

Sobald die Anmeldedaten ausgewählt wurden, wird das Wallet aufgerufen und der Nutzer wird durch die Benutzeroberfläche geleitet. Im Beispiel ist dies ein biometrischer Prompt.

Anmeldedatenantwort zurückgeben

Sobald die Wallet bereit ist, das Ergebnis zurückzusenden, können Sie dies tun, indem Sie die Aktivität mit der Anmeldedatenantwort abschließen:

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

Wenn es eine Ausnahme gibt, können Sie die Ausnahme für Anmeldedaten auf ähnliche Weise senden:

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

Ein Beispiel dafür, wie die Anmeldedatenantwort im Kontext zurückgegeben wird, finden Sie in der Beispiel-App.