De Microsoft Entra Wallet Library gebruiken met geverifieerde id

In deze zelfstudie leert u hoe een mobiele app de Microsoft Entra Wallet Library met geverifieerde id kan gebruiken om verifieerbare referenties te verlenen en te presenteren.

Vereisten

• Android Studio geïnstalleerd op Mac/Windows en een Android-testapparaat. U moet de ontwikkelaarsmodus inschakelen op uw Android-testapparaat.
• Een Apple-ontwikkelaarsaccount, Mac met Xcode en een iOS-testapparaat waarvoor de ontwikkelaarsmodus is ingeschakeld. De iOS-versie moet ten minste IOs 16 zijn.
• Installeer de QR Code Reader-app op uw testapparaat. De WalletLibraryDemo-app beschikt niet over de mogelijkheid om QR-codes te scannen, dus u hebt de app QR Code Reader nodig om de QR-codes te scannen.

U hoeft geen mobiele ontwikkelaar te zijn om deze zelfstudie te volgen en de demo-app aan de slag te laten gaan. De tools en een testapparaat en de moed om te proberen is alles wat u nodig hebt. U hebt ook geen Microsoft Entra geverifieerde ID tenant nodig, omdat u de demo-app kunt testen met onze openbare end-to-end demowebsite.

Notitie

Gebruik de nieuwste Wallet Library die beschikbaar is voor ondersteuning voor NIST-compatibele P-256-curve die wordt gebruikt door geverifieerde id sinds februari 2024.

Wat is de Microsoft Entra Wallet Library?

De Microsoft Entra Wallet Library voor iOS en Android biedt uw mobiele app de mogelijkheid om het Microsoft Entra geverifieerde ID-platform te gaan gebruiken. Met behulp van de Wallet Library gebruikt de mobiele app de Wallet Library voor het uitgeven en presenteren van verifieerbare referenties in overeenstemming met de industriestandaarden.

Wanneer moet ik de Microsoft Entra Wallet Library gebruiken?

Microsoft Authenticator heeft alle functionaliteit om te fungeren als de portemonnee voor Microsoft Entra geverifieerde ID. Maar in gevallen waarin u de Microsoft Authenticator niet kunt gebruiken, is de Wallet Library uw alternatief. Een voorbeeld hiervan kan zijn wanneer u al een mobiele app hebt waarmee uw gebruikers bekend zijn en waar het handiger is om verifieerbare referentietechnologie in deze app op te nemen.

U kunt Microsoft Authenticator en een mobiele app gebruiken met behulp van de Wallet Library naast elkaar op hetzelfde mobiele apparaat. Verificator, indien geïnstalleerd, is de app die de protocolhandler registreert voor openid://, dus uw app moet ervoor zorgen dat de uitgifte- en presentatieaanvragen uw app vinden. Gebruik van ingesloten dieptekoppelingen in HTML-pagina's die afhankelijk zijn van het openid://-protocol, start Microsoft Authenticator.

Maakt Microsoft gebruik van de Microsoft Entra Wallet Library?

Ja, de Wallet Library wordt gebruikt door de Microsoft Authenticator. Sommige functies kunnen eerst in de Authenticator worden weergegeven, maar het is onze ambitie om ze beschikbaar te maken in de Wallet Library.

Wat is de moeite om de Microsoft Entra Wallet Library toe te voegen aan mijn app?

U voegt de Wallet Library toe aan uw mobiele app-project via het toevoegen van een maven-afhankelijkheid voor Android en het toevoegen van een cocoapod-afhankelijkheid voor iOS.

iOS

Voor iOS voegt u de WalletLibrary-pod toe aan uw Podfile.

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

Android

Voor Android voegt u toe aan de build.gradle van uw app om Wallet Library toe te voegen als een afhankelijkheid.

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

Vervolgens moet u code toevoegen om de aanvragen te verwerken. Zie de voorbeeldcode WalletLibraryDemo voor meer informatie.

iOS

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

Android

// 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()
}

Vervolgens moet u de volgende belangrijke taken in uw app afhandelen.

• De aanvraag-URL's ophalen. De Wallet Library wordt niet geleverd met functionaliteit om een QR-code of vergelijkbare code te scannen. Als u ondersteuning wilt bieden voor andere opties die niet zijn ingebouwd in de app, moet u deze functies zelf toevoegen.
• De referenties opslaan. De Wallet Library maakt de persoonlijke en openbare sleutel die wordt gebruikt voor het ondertekenen van antwoorden en slaat deze op het apparaat op, maar deze wordt niet geleverd met functionaliteit voor het opslaan van referenties. U moet de opslag van referenties voor uw mobiele app beheren.
• Gebruikersinterface. U moet een visuele weergave van opgeslagen referenties en eventuele UI-elementen implementeren die bedoeld zijn om het uitgifte- en presentatieproces te stimuleren.

Demo-app voor portemonneebibliotheek

De Wallet Library wordt geleverd met een demo-app in de GitHub-opslagplaats die klaar is voor gebruik zonder wijzigingen. U hoeft het alleen maar te bouwen en te implementeren. De demo-app is een lichtgewicht en eenvoudige implementatie die de uitgifte en presentatie ten minste illustreert. Om snel aan de slag te gaan, kunt u de app QR Code Reader gebruiken om de QR-code te scannen en deze vervolgens te kopiëren en in de demo-app te plakken.

Als u de demo-app wilt testen, hebt u een web-app nodig waarmee referenties worden opgegeven en presentatieaanvragen voor referenties worden ingediend. De openbare demo-web-app woodgrove wordt gebruikt voor dit doel in deze zelfstudie.

Het Android-voorbeeld bouwen

Voer de volgende stappen uit op uw ontwikkelcomputer met Android Studio:

1. Download of kloon de GitHub-opslagplaats voor de Android Wallet Library. U hebt de map portemonneebibliotheek niet nodig en u kunt deze desgewenst verwijderen.

2. Start Android Studio en open de bovenliggende map van walletlibrarydemo

   

3. Selecteer het menu Opbouwen en vervolgens Project maken. Deze stap neemt enige tijd in beslag.

4. Verbind uw Android-testapparaat via een USB-kabel met uw laptop

5. Selecteer uw testapparaat in Android Studio en selecteer de knop Uitvoeren (groene driehoek)

Referenties uitgeven met behulp van het Android-voorbeeld

1. De App WalletLibraryDemo starten

   

2. Start op uw laptop de openbare demowebsite https://aka.ms/vcdemo en ga als volgt te werk

   1. Voer uw voornaam en achternaam in en druk op Volgende
   2. Verifiëren met true identity selecteren
   3. Selecteer Maak een selfie en Overheid uitgegeven IDuploaden. De demo maakt gebruik van gesimuleerde gegevens en u hoeft geen echte selfie of id op te geven.
   4. Selecteer Volgende en OK

3. Scan de QR-code met uw QR Code Reader-app op uw testapparaat en kopieer vervolgens de volledige URL die wordt weergegeven in de app QR Code Reader. Onthoud de pincode.

4. Ga terug naar de app WalletLibraryDemo en plak de URL van het klembord

5. Druk op de knop AANVRAAG MAKEN

6. Wanneer de app de aanvraag downloadt, wordt er een scherm weergegeven zoals in het voorbeeld. Selecteer in de witte rechthoek, een tekstvak, en voer de pincode in die wordt weergegeven op de browserpagina. Selecteer vervolgens de knop COMPLETE.

   

7. Zodra de uitgifte is voltooid, worden de claims in de referentie weergegeven in de demo-app

   

Referenties presenteren met behulp van het Android-voorbeeld

De voorbeeld-app bevat de uitgegeven referentie in het geheugen, dus na uitgifte kunt u deze gebruiken voor presentatie.

1. Als u met succes een identificatiebewijs hebt uitgegeven, zou de WalletLibraryDemo app enkele gegevens van het identificatiebewijs op het startscherm moeten weergeven.

   

2. Selecteer in de Woodgrove-demo in de browser Ga terug naar Woodgrove als u dit nog niet hebt gedaan en ga verder met stap 3 Toegang tot gepersonaliseerde portal.

3. Scan de QR-code met de app QR Code Reader op uw testapparaat en kopieer vervolgens de volledige URL naar het klembord.

4. Ga terug naar de app WalletLibraryDemo, plak de URL en selecteer de knop CREATE REQUEST.

5. De app haalt de presentatieaanvraag op en geeft de overeenkomende referenties weer die u in het geheugen hebt. In dit geval hebt u er maar één. klik erop zodat het kleine vinkje wordt weergegeven en selecteer vervolgens de knop VOLTOOIEN om het antwoord van de presentatie in te dienen

   

Het iOS-voorbeeld bouwen

Voer op uw Mac-ontwikkelcomputer met Xcode de volgende stappen uit:

1. Download of kloon de GitHub-opslagplaats voor de iOS Wallet Library.

2. Start Xcode en open de map op het hoogste niveau voor de WalletLibrary

3. Focus instellen op WalletLibraryDemo-project

   

4. Wijzig de team-id in uw Apple Developer Team ID.

5. Selecteer het menu Product en vervolgens Bouwen. Deze stap neemt enige tijd in beslag.

6. Sluit uw iOS-testapparaat via usb-kabel aan op uw laptop

7. Selecteer uw testapparaat in Xcode

8. Selecteer het menu Product en uitvoeren of selecteer op driehoek

Referenties uitgeven met behulp van het iOS-voorbeeld

1. De App WalletLibraryDemo starten

   

2. Start op uw laptop de openbare demowebsite https://aka.ms/vcdemo en ga als volgt te werk

   1. Voer uw voornaam en achternaam in en druk op Volgende
   2. Verifiëren met true identity selecteren
   3. Selecteer Maak een selfie en upload ID uitgegeven door de overheid. De demo maakt gebruik van gesimuleerde gegevens en u hoeft geen echte selfie of id op te geven.
   4. Selecteer Volgende en OK

3. Scan de QR-code met uw QR Code Reader-app op uw testapparaat en kopieer vervolgens de volledige URL die wordt weergegeven in de app QR Code Reader. Onthoud de pincode.

4. Ga terug naar de app WalletLibraryDemo en plak de URL van het klembord

5. Druk op de knop Aanvraag maken

6. Wanneer de app klaar is met het downloaden van de aanvraag, wordt er een scherm weergegeven zoals in ons voorbeeld. Selecteer op de Pin tekst toevoegen om naar een scherm te gaan waarin u de pincode kunt invoeren. Selecteer vervolgens knop toevoegen om terug te gaan en selecteer ten slotte de knop Voltooien.

   

7. Zodra de uitgifte is voltooid, worden de claims in de referentie weergegeven in de demo-app.

   

Referenties presenteren met behulp van het iOS-voorbeeld

De voorbeeld-app bevat de uitgegeven referentie in het geheugen, dus na uitgifte kunt u deze gebruiken voor presentatie.

1. Indien u met succes een bewijs hebt uitgegeven, wordt de naam van het bewijstype in de WalletLibraryDemo-app weergegeven op het startscherm.

   

2. Selecteer in de Woodgrove-demo in de browser Ga terug naar Woodgrove, als u dit nog niet hebt gedaan, en ga verder met stap 3 Toegang tot de gepersonaliseerde portal.

3. Scan de QR-code met de app QR Code Reader op uw testapparaat en kopieer vervolgens de volledige URL naar het klembord.

4. Ga terug naar de app WalletLibraryDemo, wis de vorige aanvraag uit het tekstvak, plak de URL en selecteer de knop Aanvraag maken

5. De app haalt de presentatieaanvraag op en geeft de overeenkomende referenties weer die u in het geheugen hebt. In dit geval hebt u er maar één. klik erop zodat het kleine vinkje van blauw naar groen wordt overgeschakeld en selecteer vervolgens de knop Voltooien om het presentatieantwoord te verzenden

   

Volgende stappen

Meer informatie over het configureren van uw tenant voor Microsoft Entra geverifieerde ID.