Ausweise von Google Wallet akzeptieren

Online

Digitale IDs können sowohl In-App-Vorgänge als auch 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 Credential Manager unterstützt zwar beide Formate, Google Wallet unterstützt derzeit aber 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 zeigt möglicherweise einen eigenen Einwilligungsbildschirm an oder erfordert eine biometrische Bestätigung.

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-alpha05")
    // 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-alpha05")
}

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 = IdentityCredentialManager.Companion.getClient(context)

Attribute zur Identität anfordern

// Retrieves the user's digital identites from wallet apps for your app.
val getIdentityCredentialOption = GetDigitalCredentialOption(
    requestJson = requestJson, // this is what partners needs to set, example JSON specified below
)
val result = credentialManager.getCredential(request = GetCredentialRequest(credentialOptions, ...)

Der App-Caller stellt alle IdentityRequest-Parameter als JSON-String bereit. Hier wird er als requestMatcher-Parameter von CredentialOption dargestellt. Der Credential Manager kümmert sich nicht um den Inhalt dieser JSON-Datei. Diese JSON-Anfrage wird direkt an die Wallets übergeben, die dann für das Parsen und die Entscheidung verantwortlich sind, welche Anmeldedaten die Anfrage erfüllen können. Die vollständige Implementierung finden Sie in der Beispiel-App.

Wir gehen davon aus, dass das W3C diese JSON-Anfrage als Teil der Web API definiert. Durch diese Standardisierung können Browser die Anfrage direkt an Android senden.

Hier ein Beispiel für eine mdoc-Anfrage:

{
  "selector": {
    "format": [
      "mdoc"
    ],
    "doctype": "org.iso.18013.5.1.mDL",
    "fields": [
      {
        "namespace": "org.iso.18013.5.1",
        "name": "family_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "given_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "age_over_21",
        "intentToRetain": false
      }
    ]
  },
  "nonce": "3cydsUF9xNFyBDAAWOct09hEeSqrFX2WB2r0G6f8Ol0=",
  "readerPublicKey": "BApmGdElal2-1dtafsdHVRa1EpAWZfhlQj_iof2I8L3V8_dCK1gVR0_12E4ZSQ2LcqXRd4zxVeKEqU1wUSgGWUU="
}

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 erstellen 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 erstellen 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 mit dem Erstellen und Ausführen der Referenzlese-App beginnen:

  • Klonen Sie das Repository der Referenz-App.
  • Öffne das Projekt in Android Studio.
  • Erstellen Sie das appverifier-Ziel und führen Sie es auf Ihrem Android-Gerät oder Emulator 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.

Lösung testen

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.
  • Erstellen Sie das appholder-Ziel und führen Sie es auf Ihrem Android-Gerät oder Emulator aus.

Optional: Anwendung bei Google Wallet registrieren

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