将 Microsoft Entra 电子钱包库与已验证 ID 配合使用
本教程介绍移动应用如何使用 Microsoft Entra 电子钱包库和已验证 ID 来颁发和出示可验证凭据。
- 安装在 Mac/Windows 和 Android 测试设备上的 Android Studio。 需要在 Android 测试设备上启用开发人员模式。
- Apple 开发人员帐户、具有 Xcode 的 Mac,以及启用了开发人员模式的 iOS 测试设备。 iOS 版本必须是 16 及以上版本。
- 在测试设备上安装二维码读取器应用。 WalletLibraryDemo 应用没有扫描二维码的功能,因此需要二维码读取器应用来扫描二维码。
无需成为移动开发人员即可按照本教程操作,使演示应用启动并运行。 你所需要的只是工具、测试设备和尝试的勇气。 你也无需加入 Microsoft Entra 验证 ID 租户,因为可以使用公共端到端演示网站来测试演示应用。
备注
使用最新的可用电子钱包库获取对于自 2024 年 2 月以来验证 ID 使用的符合 NIST 的 P-256 曲线的支持。
适用于 iOS 和 Android 的 Microsoft Entra 电子钱包库使移动应用能够开始使用 Microsoft Entra 验证 ID 平台。 使用电子钱包库,移动应用可以根据行业标准颁发和出示可验证凭据。
Microsoft Authenticator 提供充当 Microsoft Entra 验证 ID 电子钱包的所有功能。 但在无法使用 Microsoft Authenticator 的情况下,可以选择使用电子钱包库。 例如,当你已经有一个用户熟悉的移动应用,并且在此应用中采用可验证凭据技术更有意义时。
可以在同一移动设备上同时使用 Microsoft Authenticator 和使用电子钱包库的移动应用。 如果已安装了 Authenticator,则它将是已注册 openid:// 协议处理程序的应用,因此你的应用需要确保颁发和出示请求能够找到应用。 在依赖于 openid:// 协议的 HTML 页面中使用嵌入的深层链接会导致 Microsoft Authenticator 启动。
是,Microsoft Authenticator 使用电子钱包库。 某些功能可能首先出现在 Authenticator 中,但我们的目标是在电子钱包库中提供这些功能。
通过添加适用于 Android 的 maven 依赖项和添加适用于 iOS 的 cocoapod 依赖项,将电子钱包库添加到移动应用项目。
对于 iOS,将 WalletLibrary Pod 添加到 Podfile。
target "YourApp" do
use_frameworks!
pod "WalletLibrary", "~> 1.0.1"
end
然后,需要添加一些代码来处理请求。 有关详细信息,请参阅 WalletLibraryDemo 示例代码。
/// 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)
}
然后,必须在应用中处理以下主要任务。
- 获取请求 URL。 电子钱包库不提供扫描二维码或类似代码的任何功能。 通过扫描二维码等方法获取请求 URL 必须由你添加。
- 存储凭据。 电子钱包库创建用于签名响应的私钥和公钥,并将其存储在设备上,但它不附带任何存储凭据的功能。 必须管理移动应用的凭据存储。
- 用户界面。 用于引导颁发和出示过程的存储凭据的任何视觉表示和 UI 都必须由你实现。
电子钱包库在 GitHub 存储库中附带了一个演示应用,无需进行任何修改即可使用。 只需生成和部署它即可。 演示应用是一个轻量级的简单实现,至少演示颁发和出示凭据。 若要快速开始,可以使用二维码读取器应用扫描二维码,然后将其复制并粘贴到演示应用中。
若要测试演示应用,需要一个 Web 应用来颁发凭据并发出出示凭据的请求。 在本教程中,Woodgrove 公共演示 Web 应用用于此目的。
在具有 Android Studio 的开发人员计算机上,执行以下操作:
下载或克隆 Android 电子钱包库 GitHub 存储库。 不需要 walletlibrary 文件夹,可以根据需要将其删除。
启动 Android Studio 并打开 walletlibrarydemo 的父文件夹
选择“生成”菜单,然后选择“生成项目”。 此步骤需要一些时间。
通过 USB 电缆将 Android 测试设备连接到笔记本电脑
在 Android Studio 中选择测试设备,然后单击“运行”按钮(绿色三角形)
启动 WalletLibraryDemo 应用
在笔记本电脑上,启动公共演示网站 https://aka.ms/vcdemo 并执行以下操作
- 输入名字和姓氏,然后按“下一步”
- 选择“使用真实身份验证”
- 单击“自拍”和“上传政府颁发的 ID”。 演示使用模拟数据,无需提供真实的自拍或 ID。
- 单击“下一步”和“确定”
在测试设备上使用二维码读取器应用扫描二维码,然后复制二维码读取器应用中显示的完整 URL。 记下 PIN 码。
切换回 WalletLibraryDemo 应用并从剪贴板粘贴 URL
按下“创建请求”按钮
应用下载请求后,屏幕会如下所示。 单击白色矩形(即文本框),输入浏览器页面显示的 PIN 码。 然后单击“完成”按钮。
颁发完成后,演示应用会在凭据中显示声明
示例应用将颁发的凭据存储在内存中,因此颁发后,你可以使用它进行出示。
如果已成功颁发凭据,WalletLibraryDemo 应用的主屏幕上会显示一些凭据详细信息。
在浏览器中的 Woodgrove 演示中,单击“返回 Woodgrove”(如果尚未返回),然后继续执行步骤 3“访问个性化门户”。
使用测试设备上的二维码读取器应用扫描二维码,然后将完整 URL 复制到剪贴板。
切换回 WalletLibraryDemo 应用并粘贴 URL,然后单击“创建请求”按钮
应用会检索出示请求,并显示内存中匹配的凭据。 在这种情况下,只有一个匹配的凭据。 单击凭据,随即会显示小选中标记,然后单击“完成”按钮提交出示响应
在具有 Xcode 的 Mac 开发人员计算机上,执行以下操作:
下载或克隆 iOS 电子钱包库 GitHub 存储库。
启动 Xcode 并打开 WalletLibrary 的顶级文件夹
选择 WalletLibraryDemo 项目
将团队 ID 更改为 Apple 开发人员团队 ID。
选择“产品”菜单,然后选择“生成”。 此步骤需要一些时间。
通过 USB 电缆将 iOS 测试设备连接到笔记本电脑
在 Xcode 中选择测试设备
选择“产品”菜单,然后选择“运行”或单击运行三角形
启动 WalletLibraryDemo 应用
在笔记本电脑上,启动公共演示网站 https://aka.ms/vcdemo 并执行以下操作
- 输入名字和姓氏,然后按“下一步”
- 选择“使用真实身份验证”
- 单击“自拍”和“上传政府颁发的 ID”。 演示使用模拟数据,无需提供真实的自拍或 ID。
- 单击“下一步”和“确定”
在测试设备上使用二维码读取器应用扫描二维码,然后复制二维码读取器应用中显示的完整 URL。 记下 PIN 码。
切换回 WalletLibraryDemo 应用并从剪贴板粘贴 URL
按下“创建请求”按钮
应用下载请求后,屏幕会如下所示。 单击“添加 PIN”文本,转到输入 PIN 码的屏幕,然后单击“添加”按钮返回,最后单击“完成”按钮。
颁发完成后,演示应用会在凭据中显示声明。
示例应用将颁发的凭据存储在内存中,因此颁发后,你可以使用它进行出示。
如果已成功颁发凭据,WalletLibraryDemo 应用的主屏幕上会显示凭据类型名称。
在浏览器中的 Woodgrove 演示中,单击“返回 Woodgrove”(如果尚未返回),然后继续执行步骤 3“访问个性化门户”。
使用测试设备上的二维码读取器应用扫描二维码,然后将完整 URL 复制到剪贴板。
切换回 WalletLibraryDemo 应用,在文本框中“清除上一个请求”,粘贴 URL,然后单击“创建请求”按钮
应用会检索出示请求,并显示内存中匹配的凭据。 在这种情况下,只有一个匹配的凭据。 单击凭据,使小选中标记从蓝色变为绿色,然后单击“完成”按钮提交出示响应