Online
I documenti di identità digitali possono essere accettati sia nei flussi in-app sia in quelli web. Per accettare le credenziali da Google Wallet, devi:
- Esegui l'integrazione tramite app o web seguendo le istruzioni fornite e
- 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 che seguono 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à digitali, di cui due stanno guadagnando una notevole trazione nel settore:
- mdocs: definito da ISO.
- 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:
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.
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 di 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
In build.gradle del progetto, aggiorna le dipendenze per utilizzare Gestore delle credenziali (beta):
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")
}
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 = CredentialManager.create(context)
Attributi riguardanti l'identità della richiesta
Invece di specificare singoli parametri per le richieste di identità, l'app li fornisce tutti insieme come stringa JSON all'interno di CredentialOption. Credential Manager trasmette questa stringa JSON ai portafogli digitali disponibili senza esaminarne i contenuti. Ogni wallet è quindi responsabile di: - analizzare la stringa JSON per comprendere la richiesta di identità. - Determinare quali delle credenziali memorizzate, se presenti, soddisfano la richiesta.
È previsto che il W3C definisca formalmente la struttura di questa richiesta JSON nell'ambito della specifica dell'API web. Tuttavia, è importante ricordare che la specifica è in forma di bozza ed è soggetta a modifiche.
Inizialmente, utilizzeremo il protocollo di anteprima per ottenere gli ID da Google Wallet. In questo modo possiamo iniziare l'integrazione e i test mentre la specifica dell'API web viene finalizzata.
Ecco un esempio di mdoc requestJson per il protocollo di anteprima:
{
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}")
}
}
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. DeviceResponse deve essere convalidato in base alla clausola 9 della norma ISO/IEC 18013-5:2021. Sono inclusi diversi passaggi, ad esempio la verifica che l'mdoc provenga da un emittente attendibile e che la risposta sia firmata dal dispositivo previsto. La classe DeviceResponseParser del progetto OpenWallet Foundation Identity Credential può essere utilizzata per parte di questa procedura di convalida.
Web
Per richiedere le credenziali di identità utilizzando l'API Digital Credentials su Chrome, dovrai registrarti per la prova dell'origine dell'API Digital Credentials.
Di persona
Per accettare gli ID da Google Wallet, devi seguire 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
I documenti di identità in Wallet sono implementati in base allo standard ISO 18013-5 per le patenti di guida su dispositivo mobile. 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. Poiché 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, puoi creare ed eseguire l'app di lettura dei riferimenti:
- Clona il repository delle app di riferimento
- Apri il progetto in Android Studio
- Compila ed esegui il target
appverifiersul 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.
- Arizona
- California
- Colorado
- Georgia
- Maryland
- Nuovo Messico #### Testare la soluzione
Per testare la tua soluzione, compila ed esegui la nostra applicazione Android di riferimento open source. 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
appholdersul tuo dispositivo Android o nell'emulatore.
(Facoltativo) Registra la tua applicazione con Google Wallet
Registra la tua applicazione con Google Wallet compilando questo modulo.