Accettazione di documenti di identità da Google Wallet

Online

Gli ID digitali possono essere accettati sia nei flussi in-app sia in quelli web. Per accettare le credenziali da Google Wallet dovrai:

  1. Esegui l'integrazione tramite app o web seguendo le istruzioni fornite e
  2. Compila questo modulo per richiedere e accettare i Termini di servizio relativi all'accettazione delle credenziali da Google Wallet.

Prerequisiti

Per testare la visualizzazione degli ID, devi prima registrarti al programma beta pubblico utilizzando l'account di test previsto. Successivamente, fornisci i dettagli riportati al tuo contatto Google designato.

  • Link ai Termini di servizio
  • Logo
  • Sito web
  • ID pacchetto del Play Store (per le integrazioni di app per Android)
  • ID Gmail utilizzato per partecipare alla versione beta pubblica

Formati delle credenziali supportati

Esistono diversi standard proposti che definiscono il formato dei dati dei documenti di identità digitale, con due vantaggi significativi nel settore:

  1. mdocs: definito da ISO.
  2. Credenziali verificabili W3C: definite dal W3C.

Sebbene Gestore delle credenziali Android supporti entrambi i formati, al momento Google Wallet supporta solo gli ID digitali basati su mdoc.

Esperienza utente

Quando un'applicazione richiede attributi di identità, viene eseguita la seguente procedura:

  1. Rilevamento delle credenziali: l'applicazione esegue query sui portafogli disponibili per identificare le credenziali che possono soddisfare la richiesta. Android presenta quindi un selettore dell'interfaccia utente di sistema che mostra le informazioni da condividere. In questo modo l'utente può prendere una decisione informata su quale credenziale utilizzare.

  2. Selezione dell'utente e interazione con il wallet: l'utente seleziona una credenziale e Android richiama l'app wallet corrispondente per completare la transazione. L'app Wallet potrebbe mostrare una propria schermata di consenso o richiedere una conferma biometrica.

Risultato: se l'utente acconsente, le credenziali dell'identità selezionate vengono condivise con l'applicazione richiedente. Se l'utente rifiuta, viene restituito un errore.

Nell'app

Per richiedere le credenziali di identità dalle tue app per Android:

Aggiorna le dipendenze

Nel file build.gradle del tuo progetto, aggiorna le dipendenze per utilizzare Gestore delle credenziali (beta):

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

Configurare Gestore delle credenziali

Per configurare e inizializzare un oggetto CredentialManager, aggiungi una logica simile alla seguente:

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

Attributi riguardanti l'identità della richiesta

// 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, ...)

L'app chiamante fornisce tutti i parametri IdentityRequest come stringa JSON. Qui è rappresentato come il parametro requestMatcher di CredentialOption. Gestione delle credenziali non si occupa dei contenuti del file JSON. Questa richiesta json verrà passata direttamente ai wallet, che saranno poi responsabili dell'analisi e della decisione di quali credenziali possono soddisfare la richiesta. L'implementazione completa è disponibile nell'app di esempio.

Prevediamo che il W3C definirà questa richiesta JSON come componente dell'API web. Questa standardizzazione consentirà ai browser di trasmettere direttamente la richiesta ad Android.

Per darti un'idea del potenziale aspetto di questa richiesta, ecco un esempio di richiesta mdoc:

{
  "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="
}

La risposta restituisce un identityToken (stringa JSON), definito dal W3C. L'app Wallet è responsabile della creazione di questa risposta.

Esempio:

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

Invia il token ed elaboralo sul server

Una volta ricevuto l'identityToken, l'applicazione deve trasmetterlo al suo server di applicazioni per la verifica. Il passaggio iniziale prevede la decodifica del token dal formato base64. L'array di byte risultante rappresenta i dati CBOR, che rispettano la seguente CDDL.

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

Il passaggio successivo consiste nel calcolare il SessionTranscript da ISO/IEC 18013-5:2021 con una struttura di trasferimento specifica per Android:

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
]

Il cipherText viene criptato utilizzando la crittografia HPKE. Per decriptarlo, utilizza SessionTranscript come Dati autenticati aggiuntivi, insieme alla chiave privata EC generata in precedenza e alle seguenti impostazioni:

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

Il testo non cifrato risultante è costituito dai byte CBOR di DeviceResponse come definito in ISO/IEC 18013-5:2021. Il servizio DeviceResponse deve essere convalidato secondo lo standard ISO/IEC 18013-5:2021, clausola 9. Questo include diversi passaggi, come la verifica che il mdoc provenga da un emittente attendibile e che la risposta sia firmata dal dispositivo previsto. La classe DeviceResponseParser del progetto di credenziale OpenWallet Foundation Identity può essere utilizzata per questo processo di convalida.

Web

Per richiedere credenziali di identità utilizzando l'API Digital Credentials su Chrome, devi registrarti alla prova dell'origine dell'API Digital Credentials.

Di persona

Per accettare gli ID da Google Wallet sono necessari i seguenti passaggi:

  • Crea o acquista un lettore per accettare i documenti di identità come definiti dalla norma ISO 18013-5
  • Carica i certificati IACA nel lettore per assicurarti che gli ID accettati siano autentici
  • Testa la soluzione
  • Registra la tua applicazione con Google Wallet

Crea o acquista un lettore per accettare i documenti di identità come definiti dalla norma ISO 18013-5

Gli ID in Wallet sono implementati secondo lo standard ISO 18013-5 per le licenze di guida per dispositivi mobili. Utilizzano l'interazione basata su NFC o codice QR insieme al BLE come meccanismo di trasferimento dei dati, pertanto qualsiasi dispositivo in grado di implementare questi aspetti dello standard può fungere da lettore, anche un'applicazione mobile. Dato che lo standard è aperto, sul mercato sono disponibili diverse implementazioni di terze parti. Se necessario, puoi anche implementare la funzionalità direttamente.

Per indicazioni su come implementare autonomamente la funzionalità, consulta la nostra app di lettura di riferimento open source per Android, che implementa lo standard ISO e può accettare le patenti di guida digitali da Google Wallet.

Per iniziare, crea ed esegui l'app di lettura dei riferimenti:

  • Clona il repository delle app di riferimento
  • Apri il progetto in Android Studio
  • Compila ed esegui il target appverifier sul tuo dispositivo Android o nell'emulatore.

Carica i certificati IACA nel lettore per assicurarti che gli ID accettati siano autentici

Per convalidare una credenziale reale, devi avere un documento di identità nel portafoglio di un emittente supportato. Di seguito è riportato un elenco degli emittenti supportati da Google Wallet, insieme ai link ai relativi certificati per la verifica.

Testa la tua soluzione

Per testare la tua soluzione, compila ed esegui il nostro detentore di riferimento open source applicazione Android. Ecco i passaggi per creare ed eseguire l'app del proprietario di riferimento:

  • Clona il repository delle app di riferimento
  • Apri il progetto in Android Studio
  • Compila ed esegui il target appholder sul tuo dispositivo Android o nell'emulatore.

(Facoltativo) Registra la tua applicazione con Google Wallet

Registra la tua applicazione con Google Wallet compilando questo modulo.