Använda Microsoft Entra-plånboksbiblioteket med verifierat ID

I den här självstudien får du lära dig hur en mobilapp kan använda Microsoft Entra Wallet Library med verifierat ID för att utfärda och presentera verifierbara autentiseringsuppgifter.

Förutsättningar

• Android Studio installerat på Mac/Windows och en Android-testenhet. Du måste aktivera utvecklarläge på android-testenheten.
• Ett Apple-utvecklarkonto, Mac med Xcode och en iOS-testenhet med utvecklarläge aktiverat. IOS-versionen måste vara 16 och senare.
• Installera QR Code Reader-appen på testenheten. Appen WalletLibraryDemo har inte möjlighet att skanna QR-koder, så du behöver QR Code Reader-appen för att skanna QR-koderna med.

Du behöver inte vara mobilutvecklare för att följa den här självstudien och få igång demoappen. Verktygen och en testenhet och modet att prova är allt du behöver. Du behöver inte heller en Microsoft Entra – verifierat ID klientorganisation registrerad eftersom du kan testa demoappen med vår offentliga demowebbplats från slutpunkt till slutpunkt.

Kommentar

Använd det senaste tillgängliga plånboksbiblioteket för att få stöd för NIST-kompatibel P-256-kurva som använts av verifierat ID sedan februari 2024.

Vad är Microsoft Entra Wallet Library?

Microsoft Entra Wallet Library för iOS och Android ger din mobilapp möjlighet att börja använda Microsoft Entra – verifierat ID-plattformen. Med hjälp av plånboksbiblioteket kan din mobilapp utfärda och presentera verifierbara autentiseringsuppgifter i enlighet med branschstandarder.

När ska jag använda Microsoft Entra-plånboksbiblioteket?

Microsoft Authenticator har alla funktioner för att fungera som plånbok för Microsoft Entra – verifierat ID. Men i de fall där du inte kan använda Microsoft Authenticator är plånboksbiblioteket ditt alternativ. Ett exempel kan vara när du redan har en mobilapp som användarna är bekanta med och där det är mer meningsfullt att inkludera verifierbar teknik för autentiseringsuppgifter i den här appen.

Du kan använda Microsoft Authenticator och en mobilapp med hjälp av Plånboksbiblioteket sida vid sida på samma mobila enhet. Om authenticatorn installeras är den app som har registrerat protokollhanteraren för openid://, så din app måste se till att utfärdande- och presentationsbegäranden hittar din app. Användning av inbäddade djuplänkar på HTML-sidor som förlitar sig på openid://-protokollet resulterar i att Microsoft Authenticator startas.

Använder Microsoft Microsoft Entra Wallet Library?

Ja, plånboksbiblioteket används av Microsoft Authenticator. Vissa funktioner kan visas i Authenticator först, men det är vår ambition att göra dem tillgängliga i plånboksbiblioteket.

Vad är det för arbete med att lägga till Microsoft Entra Wallet Library i min app?

Du lägger till plånboksbiblioteket i ditt mobilappsprojekt genom att lägga till ett maven-beroende för Android och lägga till ett cocoapod-beroende för iOS.

iOS

För iOS lägger du till WalletLibrary-podden i podden.

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

Android

För Android lägger du till i appens build.gradle för att lägga till Plånboksbibliotek som ett beroende.

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

Sedan måste du lägga till kod för att bearbeta begäranden. Mer information finns i exempelkoden WalletLibraryDemo.

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

Sedan måste du hantera följande viktiga uppgifter i din app.

• Hämta url:erna för begäran. Plånboksbiblioteket har inga funktioner för att skanna en QR-kod eller liknande. Du måste lägga till att hämta begärande-URL:en via metoder som att skanna en QR-kod.
• Lagra autentiseringsuppgifterna. Plånboksbiblioteket skapar den privata och offentliga nyckeln som används för signeringssvar och lagrar den på enheten, men den har inga funktioner för lagring av autentiseringsuppgifter. Du måste hantera lagring av autentiseringsuppgifter för din mobilapp.
• Användargränssnitt. En visuell representation av lagrade autentiseringsuppgifter och användargränssnittet för att driva utfärdande- och presentationsprocessen måste implementeras av dig.

Demoapp för plånboksbibliotek

Plånboksbiblioteket levereras med en demoapp på GitHub-lagringsplatsen som är redo att användas utan några ändringar. Du behöver bara skapa och distribuera den. Demoappen är en enkel och enkel implementering som illustrerar utfärdande och presentation som minst. För att snabbt komma igång kan du använda QR Code Reader-appen för att skanna QR-koden och sedan kopiera och klistra in den i demoappen.

För att kunna testa demoappen behöver du en webbapp som utfärdar autentiseringsuppgifter och gör presentationsbegäranden för autentiseringsuppgifter. Den offentliga demowebbappen Woodgrove används för detta ändamål i den här självstudien.

Skapa Android-exemplet

Gör följande på utvecklardatorn med Android Studio:

1. Ladda ned eller klona GitHub-lagringsplatsen för Android Wallet Library. Du behöver inte mappen walletlibrary och du kan ta bort den om du vill.

2. Starta Android Studio och öppna den överordnade mappen för walletlibrarydemo

   

3. Välj Skapa-menyn och sedan Skapa projekt. Det här steget tar lite tid.

4. Anslut Android-testenheten via USB-kabel till din bärbara dator

5. Välj testenheten i Android Studio och klicka på knappen Kör (grön triangel)

Utfärda autentiseringsuppgifter med androidexemplet

1. Starta appen WalletLibraryDemo

   

2. Starta den offentliga demowebbplatsen https://aka.ms/vcdemo på din bärbara dator och gör följande

   1. Ange ditt förnamn och efternamn och tryck på Nästa
   2. Välj Verifiera med sann identitet
   3. Klicka på Ta en selfie och Ladda upp myndighets utfärdat ID. Demonstrationen använder simulerade data och du behöver inte ange en riktig selfie eller ett ID.
   4. Klicka på Nästa och OK

3. Skanna QR-koden med QR Code Reader-appen på testenheten och kopiera sedan den fullständiga URL:en som visas i QR Code Reader-appen. Kom ihåg pin-koden.

4. Växla tillbaka till Appen WalletLibraryDemo och klistra in URL:en från Urklipp

5. Tryck på knappen CREATE REQUEST (SKAPA BEGÄRAN)

6. När appen har laddat ned begäran visas en skärm som nedan. Klicka på den vita rektangeln, som är en textruta, och ange den pin-kod som visas på webbläsarsidan. Klicka sedan på knappen SLUTFÖR .

   

7. När utfärdandet är klart visar demoappen anspråken i autentiseringsuppgifterna

   

Presentera autentiseringsuppgifter med androidexemplet

Exempelappen innehåller de utfärdade autentiseringsuppgifterna i minnet, så efter utfärdandet kan du använda den för presentation.

1. Appen WalletLibraryDemo bör visa viss information om autentiseringsuppgifter på startskärmen om du har utfärdat en autentiseringsuppgift.

   

2. I Woodgrove-demonstrationen i webbläsaren klickar du på Återgå till Woodgrove om du inte redan har gjort det och fortsätter med steg 3 Åtkomst till anpassad portal.

3. Skanna QR-koden med QR Code Reader-appen på testenheten och kopiera sedan den fullständiga URL:en till Urklipp.

4. Växla tillbaka till appen WalletLibraryDemo och klistra in url:en och klicka på knappen SKAPA BEGÄRAN

5. Appen hämtar presentationsbegäran och visar de matchande autentiseringsuppgifterna som du har i minnet. I det här fallet har du bara en. Klicka på den så att den lilla bockmarkeringen visas och klicka sedan på knappen SLUTFÖR för att skicka presentationssvaret

   

Skapa iOS-exemplet

Gör följande på din Mac-utvecklardator med Xcode:

1. Ladda ned eller klona GitHub-lagringsplatsen för iOS-plånboksbiblioteket.

2. Starta Xcode och öppna mappen på den översta nivån för WalletLibrary

3. Ställ in fokus på WalletLibraryDemo-projekt

   

4. Ändra team-ID till ditt Apple Developer Team-ID.

5. Välj Produkt-menyn och sedan Skapa. Det här steget tar lite tid.

6. Anslut din iOS-testenhet via USB-kabel till din bärbara dator

7. Välj testenheten i Xcode

8. Välj Produkt-menyn och sedan Kör eller klicka på run triangle

Utfärda autentiseringsuppgifter med iOS-exemplet

1. Starta appen WalletLibraryDemo

   

2. Starta den offentliga demowebbplatsen https://aka.ms/vcdemo på din bärbara dator och gör följande

   1. Ange ditt förnamn och efternamn och tryck på Nästa
   2. Välj Verifiera med sann identitet
   3. Klicka på Ta en selfie och Ladda upp myndighets utfärdat ID. Demonstrationen använder simulerade data och du behöver inte ange en riktig selfie eller ett ID.
   4. Klicka på Nästa och OK

3. Skanna QR-koden med QR Code Reader-appen på testenheten och kopiera sedan den fullständiga URL:en som visas i QR Code Reader-appen. Kom ihåg pin-koden.

4. Växla tillbaka till Appen WalletLibraryDemo och klistra in URL:en från Urklipp

5. Tryck på knappen Skapa begäran

6. När appen har laddat ned begäran visas en skärm som nedan. Klicka på Lägg till pin-text för att gå till en skärm där du kan mata in pin-koden, klicka på knappen Lägg till för att komma tillbaka och klicka slutligen på knappen Slutför .

   

7. När utfärdandet är klart visar demoappen anspråken i autentiseringsuppgifterna.

   

Presentera autentiseringsuppgifter med iOS-exemplet

Exempelappen innehåller de utfärdade autentiseringsuppgifterna i minnet, så efter utfärdandet kan du använda den för presentation.

1. Appen WalletLibraryDemo bör visa namn på typ av autentiseringsuppgifter på startskärmen om du har utfärdat en autentiseringsuppgift.

   

2. I Woodgrove-demonstrationen i webbläsaren klickar du på Återgå till Woodgrove om du inte redan har gjort det och fortsätter med steg 3 Åtkomst till anpassad portal.

3. Skanna QR-koden med QR Code Reader-appen på testenheten och kopiera sedan den fullständiga URL:en till Urklipp.

4. Växla tillbaka till appen WalletLibraryDemo, rensa föregående begäran från textrutan, klistra in URL:en och klicka på knappen Skapa begäran

5. Appen hämtar presentationsbegäran och visar de matchande autentiseringsuppgifterna som du har i minnet. I det här fallet har du bara en. Klicka på den så att den lilla bockmarkeringen växlar från blått till grönt och klicka sedan på knappen Slutför för att skicka presentationssvaret

   

Nästa steg

Lär dig hur du konfigurerar klientorganisationen för Microsoft Entra – verifierat ID.