Uso della libreria Portafoglio Di Microsoft Entra con ID verificato

2025-04-03

In questa esercitazione si apprenderà come un'app per dispositivi mobili può usare Microsoft Entra Wallet Library con ID verificato per rilasciare e presentare credenziali verificabili.

Prerequisiti

Android Studio installato in Mac/Windows e in un dispositivo di test Android. È necessario abilitare la modalità sviluppatore nel dispositivo di test Android.
Un account sviluppatore Apple, Mac con Xcode e un dispositivo di test iOS con la modalità sviluppatore abilitata. La versione di iOS deve essere almeno IOs 16.
Installa l'app lettore di codice QR sul dispositivo di test. L'app WalletLibraryDemo non è dotata della possibilità di analizzare i codici QR, quindi è necessaria l'app Lettore di Codici QR per analizzare i codici QR.

Non è necessario essere uno sviluppatore di dispositivi mobili per seguire questa esercitazione e rendere operativa l'app demo. Gli strumenti e un dispositivo di prova e il coraggio di provare è tutto ciò che serve. Non serve nemmeno un tenant ID verificato di Microsoft Entra per testare l'app demo con il nostro sito Web demo pubblico end-to-end.

Nota

Utilizzare la Wallet Library più recente disponibile per ottenere il supporto per la curva P-256 conforme a NIST, utilizzata da Verified ID a partire da febbraio 2024.

Che cos'è microsoft Entra Wallet Library?

Microsoft Entra Wallet Library per iOS e Android offre all'app per dispositivi mobili la possibilità di iniziare a usare la piattaforma ID verificato di Microsoft Entra. Usando la libreria portafoglio, l'app per dispositivi mobili usa la libreria portafoglio per rilasciare e presentare credenziali verificabili in conformità agli standard del settore.

Quando è consigliabile usare microsoft Entra Wallet Library?

Microsoft Authenticator ha tutte le funzionalità da usare come portafoglio per ID verificato di Microsoft Entra. Ma nei casi in cui non è possibile usare Microsoft Authenticator, la libreria portafoglio è l'alternativa. Un esempio può essere quando si ha già un'app per dispositivi mobili con cui gli utenti hanno familiarità e dove è più opportuno includere la tecnologia delle credenziali verificabili in questa app.

È possibile utilizzare Microsoft Authenticator e un'app mobile assieme utilizzando la libreria Wallet sullo stesso dispositivo mobile. Authenticator, se installato, è l'app che registra il gestore di protocolli per openid://, pertanto l'app deve garantire che le richieste di emissione e presentazione raggiungano l'app. L'uso di collegamenti diretti incorporati nelle pagine HTML che si basano sul protocollo openid:// avvia Microsoft Authenticator.

Microsoft usa Microsoft Entra Wallet Library?

Sì, la libreria portafoglio viene usata da Microsoft Authenticator. Alcune caratteristiche possono apparire prima nell'Autenticatore, ma è nostra ambizione renderle disponibili nella Libreria Portafoglio.

Qual è lo sforzo di aggiungere la "Microsoft Entra Wallet Library" alla tua app?

Aggiungi la Libreria Portafoglio al progetto dell'app per dispositivi mobili aggiungendo una dipendenza maven per Android e aggiungendo una dipendenza cocoapod per iOS.

Ios
Androide

Per iOS, aggiungere il pod WalletLibrary al podfile.

target "YourApp" do
  use_frameworks!
  pod "WalletLibrary", "~> 1.0.1"
end

Per Android, aggiungere alla build.gradle dell'app per aggiungere Wallet Library come dipendenza.

dependencies {
    implementation 'com.microsoft.entra.verifiedid:walletlibrary:1.0.0'
}

È quindi necessario aggiungere codice per elaborare le richieste. Per informazioni dettagliate, vedere il codice di esempio WalletLibraryDemo.

Ios
Androide

/// Create a verifiedIdClient.
let verifiedIdClient = VerifiedIdClientBuilder().build()

/// Create a VerifiedIdRequestInput using a OpenId Request Uri.
let input = VerifiedIdRequestURL(url: URL(string: "openid-vc://...")!)
let result = await verifiedIdClient.createRequest(from: input)

/// Every external method's return value is wrapped in a Result object to ensure proper error handling.
switch (result) {
case .success(let request):
    /// A request created from the method above could be an issuance or a presentation request. 
    /// In this example, it is a presentation request, so we can cast it to a VerifiedIdPresentationRequest.
    let presentationRequest = request as? VerifiedIdPresentationRequest
case .failure(let error):
    /// If an error occurs, its value can be accessed here.
    print(error)
}

// Create a verifiedIdClient
val verifiedIdClient = VerifiedIdClientBuilder(context).build()

// Create a VerifiedIdRequestInput using a OpenId Request Uri.
val verifiedIdRequestUrl = VerifiedIdRequestURL(Uri.parse("openid-vc://..."))
val verifiedIdRequestResult: Result<VerifiedIdRequest<*>> = verifiedIdClient.createRequest(verifiedIdRequestUrl)

// Every external method's return value is wrapped in a Result object to ensure proper error handling.
if (verifiedIdRequestResult.isSuccess) {
    val verifiedIdRequest = verifiedIdRequestResult.getOrNull()
    val presentationRequest = verifiedIdRequest?.let {
        verifiedIdRequest as VerifiedIdPresentationRequest
    }
} else {
    // If an exception occurs, its value can be accessed here.
    val exception = verifiedIdRequestResult.exceptionOrNull()
}

È quindi necessario gestire le attività principali seguenti nell'app.

Recupero degli URL della richiesta. La libreria Portafoglio non include alcuna funzionalità per la scansione di un codice QR o simile. Se vuoi fornire supporto per qualsiasi altra opzione non integrata nell'app, devi aggiungere queste funzionalità manualmente.
Archiviazione delle credenziali. La libreria Portafoglio crea la chiave pubblica e privata usata per firmare le risposte e le archivia nel dispositivo, ma non include alcuna funzionalità per l'archiviazione delle credenziali. È necessario gestire l'archiviazione delle credenziali per l'app per dispositivi mobili.
Interfaccia utente. È necessario implementare qualsiasi rappresentazione visiva delle credenziali archiviate e qualsiasi elemento dell'interfaccia utente destinato a guidare il processo di rilascio e presentazione.

App demo della libreria portafoglio

La libreria Wallet include un'app demo nel repository GitHub pronto per l'uso senza modifiche. È sufficiente compilarlo e distribuirlo. L'app demo è un'implementazione leggera e semplice che illustra il rilascio e la presentazione nel modo più essenziale. Per iniziare rapidamente, è possibile usare l'applicazione lettore di codici QR per scansionare il codice QR e quindi copiarlo e incollarlo nell'app demo.

Per testare l'app demo, è necessaria un'app Web che rilascia le credenziali e invia richieste di presentazione per le credenziali. "Woodgrove Public Demo Webapp è utilizzata a questo scopo in questo tutorial."

Compilazione dell'esempio Android

Nel computer per sviluppatori con Android Studio seguire questa procedura:

Scarica o clona il repository GitHub della libreria Android Wallet. Non hai bisogno della cartella della libreria portafoglio e puoi eliminarla se ti piace.
Avviare Android Studio e aprire la cartella padre di walletlibrarydemo
Selezionare Il menu Compila e quindi Crea progetto. Questo passaggio richiede del tempo.
Connettere il dispositivo di test Android tramite cavo USB al portatile
Selezionare il dispositivo di test in Android Studio e selezionare pulsante Esegui (triangolo verde)

Rilascio di credenziali con l'esempio Android

Avviare l'app WalletLibraryDemo
Sul portatile avviare il sito https://aka.ms/vcdemo Web demo pubblico ed eseguire le operazioni seguenti
1. Immettere il nome e il cognome e premere Avanti
2. Selezionare Verify with True Identity (Verifica con identità vera)
3. Selezionare Scatta un selfie e Carica un documento d'identità rilasciato dal governo. La demo usa dati simulati e non è necessario fornire un selfie reale o un ID.
4. Selezionare Avanti e OK
Scansiona il QR Code con l'app lettore di codici QR sul tuo dispositivo di test, quindi copia l'URL completo visualizzato nell'app. Ricordare il codice pin.
Passa di nuovo all'app WalletLibraryDemo e incolla l'URL dagli appunti.
Premere il pulsante CREATE REQUEST
Quando l'app scarica la richiesta, viene visualizzata una schermata simile all'esempio fornito. Selezionare il rettangolo bianco, ovvero una casella di testo, e immettere il codice pin visualizzato nella pagina del browser. Selezionare quindi il pulsante COMPLETA.
Al termine del rilascio, l'app demo visualizza le attestazioni nella credenziale

Presentazione delle credenziali con l'esempio Android

L'app di esempio contiene le credenziali rilasciate in memoria, quindi dopo il rilascio è possibile usarla per la presentazione.

Se hai emesso correttamente una credenziale, l'app WalletLibraryDemo dovrebbe visualizzare alcuni dettagli delle credenziali nella schermata iniziale.
Nella demo di Woodgrove nel browser, selezionare Ritorna a Woodgrove se non è già stato fatto e continuare con il passaggio 3 Accedi al portale personalizzato.
Scansionare il codice QR con l’app Lettore di codici QR sul dispositivo di test, quindi copiare l'URL completo sugli Appunti.
Torna all'app WalletLibraryDemo, incolla l'URL e quindi seleziona il pulsante CREATE REQUEST.
L'app recupera la richiesta di presentazione e visualizza le credenziali corrispondenti disponibili in memoria. In questo caso, ne hai solo uno. Clicca su di esso in modo che venga visualizzato il piccolo segno di spunta, quindi seleziona il pulsante COMPLETA per inviare la risposta della presentazione

Compilazione dell'esempio iOS

Nel computer per sviluppatori Mac con Xcode seguire questa procedura:

Scaricare o clonare il repository GitHub della libreria Portafoglio iOS.
Avviare Xcode e aprire la cartella di primo livello per WalletLibrary
Impostare il focus sul progetto WalletLibraryDemo

Screenshot di Xcode.
Modificare l'ID team impostando l'ID del team per sviluppatori Apple.
Selezionare il menu Prodotto e quindi Compila. Questo passaggio richiede del tempo.
Connettere il dispositivo di test iOS tramite cavo USB al portatile
Selezionare il dispositivo di test in Xcode
Selezionare il menu Prodotto e quindi Esegui o selezionare il triangolo 'Esegui'

Emissione di credenziali con l'esempio iOS

Avviare l'app WalletLibraryDemo
Sul portatile avviare il sito https://aka.ms/vcdemo Web demo pubblico ed eseguire le operazioni seguenti
1. Immettere il nome e il cognome e premere Avanti
2. Selezionare Verify with True Identity (Verifica con identità vera)
3. Selezionare Scatta un selfie e Carica un documento d'identità rilasciato dal governo. La demo usa dati simulati e non è necessario fornire un selfie reale o un ID.
4. Selezionare Avanti e OK
Scansiona il QR Code con l'app lettore di codici QR sul tuo dispositivo di test, quindi copia l'URL completo visualizzato nell'app. Ricordare il codice pin.
Passa di nuovo all'app WalletLibraryDemo e incolla l'URL dagli appunti.
Premere il pulsante Crea richiesta
Al termine del download della richiesta, l'app mostra una schermata simile all'esempio. Selezionare il testo Aggiungi pin per passare a una schermata in cui è possibile immettere il codice pin, quindi selezionare il pulsante Aggiungi per tornare alla schermata precedente e infine selezionare il pulsante Completa.
Al termine del rilascio, l'app demo visualizza le attestazioni nella credenziale.

Presentazione delle credenziali con l'esempio iOS