将 Microsoft Entra 钱包库与验证 ID 配合使用

2025-06-30

本教程介绍移动应用如何使用 Microsoft Entra 电子钱包库和已验证 ID 来颁发和出示可验证凭据。

先决条件

在 Mac/Windows 和 Android 测试设备上安装的 Android Studio。需要在 Android 测试设备上启用开发人员模式。
Apple 开发人员帐户、具有 Xcode 的 Mac 和启用了开发人员模式的 iOS 测试设备。 iOS 版本至少需要 IOS 16。
在测试设备上安装 QR 代码读取器 应用。 WalletLibraryDemo 应用无法扫描 QR 码，因此需要 QR 码读取器应用来扫描 QR 码。

无需成为移动开发人员即可按照本教程操作，使演示应用启动并运行。你所需要的只是工具、测试设备和尝试的勇气。你也无需加入 Microsoft Entra 验证 ID 租户，因为可以使用公共端到端演示网站来测试演示应用。

注意

使用最新的可用电子钱包库获取对于自 2024 年 2 月以来验证 ID 使用的符合 NIST 的 P-256 曲线的支持。

什么是 Microsoft Entra 电子钱包库？

适用于 iOS 和 Android 的 Microsoft Entra 电子钱包库使移动应用能够开始使用 Microsoft Entra 验证 ID 平台。使用电子钱包库，移动应用使用电子钱包库根据行业标准发布和提供可验证凭据。

何时应使用 Microsoft Entra 电子钱包库？

Microsoft Authenticator 提供充当 Microsoft Entra 验证 ID 电子钱包的所有功能。但在无法使用 Microsoft Authenticator 的情况下，可以选择使用电子钱包库。例如，当你已经有一个用户熟悉的移动应用，并且在此应用中采用可验证凭据技术更有意义时。

可以在同一移动设备上同时使用 Microsoft Authenticator 和使用 Wallet Library 的移动应用程序。验证器（若已安装）是注册 openid:// 协议处理程序的应用，因此你的应用需要确保颁发和显示请求能够找到你的应用。使用依赖于 openid:// 协议的 HTML 页面中嵌入的深层链接会启动Microsoft Authenticator。

Microsoft 是否使用 Microsoft Entra 电子钱包库？

是，Microsoft Authenticator 使用钱包库。某些功能可能首先出现在 Authenticator 中，但我们的目标是在电子钱包库中提供这些功能。

将 Microsoft Entra 电子钱包库添加到我的应用需要哪些工作？

通过添加适用于 Android 的 maven 依赖项和添加适用于 iOS 的 cocoapod 依赖项，将电子钱包库添加到移动应用项目。

iOS
安卓

对于 iOS，将 WalletLibrary Pod 添加到 Podfile。

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

对于 Android，将 WalletLibrary Pod 添加到应用的 build.gradle，从而将钱包库添加为依赖项。

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

然后，需要添加一些代码来处理请求。有关详细信息，请参阅 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)
}

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

然后，必须在应用中处理以下主要任务。

获取请求 URL。电子钱包库不提供扫描二维码或类似代码的任何功能。如果想要为应用中未内置的任何其他选项提供支持，则需要自行添加这些功能。
存储凭据。电子钱包库创建用于对响应进行签名的私钥和公钥，并将其存储在设备上，但它没有任何用于存储凭据的功能。必须管理移动应用的凭据存储。
用户界面。必须实现存储凭据的任何可视表示形式以及用于驱动颁发和呈现过程的任何 UI 元素。

钱包库演示应用

电子钱包库在 GitHub 存储库中附带了一个演示应用，无需进行任何修改即可使用。只需生成和部署它即可。演示应用是一个轻量级的简单实现，至少演示颁发和出示凭据。若要快速开始，可以使用二维码读取器应用扫描二维码，然后将其复制并粘贴到演示应用中。

若要测试演示应用，需要一个 Web 应用来颁发凭据并发出出示凭据的请求。在本教程中，Woodgrove 公共演示 Web 应用用于此目的。

生成 Android 示例

在使用 Android Studio 的开发人员计算机上，执行以下步骤：

下载或克隆 Android 电子钱包库 GitHub 存储库。不需要电子钱包库文件夹，可以根据需要将其删除。
启动 Android Studio 并打开 walletlibrarydemo 的父文件夹
选择“生成”菜单，然后选择“生成项目”。此步骤需要一些时间。
通过 USB 电缆将 Android 测试设备连接到笔记本电脑
在 Android Studio 中选择测试设备，然后选择 “运行 ”按钮（绿色三角形）

使用 Android 颁发凭据示例

启动 WalletLibraryDemo 应用
在笔记本电脑上，启动公共演示网站 https://aka.ms/vcdemo 并执行以下操作
1. 输入名字和姓氏，然后按“下一步”
2. 选择“使用真实身份验证”
3. 选择“自拍”；上传政府颁发的身份证。演示使用模拟数据，无需提供真实的自拍或 ID。
4. 选择“下一步”和“确定”
在测试设备上使用二维码读取器应用扫描二维码，然后复制二维码读取器应用中显示的完整 URL。记下 PIN 码。
切换回 WalletLibraryDemo 应用并从剪贴板粘贴 URL
按下“创建请求”按钮
当应用下载请求时，它会显示一个屏幕，如提供的示例。请点击白色矩形（文本框），然后输入浏览器页面中显示的PIN码。然后选择“ 完成 ”按钮。
颁发完成后，演示应用会在凭据中显示声明

使用 Android 出示凭据的示例

示例应用将颁发的凭据存储在内存中，因此颁发后，你可以使用它进行出示。

如果已成功颁发凭据，则 WalletLibraryDemo 应用应在主屏幕上显示一些凭据详细信息。
在浏览器中的 Woodgrove 演示中，如果尚未执行此操作，请选择 返回到 Woodgrove，并继续执行步骤 3 访问个性化门户。
使用测试设备上的二维码读取器应用扫描二维码，然后将完整 URL 复制到剪贴板。
切换回 WalletLibraryDemo 应用并粘贴 URL，然后选择“ 创建请求 ”按钮
应用会检索出示请求，并显示内存中匹配的凭据。在这种情况下，只有一个匹配的凭据。 单击它 ，以便显示小复选标记，然后选择 “完成 ”按钮以提交演示文稿响应

生存 iOS 示例

在具有 Xcode 的 Mac 开发人员计算机上，执行以下步骤：

下载或克隆 iOS 电子钱包库 GitHub 存储库。
启动 Xcode 并打开 WalletLibrary 的顶级文件夹
选择 WalletLibraryDemo 项目
将团队 ID 更改为 Apple 开发人员团队 ID。
选择“产品”菜单，然后选择“生成”。此步骤需要一些时间。
通过 USB 电缆将 iOS 测试设备连接到笔记本电脑
在 Xcode 中选择测试设备
选择“产品”菜单，然后选择“运行”或选择“运行”三角形图标

使用 iOS 颁发凭据示例

启动 WalletLibraryDemo 应用
在笔记本电脑上，启动公共演示网站 https://aka.ms/vcdemo 并执行以下操作
1. 输入名字和姓氏，然后按“下一步”
2. 选择“使用真实身份验证”
3. 选择“自拍”；上传政府颁发的身份证。演示使用模拟数据，无需提供真实的自拍或 ID。
4. 选择“下一步”和“确定”
在测试设备上使用二维码读取器应用扫描二维码，然后复制二维码读取器应用中显示的完整 URL。记下 PIN 码。
切换回 WalletLibraryDemo 应用并从剪贴板粘贴 URL
按下“创建请求”按钮
当应用完成下载请求时，它会显示一个类似于我们的示例的屏幕。选择添加PIN以进入输入PIN码的界面，然后选择添加按钮以返回，最后选择完成按钮。
颁发完成后，演示应用会在凭据中显示声明。

使用 iOS 出示凭据的示例