Ausweise von Google Wallet akzeptieren

Online

Digitale Ausweise können sowohl für In-App- als auch für Webabläufe akzeptiert werden. Wenn Sie Anmeldedaten von Google Wallet akzeptieren möchten, müssen Sie Folgendes tun:

  1. Führen Sie die Integration über die App oder das Web gemäß der Anleitung durch und
  2. Füllen Sie dieses Formular aus, um die Nutzungsbedingungen für die Annahme von Anmeldedaten von Google Wallet anzufordern und zu akzeptieren.

Vorbereitung

Wenn Sie die Vorlage von Ausweisen testen möchten, müssen Sie sich zuerst mit dem vorgesehenen Testkonto für das öffentliche Betaprogramm registrieren. Geben Sie anschließend die folgenden Details an Ihren zuständigen Google-Ansprechpartner weiter.

  • Link zu den Nutzungsbedingungen
  • Logo
  • Website
  • Play Store-Paket-ID (für Android-App-Integrationen)
  • Gmail-ID, mit der Sie an der öffentlichen Betaversion teilgenommen haben

Unterstützte Anmeldedatenformate

Es gibt mehrere vorgeschlagene Standards, die das Datenformat digitaler Ausweisdokumente definieren. Zwei davon gewinnen in der Branche zunehmend an Bedeutung:

  1. mdocs – von ISO definiert.
  2. W3C Verifiable Credentials: vom W3C definiert

Der Android-Anmeldedaten-Manager unterstützt beide Formate, Google Wallet unterstützt derzeit jedoch nur mdoc-basierte digitale Ausweise.

Nutzererfahrung

Wenn eine Anwendung Identitätsattribute anfordert, geschieht Folgendes:

  1. Anmeldedatensuche:Die Anwendung fragt verfügbare Wallets ab, um Anmeldedaten zu ermitteln, die der Anfrage entsprechen. Android zeigt dann eine Auswahl in der System-UI an, in der die freizugebenden Informationen angezeigt werden. So kann der Nutzer fundierte Entscheidungen darüber treffen, welche Anmeldedaten er verwenden möchte.

  2. Nutzerauswahl und Wallet-Interaktion:Der Nutzer wählt ein Anmeldedatensatz aus und Android ruft die entsprechende Wallet-App auf, um die Transaktion abzuschließen. Die Wallet-App kann einen eigenen Einwilligungsbildschirm anzeigen oder eine biometrische Bestätigung erfordern.

Ergebnis:Wenn der Nutzer zustimmt, werden die ausgewählten Anmeldedaten für die Identität mit der anfordernden Anwendung geteilt. Wenn der Nutzer ablehnt, wird ein Fehler zurückgegeben.

In-App

So fordern Sie Anmeldedaten für Ihre Identität von Ihren Android-Apps an:

Abhängigkeiten aktualisieren

Aktualisieren Sie in der Datei „build.gradle“ Ihres Projekts die Abhängigkeiten, um Credential Manager (Beta) zu verwenden:

dependencies {
    implementation("androidx.credentials:credentials:1.5.0-beta01")
    // optional - needed for credentials support from play services, for devices running Android 13 and below.
    implementation("androidx.credentials:credentials-play-services-auth:1.5.0-beta01")
}

Anmeldedaten-Manager konfigurieren

Fügen Sie zum Konfigurieren und Initialisieren eines CredentialManager-Objekts eine Logik wie die folgende hinzu:

// Use your app or activity context to instantiate a client instance of CredentialManager.
val credentialManager = CredentialManager.create(context)

Attribute zur Identität anfordern

Anstatt einzelne Parameter für Identitätsanfragen anzugeben, stellt die App sie alle zusammen als JSON-String innerhalb der CredentialOption bereit. Der Anmeldedaten-Manager gibt diesen JSON-String an die verfügbaren digitalen Brieftaschen weiter, ohne den Inhalt zu prüfen. Jedes Wallet ist dann für Folgendes verantwortlich: - JSON-String parsen, um die Identitätsanfrage zu verstehen – Feststellen, welche seiner gespeicherten Anmeldedaten (falls vorhanden) der Anfrage entsprechen.

Es wird erwartet, dass das W3C die Struktur dieser JSON-Anfrage als Teil der Web API-Spezifikation formal definiert. Beachten Sie jedoch, dass die Spezifikation in Form eines Entwurfs vorliegt und sich ändern kann.

Anfangs verwenden wir das Vorabprotokoll, um Ausweise von Google Wallet abzurufen. So können wir mit der Integration und den Tests beginnen, während die Web API-Spezifikation fertiggestellt wird.

Hier ein Beispiel für eine mdoc-requestJson für das Vorabprotokoll:

{
  identity: {
    providers: [{
      holder: {
        selector: {
          format: ['mdoc'],
          type: 'org.iso.18013.5.1.mDL',
          fields: [
            'org.iso.18013.5.1.family_name',
            'org.iso.18013.5.1.portrait',
          ]
        },
        params: {
          nonce: '1234',
          readerPublicKey: '<public_key>',
          extraParamAsNeededByWallets: true,
        },
      },
    }]
  }
}

// The request in the JSON format to conform with
// the JSON-ified Digital Credentials API request definition.
val requestJson = generateRequestFromServer()
val digitalCredentialOption =
    GetDigitalCredentialOption(requestJson = requestJson)

// Use the option from the previous step to build the `GetCredentialRequest`.
val getCredRequest = GetCredentialRequest(
    listOf(digitalCredentialOption)
)

coroutineScope.launch {
    try {
        val result = credentialManager.getCredential(
            context = activityContext,
            request = getCredRequest
        )
        verifyResult(result)
    } catch (e : GetCredentialException) {
        handleFailure(e)
    }
}

// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
    val credential = result.credential
    when (credential) {
        is DigitalCredential -> {
            val responseJson = credential.credentialJson
            validateResponseOnServer(responseJson)
        }
        else -> {
            // Catch any unrecognized credential type here.
            Log.e(TAG, "Unexpected type of credential ${credential.type}")
        }
    }
}

// Handle failure.
fun handleFailure(e: GetCredentialException) {
  when (e) {
        is GetCredentialCancellationException -> {
            // The user intentionally canceled the operation and chose not
            // to share the credential.
        }
        is GetCredentialInterruptedException -> {
            // Retry-able error. Consider retrying the call.
        }
        is NoCredentialException -> {
            // No credential was available.
        }
        is CreateCredentialUnknownException -> {
            // An unknown, usually unexpected, error has occurred. Check the
            // message error for any additional debugging information.
        }
        is CreateCredentialCustomException -> {
            // You have encountered a custom error thrown by the wallet.
            // If you made 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}")
    }
}

Die Antwort gibt ein vom W3C definiertes identityToken (JSON-String) zurück. Die Wallet App ist für die Erstellung dieser Antwort verantwortlich.

Beispiel:

{
    "token": "<base64 encoded response>"
}

Token senden und auf dem Server verarbeiten

Nach Erhalt des identityToken sollte Ihre Anwendung es zur Überprüfung an Ihren Anwendungsserver senden. Im ersten Schritt wird das Token aus dem Base64-Format decodiert. Das resultierende Byte-Array stellt die CBOR-Daten dar, die der folgenden CDDL entsprechen.

CredentialDocument = {
  "version": tstr,       // Set to "ANDROID-HPKE-v1"
  "pkEm": bstr,          // Public key, in uncompressed form
  "cipherText": bstr     // The encrypted data
}

Im nächsten Schritt wird das SessionTranscript aus ISO/IEC 18013-5:2021 mit einer Android-spezifischen Übergabestruktur berechnet:

SessionTranscript = [
  null,                // DeviceEngagementBytes not available
  null,                // EReaderKeyBytes not available
  AndroidHandover      // Defined below
]

AndroidHandover = [
  "AndroidHandoverv1", // Version number
  nonce,               // nonce that comes from request
  appId,               // RP package name
  pkRHash,             // The SHA256 hash of the recipient public key
]

Der cipherText wird mit der HPKE-Verschlüsselung verschlüsselt. Verwenden Sie zum Entschlüsseln SessionTranscript als zusätzliche authentifizierte Daten zusammen mit dem zuvor generierten EC-Privatschlüssel und den folgenden Einstellungen:

  • KEM: DHKEM(P-256, HKDF-SHA256)
  • KDF: HKDF-SHA256
  • AEAD: AES-128-GCM

Der resultierende Klartext sind die CBOR-Bytes der DeviceResponse gemäß ISO/IEC 18013-5:2021. DeviceResponse muss gemäß Paragraf 9 der ISO/IEC 18013-5:2021 validiert werden. Dazu sind mehrere Schritte erforderlich, z. B. die Überprüfung, ob der mdoc von einem vertrauenswürdigen Aussteller stammt und die Antwort vom vorgesehenen Gerät signiert wurde. Die Klasse DeviceResponseParser aus dem OpenWallet Foundation Identity Credential-Projekt kann für einen Teil dieses Validierungsprozesses verwendet werden.

Web

Wenn Sie in Chrome über die Digital Credentials API Anmeldedaten anfordern möchten, müssen Sie sich für den Ursprungstest der Digital Credentials API registrieren.

Vor Ort

So akzeptierst du Ausweise von Google Wallet:

  • Lesegerät entwickeln oder erwerben, um Ausweise gemäß ISO 18013-5 zu akzeptieren
  • Lade IACA-Zertifikate in das Lesegerät, um sicherzustellen, dass die akzeptierten Ausweise echt sind
  • Lösung testen
  • Anwendung bei Google Wallet registrieren

Lesegerät entwickeln oder erwerben, um Ausweise gemäß ISO 18013-5 zu akzeptieren

Ausweise in Wallet werden gemäß dem ISO 18013-5-Standard für digitale Führerscheine implementiert. Sie nutzen NFC-basiertes oder QR-Code-Engagement zusammen mit BLE als Datenübertragungsmechanismus, sodass jedes Gerät, das diese Aspekte des Standards implementieren kann, als Lesegerät dient, selbst bei mobilen Apps. Da der Standard offen ist, gibt es mehrere Implementierungen von Drittanbietern auf dem Markt. Die Funktion lässt sich bei Bedarf auch direkt implementieren.

Eine Anleitung dazu, wie du die Funktion selbst implementierst, findest du in der Android-App für Open-Source-Lesegeräte, die den ISO-Standard umsetzt und mDLs von Google Wallet akzeptiert.

Du kannst die App für das Referenzlesegerät erstellen und ausführen:

  • Klone das Repository der Referenz-App
  • Öffne das Projekt in Android Studio.
  • Erstelle das Ziel appverifier auf deinem Android-Gerät oder Emulator und führe es aus.

Lade IACA-Zertifikate in das Lesegerät, um sicherzustellen, dass die akzeptierten Ausweise echt sind

Für die Validierung echter Anmeldedaten ist ein Ausweis in Google Wallet von einem unterstützten Aussteller erforderlich. Unten findest du eine Liste der Aussteller, die von Google Wallet unterstützt werden, sowie Links zu ihren Zertifikaten zur Überprüfung.

Erstelle zum Testen deiner Lösung die Android-App für den Open-Source-Referenzinhaber und führe sie aus. So erstellen Sie die App für den Referenzinhaber und führen sie aus:

  • Klone das Repository der Referenz-App
  • Öffne das Projekt in Android Studio.
  • Erstelle das Ziel appholder auf deinem Android-Gerät oder Emulator und führe es aus.

Optional: Anwendung bei Google Wallet registrieren

Registriere deine Anwendung bei Google Wallet. Fülle dazu dieses Formular aus.