跳到主要內容

可驗證憑證宣告

可驗證憑證 (Verifiable Credential, VC) 是一種數位防竄改的憑證，可用於證明持有者的某些資訊。可驗證憑證宣告允許您的應用程式要求使用者從其 DID 錢包中出示特定的 VC，以證明某項屬性、資格或權利。

這是一種強大的資訊驗證方式，無需每次都聯繫原始發行者。常見的使用案例包括：

  • 驗證使用者的年齡，而無需透露其出生日期。
  • 確認組織的成員資格。
  • 證明票券或通行證的所有權。
  • 根據特定成就或證書來限制內容的存取權限。

如何請求可驗證憑證

要請求可驗證憑證，您需要在建立 DID Connect 會話時，在 claims 陣列中包含一個 verifiableCredential 物件。您可以指定各種條件來篩選您需要使用者錢包中的確切憑證。

DID Connect Handler

javascript
const handlers = new WalletHandlers({
  authenticator,
  // ... other configurations
});

app.get('/api/auth/login', async (req, res) => {
  const claims = {
    verifiableCredential: {
      description: '請出示您的 Blocklet Server 通行證以繼續。',
      filters: [
        {
          type: ['BlockletServerPassport'],
          trustedIssuers: ['zNKjDm4Xsoaffb19UE6Q_YOUR_ISSUER_DID_HERE'], // 發行者 DID 範例
        },
      ],
    },
  };

  // 錢包會提示使用者選擇一個匹配的憑證
  return handlers.auth(req, res, claims);
});

參數

verifiableCredential 宣告物件接受以下參數來定義請求：

ParameterTypeDescription
descriptionstring必填。 顯示在使用者錢包中的訊息，解釋請求該憑證的原因。
optionalboolean如果設定為 true，使用者可以跳過此宣告並繼續。預設為 false。
filtersarray篩選物件的陣列。錢包將找到匹配任何一個篩選條件的憑證（邏輯 OR）。在每個篩選物件中，所有條件都必須滿足（邏輯 AND）。這是推薦的現代方法。
claimUrlstring一個 URL，使用者可以在此處查看有關所請求宣告的更多資訊。
acquireUrlstring一個 URL，如果使用者尚未擁有所需憑證，可以前往此處獲取。

篩選物件參數

filters 陣列中的每個物件可以包含以下欄位：

ParameterTypeDescription
typestring[]可接受的 VC 類型名稱陣列。憑證必須匹配此列表中的其中一種類型。
trustedIssuersstring[]DID 的陣列。憑證必須由這些 DID 中的其中一個發行。
targetstring憑證發行對象的 DID。通常，這是使用者自己的 DID。
tagstring憑證上必須存在的特定標籤。
ownerDidstring[]允許出示該憑證的 DID 陣列。

舊版參數

為了向後相容，可以在宣告物件的頂層使用以下參數。但是，對於新應用程式，建議使用 filters 陣列。

  • item: (string[]) filters[0].type 的別名。
  • trustedIssuers: (string[]) filters[0].trustedIssuers 的別名。
  • target: (string) filters[0].target 的別名。
  • tag: (string) filters[0].tag 的別名。

範例

依類型和發行者請求憑證

這是最常見的使用案例。您知道您需要哪種憑證，以及您信任由誰發行。

Request a specific VC

javascript
const claims = {
  verifiableCredential: () => ({
    description: '請出示您的 Blocklet Server 通行證。',
    filters: [
      {
        type: ['BlockletServerPassport'],
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
      },
    ],
  }),
};

使用多個條件請求憑證

您可以提供多個篩選條件，給予使用者更多選擇。例如，您可以接受來自某個發行者的通行證，或來自另一個發行者帶有特定標籤的會員卡。

Request VC with multiple filters

javascript
const claims = {
  verifiableCredential: () => ({
    description: '請出示有效的通行證或帶有標籤的會員卡。',
    optional: true,
    filters: [
      // 選項 1：來自可信發行者的特定類型通行證
      {
        type: ['BlockletServerPassport'],
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
      },
      // 選項 2：來自另一位發行者的任何帶有特定標籤的憑證
      {
        trustedIssuers: ['zNKoA97a922N4234UE6QxVeevuaTaLCS1abc'],
        tag: 'gold_member_card',
      },
    ],
  }),
};

在此範例中，使用者可以透過出示來自第一個發行者的 BlockletServerPassport，或來自第二個發行者且標記為 gold_member_card 的任何憑證來滿足此請求。

成功請求可驗證憑證後，您可能希望請求另一種鏈上資料的所有權。在下一節中學習如何操作。

下一步：資產宣告

了解如何要求使用者出示鏈上資產（例如 NFT）以證明所有權。