Ausstellung von Anmeldedaten mit Ihrer Inhaber-App verarbeiten

Damit Ihre Inhaber-App Anmeldedaten von Ausstellern empfangen und speichern kann, muss sie die Ausstellungsabläufe verarbeiten können. Die Ausstellung von Berechtigungsnachweisen kann auf zwei Arten ausgelöst werden:

  • Vom Aussteller initiierter Ablauf: Der Nutzer löst eine Anfrage zum Ausstellen einer VDC über eine App oder Website des Ausstellers aus. Beispielsweise kann eine Website ihren Nutzern die Option „Reisepass zu Wallet hinzufügen“ anbieten. Der Aussteller ruft die Credential Manager Issuance API auf, um eine OpenID4VCI-Anfrage für ein Angebot von Anmeldedaten zu stellen. Um solche Anfragen zu verarbeiten, muss ein Inhaber zuerst den Credential Manager einbinden, um seine Metadaten zu registrieren. Der Credential Manager zeigt relevante Optionen an, die der Nutzer auswählen kann. Nachdem der Nutzer eine Inhaberoption ausgewählt hat, wird die Inhaber-App aufgerufen und kann die erforderlichen Schritte zum Abschließen der Ausstellung ausführen.
  • Vom Inhaber initiierter Ablauf: Der Nutzer fordert das Hinzufügen eines digitalen Ausweises über seine Inhaber-App an. Ein Inhaber kann beispielsweise die Schaltfläche „Reisepass hinzufügen“ anbieten. In diesem Fall verwaltet der Inhaber die Liste der unterstützten Aussteller und die Metadaten. Für diese Funktion ist keine Integration in den Android Credential Manager erforderlich.

Weitere Informationen zur Verwendung von Berechtigungsnachweisen mit der Holder API finden Sie unter Digitale Berechtigungsnachweise speichern.

Kompatibilität mit Android-Versionen

Die Holder API wird ab Android 6 (API-Level 23) unterstützt.

Implementierung

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

Groovy

dependencies {
    // Use to implement credentials registrys

    implementation "androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04"

}

Kotlin

dependencies {
    // Use to implement credentials registrys

    implementation("androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04")

}

RegistryManager erstellen

Erstellen Sie eine RegistryManager-Instanz und registrieren Sie eine RegisterCreationOptionsRequest-Anfrage dafür.

val registryManager = RegistryManager.create(context)

try {
    registryManager.registerCreationOptions(object :
        RegisterCreationOptionsRequest(
            creationOptions = buildIssuanceData(),
            matcher = loadIssuanceMatcher(),
            type = DigitalCredential.TYPE_DIGITAL_CREDENTIAL,
            id = "openid4vci",
        ) {}
    )
} catch (e: Exception) {
    Log.e(TAG, "Issuance registration failed.", e)
}

Der Matcher ist eine WebAssembly-Binärdatei (Wasm), die das bei der Registrierung festgelegte creationOptions-Set und das vom Aussteller gesendete Angebot für Ausweisdokumente empfängt, um die in der Credential Manager-Benutzeroberfläche angezeigten Einträge zu bestimmen. Ein Beispiel für einen Matcher finden Sie in der Open-Source-Beispiel-Wallet-App.

Ausstellungsanfrage verarbeiten

Als Nächstes muss die Wallet verarbeiten, wenn der Nutzer eine Option zum Erstellen von Ausweisen auswählt. Definieren Sie eine Aktivität, die auf den Intent-Filter androidx.credentials.registry.provider.action.CREATE_CREDENTIAL reagiert, wie in der Beispiel-Wallet gezeigt.

Der Intent, der die Aktivität startet, enthält die Erstellungsanfrage und den aufrufenden Ursprung, die Sie mit der Funktion PendingIntentHandler.retrieveProviderCreateCredentialRequest extrahieren können. Die API gibt ein ProviderCreateCredentialRequest-Objekt zurück, das alle Informationen zur Erstellungsanfrage enthält. Es gibt zwei Hauptkomponenten:

  • Die App, die die Anfrage gestellt hat. Sie können dies mit getCallingAppInfo abrufen.
  • Die Anfrage der aufrufenden App. Sie können diese mit getCallingRequest abrufen, wodurch ein CreateCredentialRequest zurückgegeben wird. Wenn die Anfrage für digitale Ausweise bestimmt ist, handelt es sich um eine Instanz von CreateDigitalCredentialRequest, die die JSON-Ausstellungsanfrage im Attribut requestJson enthält. Sie können sie mit dem folgenden Beispielcode verarbeiten:
val pendingIntentRequest =
    PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
val request = pendingIntentRequest!!.callingRequest
if (request is CreateDigitalCredentialRequest) {
    Log.i(TAG, "Got DC creation request: ${request.requestJson}")
    processCreationRequest(request.requestJson)
}

Schlüsselattestierung

Beachte Folgendes zur Schlüsselattestierung:

  • Beim Generieren einer Schlüsselattestierung verwenden Sie möglicherweise BigInteger.toByteArray, um die Schlüsselmaterialien beispielsweise in einen JSON-Webschlüssel zu konvertieren. Diese Methode kann manchmal ein Vorzeichenbyte hinzufügen und einen Validierungsfehler verursachen. Entfernen Sie in diesem Fall diese Byte, bevor Sie die Schlüsselattestierung an den Aussteller senden.
  • Wir empfehlen, android_key_attestation als Schlüsselprüftyp zu verwenden.

Erstellungsantwort zurückgeben

Sobald die Wallet die zum Speichern des Berechtigungsnachweises erforderlichen Schritte abgeschlossen hat, beenden Sie die Aktivität mit der Antwort des Berechtigungsnachweises:

val resultData = Intent()
PendingIntentHandler.setCreateCredentialResponse(
    resultData,
    CreateDigitalCredentialResponse(response.responseJson)
)
setResult(RESULT_OK, resultData)
finish()

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

val resultData = Intent()
PendingIntentHandler.setCreateCredentialException(
    resultData,
    CreateCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

Ein vollständiges Beispiel für die Rückgabe der Antwort mit den Anmeldedaten im Kontext finden Sie in der Beispiel-App.