从应用程序颁发 Microsoft Entra 验证 ID 凭据

项目
01/17/2024

在本教程中，你将从连接到 Microsoft Entra 租户的本地计算机运行示例应用程序。使用该应用程序，你将颁发已验证凭据专家卡并对其进行验证。

在本文中，学习如何：

在 Azure 中创建已验证凭据专家卡。
收集凭据和环境详细信息来设置示例应用程序。
将示例应用程序代码下载到本地计算机。
使用已验证凭据专家卡和环境详细信息更新示例应用程序。
运行示例应用程序并颁发第一张已验证凭据专家卡。
验证已验证凭据专家卡。

下图展示了 Microsoft Entra 验证 ID 体系结构以及所配置的组件。

Diagram that illustrates the Microsoft Entra Verified ID architecture.

先决条件

为 Microsoft Entra 验证 ID 设置租户。
若要克隆托管示例应用的存储库，请安装 GIT。
Visual Studio Code、Visual Studio 或类似代码编辑器。
.NET 7.0.
下载 ngrok 并注册免费帐户。如果无法在组织中使用ngrok，请参阅该常见问题解答。
带有最新版 Microsoft Authenticator 的移动设备。

在 Azure 中创建已验证凭据专家卡

提示

本文中的步骤可能因开始使用的门户而略有不同。

在此步骤中，你将使用 Microsoft Entra 验证 ID 创建已验证凭据专家卡。创建凭据后，你的 Microsoft Entra 租户可以向启动该过程的用户颁发此凭据。

至少以全局管理员身份登录到 Microsoft Entra 管理中心。
选择“可验证凭据”。
设置租户后，应会显示“创建凭据”。或者，可以在左侧菜单中选择“凭据”，然后选择“+ 添加凭据”。

在“创建凭据”中，选择“自定义凭据”，然后单击“下一步”：

在“凭据名称”中，输入 VerifiedCredentialExpert。该名称用于在门户中识别可验证凭据。它作为可验证凭据协定的一部分。

复制以下 JSON 并将其粘贴到“显示定义”文本框

{
    "locale": "en-US",
    "card": {
      "title": "Verified Credential Expert",
      "issuedBy": "Microsoft",
      "backgroundColor": "#000000",
      "textColor": "#ffffff",
      "logo": {
        "uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png",
        "description": "Verified Credential Expert Logo"
      },
      "description": "Use your verified credential to prove to anyone that you know all about verifiable credentials."
    },
    "consent": {
      "title": "Do you want to get your Verified Credential?",
      "instructions": "Sign in with your account to get your card."
    },
    "claims": [
      {
        "claim": "vc.credentialSubject.firstName",
        "label": "First name",
        "type": "String"
      },
      {
        "claim": "vc.credentialSubject.lastName",
        "label": "Last name",
        "type": "String"
      }
    ]
}

复制以下 JSON 并将其粘贴到“规则定义”文本框

{
  "attestations": {
    "idTokenHints": [
      {
        "mapping": [
          {
            "outputClaim": "firstName",
            "required": true,
            "inputClaim": "$.given_name",
            "indexed": false
          },
          {
            "outputClaim": "lastName",
            "required": true,
            "inputClaim": "$.family_name",
            "indexed": true
          }
        ],
        "required": false
      }
    ]
  },
  "validityInterval": 2592000,
  "vc": {
    "type": [
      "VerifiedCredentialExpert"
    ]
  }
}

选择“创建” 。

以下屏幕截图演示了如何创建新凭据：

Screenshot that shows how to create a new credential.

收集凭据和环境详细信息

获得新凭据后，你将收集有关环境和已创建凭据的一些信息。设置示例应用程序时，会用到这些信息。

在“可验证凭据”中，选择“颁发凭据”。
复制即分散式标识符“authority”，记录下来供稍后使用。
复制“清单”URL。它是 Authenticator 在显示为用户可验证凭据颁发要求之前评估的 URL。请记下它供将来使用。
复制“租户 ID”并记下它供将来使用。租户 ID 是上面以红色突出显示的清单 URL 中的 GUID。

下载示例代码

示例应用程序在 .NET 中提供，代码保留在 GitHub 存储库中。可从 GitHub 下载示例代码，或将存储库克隆到本地计算机：

git clone https://github.com/Azure-Samples/active-directory-verifiable-credentials-dotnet.git

配置可验证凭据应用

为你创建的已注册应用程序创建客户端密码。该示例应用程序请求令牌时使用客户端密码来证明其身份。

至少以全局管理员身份登录到 Microsoft Entra 管理中心。
选择“Microsoft Entra ID”。
转到“应用程序”>“应用注册”页。
选择此前创建的“verifiable-credentials-app”应用程序。
选择可用于查看注册详细信息的名称。
复制“应用程序(客户端) ID”并保存它供以后使用。
在主菜单中的“管理”下，选择“证书和机密”。
选择“新建客户端密码”，然后执行以下操作：
1. 在“说明”框中输入客户端密码的说明（例如 vc-sample-secret）。
2. 在“过期时间”下，选择密码的有效期（例如 6 个月）。然后选择“添加” 。
3. 记下机密的“值”。在稍后的步骤中将使用此值进行配置。不会再次显示该密码的值，也无法通过任何其他方法进行检索。在显示时尽快记录。

此时，你应具有设置示例应用程序所需的所有必需信息。

更新示例应用程序

现在，对示例应用的颁发者代码进行修改，以便用可验证凭据 URL 更新它。此步骤使你可以使用自己的租户颁发可验证凭据。

在 active-directory-verifiable-credentials-dotnet-main 文件夹下，打开 Visual Studio Code，然后选择 1-asp-net-core-api-idtokenhint 文件夹中的项目。
在项目根文件夹下，打开 appsettings.json 文件。此文件包含有关 Microsoft Entra 验证 ID 环境的信息。用在前面的步骤中记录的信息更新以下属性：
1. 租户 ID：你的租户 ID
2. Client ID：客户端 ID
3. 客户端密码：你的客户端 ID
4. DidAuthority：你的分散式标识符
5. 凭据清单：清单 URL
CredentialType 仅在演示时需要，因此如果只想颁发，严格来说并不需要它。
保存 appsettings.json 文件。

下面的 JSON 演示了一个完整的 appsettings.json 文件：

{
  "VerifiedID": {
    "Endpoint": "https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/",
    "VCServiceScope": "3db474b9-6a0c-4840-96ac-1fceb342124f/.default",
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "12345678-0000-0000-0000-000000000000",
    "ClientId": "33333333-0000-0000-0000-000000000000",
    "ClientSecret": "123456789012345678901234567890",
    "CertificateName": "[Or instead of client secret: Enter here the name of a certificate (from the user cert store) as registered with your application]",
    "DidAuthority": "did:web:...your-decentralized-identifier...",
    "CredentialType": "VerifiedCredentialExpert",
    "CredentialManifest":  "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/VerifiedCredentialExpert"
  }
}

颁发首张已验证凭据专家卡

现在，你已准备好运行示例应用程序来颁发首张已验证凭据专家卡。

在 Visual Studio Code 中，运行 Verifiable_credentials_DotNet 项目。或者，从操作系统的命令行,运行：

cd active-directory-verifiable-credentials-dotnet\1-asp-net-core-api-idtokenhint
dotnet build "AspNetCoreVerifiableCredentials.csproj" -c Debug -o .\bin\Debug\net6.
dotnet run

在另一个命令提示符窗口，运行以下命令。此命令会运行 ngrok 在 5000 上设置一个 URL，并使其在 Internet 上公开可用。
```
ngrok http 5000
```
注意

在某些计算机上，可能需要以 ./ngrok http 5000 格式运行命令。
打开 ngrok 生成的 HTTPS URL。
在 Web 浏览器中，选择“获取凭据”。
使用移动设备，通过 Authenticator 应用扫描 QR 码。你还可直接从照相机扫描 QR 码，这会为你打开 Authenticator 应用。
此时，你会看到一条消息，警告你此应用或网站可能有风险。选择“高级”。
在出现“网站有风险”的警告时，选择“仍然继续(不安全)”。你会看到此警告，因为你的域未链接到你的去中心化标识符。若要验证域，请按照将域关联到去中心化标识符 (DID)进行操作。对于本教程，可跳过域注册，选择“仍然继续(不安全)”。
系统将提示你输入在扫描 QR 码的屏幕中显示的 PIN 码。 PIN 向颁发添加了额外的保护层。每次显示颁发 QR 码时，都会随机生成 PIN 码。
输入 PIN 码后，会显示“添加凭据”屏幕。在屏幕顶部，可以看到“未验证”消息（红色）。此警告与之前提到的域验证警告相关。
选择“添加”以接受新的可验证凭据。

祝贺你！你现在拥有已验证凭据专家可验证凭据。

Screenshot that shows a newly added verifiable credential.

返回到示例应用。其中显示凭据已成功颁发。

Screenshot that shows a successfully issued verifiable credential.

可验证凭据名称

可验证凭据包含 Megan Bowen 用作凭据中的名字和姓氏值。这些值在示例应用程序中进行了硬编码，并在有效负载中颁发时添加到了可验证凭据。

在实际情况下，应用程序将从标识提供者中提取用户详细信息。以下代码片段显示了在示例应用程序中的哪里设置名称。

//file: IssuerController.cs
[HttpGet("/api/issuer/issuance-request")]
public async Task<ActionResult> issuanceRequest()
  {
    ...
    // Here you could change the payload manifest and change the first name and last name.
    payload["claims"]["given_name"] = "Megan";
    payload["claims"]["family_name"] = "Bowen";
    ...
}

后续步骤

在下一步中，你将了解第三方应用程序（也称为信赖方应用）如何通过其自己的 Microsoft Entra 租户可验证凭据 API 服务来验证你的凭据。