跳到主要內容

Auth Principal 宣告

authPrincipal 宣告是任何 DID Connect 會話的基石。它是最基本且最常用的宣告，旨在要求使用者連接他們的錢包並選擇一個去中心化識別碼（DID）來與您的應用程式互動。這個初始步驟建立了一個安全的會話，並為應用程式提供了使用者的主要 DID，所有後續的互動都建立在此基礎之上。

可以將其視為「用錢包登入」按鈕。它不要求特定的個人資料，僅要求使用者透過選擇一個帳戶來識別自己的身份。

使用時機

在幾乎所有需要使用者互動的工作流程中，您都應該使用 authPrincipal 宣告作為第一步，包括：

  • 使用者登入： 最基本的使用案例，允許使用者登入您的應用程式。
  • 啟動會話： 開始一個多步驟的流程，您稍後將請求更具體的資訊或操作（例如，簽署一筆交易或出示一份憑證）。
  • 建立情境： 當您需要知道使用者的 DID 以個人化使用者體驗或檢查與該 DID 相關的現有資料時。

參數

authPrincipal 宣告可以配置以下參數，以根據您的需求客製化請求。

參數類型描述
descriptionstring必要。 顯示給使用者錢包的訊息，解釋為何要求他們連線。預設為："Please continue with your account"。
targetstring選用。您建議錢包應使用的特定 DID。如果使用者不擁有該 DID 或選擇了另一個，錢包可能會忽略此建議。
supervisedboolean選用。若設為 true，表示這是一個代理連線情境，錢包可能代表另一個 DID 行事。預設為 false。
targetTypeobject選用。一個物件，用以指定所選 DID 的期望屬性。這對於請求具有特定密碼學特性的 DID 很有用。

Target Type 欄位

targetType 物件可以包含以下欄位，以篩選呈現給使用者的 DID：

欄位類型描述
keystring期望的金鑰類型。有效值："ed25519"、"secp256k1"、"ethereum"。預設為 "ed25519"。
hashstring期望的雜湊函數。有效值："sha3"、"keccak"、"sha2"。預設為 "sha3"。
rolestring期望的錢包帳戶角色類型。有效值包括 "account"、"node"、"application"、"smart_contract" 等。預設為 "account"。
encodingstring期望的編碼格式。有效值："base58"、"base16"。預設為 "base58"。

使用範例

以下是如何請求使用者使用標準帳戶進行連線。這通常在您的 DID Connect 設定的 claims 陣列中完成。

請求基本連線

javascript
const claims = {
  authPrincipal: {
    description: '登入我們超棒的應用程式',
  },
};

// 這個 claims 物件將由您的 WalletAuthenticator 實例
// 在生成供使用者掃描的 QR code 時使用。

範例：請求特定類型的 DID

如果您的應用程式需要與特定的區塊鏈互動或需要某種金鑰類型，您可以使用 targetType。

請求與以太坊相容的 DID

javascript
const claims = {
  authPrincipal: {
    description: '連線您的以太坊相容帳戶',
    targetType: {
      key: 'ethereum',
      role: 'account',
    },
  },
};

錢包回應

在使用者掃描 QR code 並在錢包中核准請求後，您應用程式的 onConnect 和 onAuth 處理常式將被觸發。onAuth 回呼函式將收到一個包含使用者所選 DID 和公鑰的會話物件。

onAuth 回呼範例

javascript
const handlers = new WalletHandlers({
  // ...其他處理常式
  onAuth: async (session) => {
    console.log('使用者已連線！', session);
    // session 物件包含：
    // session.userDid - 例如：'z1...' (使用者的地址)
    // session.userPk - 使用者的 base58 格式公鑰

    // 您現在可以在資料庫中建立使用者會話
    // 或繼續您工作流程的下一步。
  },
});

後續步驟

一旦使用 authPrincipal 宣告建立會話後，您就可以繼續向使用者請求更詳細的資訊或操作。常見的後續步驟包括：

個人資料宣告

請求使用者的基本資訊，如姓名、電子郵件或頭像，以建立使用者個人資料。

簽名宣告

要求使用者簽署訊息或交易，以證明所有權或授權一項操作。