從應用程式核發 Microsoft Entra 已驗證的識別碼認證

發行項
11/01/2024

在本教學課程中，您會從本機電腦執行範例應用程式，以連線至您的 Microsoft Entra 租用戶。使用應用程式時，您將會發行並驗證已驗證的認證專家卡片。

在本文中，您將學會如何：

在 Azure 中建立已驗證的認證專家卡。
收集認證和環境詳細資料，以設定範例應用程式。
將範例應用程式程式碼下載至您的本機電腦。
使用已驗證的認證專家卡片和環境詳細資料來更新範例應用程式。
執行範例應用程式，並發行您的第一次已驗證認證專家卡。
驗證您的已驗證認證專家卡。

下圖說明 Microsoft Entra 已驗證的識別碼架構以及您所設定的元件。

說明 Microsoft Entra 已驗證識別碼架構的圖表。

必要條件

為 Microsoft Entra 驗證識別碼設定租用戶。
若要複製裝載範例應用程式的存放庫，請安裝 GIT。
Visual Studio Code、Visual Studio 或類似的程式碼編輯器。
.NET 7.0。
下載 ngrok 並註冊來取得一個免費帳戶。如果您無法在組織中使用 ngrok，請閱讀此常見問題。
含最新版 Microsoft Authenticator 的行動裝置。

在 Azure 中建立已驗證的認證專家卡

提示

根據您從中開始的入口網站，本文中的步驟可能會略有不同。

在此步驟中，您會使用 Microsoft Entra 已驗證的識別碼來建立已驗證認證專家卡。建立認證之後，您的 Microsoft Entra 租用戶可以將此認證發行給起始流程的使用者。

以全域管理員的身分登入 Microsoft Entra 系統管理中心。
選擇 [可驗證認證]。
設定您的租用戶之後，應會顯示 [建立認證]。或者，您可以在左側功能表中選取 [認證]，接著選取 [+ 新增認證]。

在 [建立認證]中，選取 [自訂認證]，然後按 [下一步]：

針對 [認證名稱]，輸入 VerifiedCredentialExpert。此名稱會在入口網站中用來識別您的可驗認證。其作為一部分的可驗認證合約納入。

複製下列 JSON，並將其貼到 [顯示定義] 文字方塊中

{
    "locale": "en-US",
    "card": {
      "title": "Verified Credential Expert",
      "issuedBy": "Microsoft",
      "backgroundColor": "#000000",
      "textColor": "#ffffff",
      "logo": {
        "uri": "https://didcustomerplayground.z13.web.core.windows.net/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"
    ]
  }
}

選取建立。

下列螢幕擷取畫面示範如何建立新的認證：

螢幕擷取畫面，其中顯示如何建立新認證。

收集認證和環境詳細資料

現在您已有新的認證，您將會收集有關您的環境和您所建立認證的一些資訊。設定應用程式範例時，您會使用這些資訊片段。

在 [可驗認證] 中，選取 [發行認證]。
複製授權單位 (即分散式識別碼)，並加以記錄以供稍後使用。
複製資訊清單 URL。它是 Authenticator 在向使用者可驗認證發行需求顯示之前評估的 URL。保留此資訊以供稍後使用。
複製您的租用戶識別碼，並加以記錄以供稍後使用。租用戶識別碼是上方以紅色醒目提醒資訊清單 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 應用程式。
選取名稱以進入註冊詳細資料。
複製應用程式 (用戶端) 識別碼並儲存，以供稍後使用。
從左側功能表的 [管理] 下，選取 [驗證與密碼]。
選取 [新增用戶端密碼]，然後執行下列動作：
1. 在 [描述] 中，輸入用戶端密碼的描述 (例如，vc-sample-secret)。
2. 在 [到期] 下，選取秘密的有效持續時間 (例如，六個月)。然後選取 [新增]。
3. 記錄祕密的 [值]。您將會在稍後的步驟中使用此值進行設定。密碼的值將不會再次顯示，也無法透過任何其他方式來擷取。密碼顯示時立即記錄。

此時，您應該擁有設定範例應用程式所需的所有必要資訊。

更新應用程式範例

現在，您將修改範例應用程式的簽發者程式碼，以使用可驗認證 URL 來進行更新。此步驟可讓您使用自己的租用戶發出可驗認證。

在 active-directory-verifiable-credentials-dotnet-main 資料夾下，開啟 Visual Studio Code，然後選取 1-asp-net-core-api-idtokenhint 資料夾內的專案。
開啟專案根資料夾下的 appsettings.json 檔案。此檔案包含 Microsoft Entra 已驗證的識別碼環境的相關資訊。使用您在先前步驟中記錄的資訊來更新下列屬性：
1. 租用戶識別碼：您的租用戶識別碼
2. 用戶端識別碼：您的用戶端識別碼
3. 用戶端密碼：您的用戶端密碼
4. DidAuthority：您的分散式識別碼
5. Credential Manifest：您的資訊清單 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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "ClientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "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/00001111-aaaa-2222-bbbb-3333cccc4444/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，並讓其可在網際網路上公開使用。
```
ngrok http 5000
```
注意

在某些電腦上，您可能需要以下列格式來執行該命令：./ngrok http 5000。
開啟 ngrok 所產生的 HTTPS URL。
從網頁瀏覽器中，選取 [取得認證]。
使用您的行動裝置，透過 Authenticator 應用程式掃描 QR 代碼。如需掃描 QR 代碼的詳細資訊，請參閱常見問題一節。
此時，您將看到一則訊息警告，指出此應用程式或網站可能有風險。選取進階。
在有風險的網站警告中，選取 [仍然繼續 (不安全)]。您看到此警告是因為您的網域未連結至您的分散式識別碼 (DID)。若要驗證您的網域，請遵循將您的網域連結至您的分散式識別碼 (DID)。在本教學課程中，您可以略過網域註冊，然後選取 [仍要繼續 (不安全)]。
系統將會提示您輸入在掃描 QR 代碼畫面中所顯示的 PIN 碼。 PIN 會為發行提供額外的保護層。每次顯示發行 QR 代碼時，系統會隨機產生 PIN 碼。
輸入 PIN 碼之後，[新增認證] 畫面隨即顯示。在畫面頂端，您會看到 未驗證 的訊息 (紅色)。此警告與先前所述的網域驗證警告有關。
選取 [新增] 以接受新的可驗認證。

恭喜！您現在擁有已驗證認證專家的可驗認證。

顯示新增的可驗認證的螢幕擷取畫面。

返回範例應用程式。應用程式會顯示已成功發行認證。

顯示成功核發的可驗認證的螢幕擷取畫面。

可驗認證名稱

您可驗認證包含認證中名字和姓氏值的 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 服務來驗證您的認證。

共用方式為