跳到主要内容

Auth Principal 声明

authPrincipal 声明是任何 DID Connect 会话的基石。它是最基本、最常用的声明，旨在要求用户连接他们的钱包并选择一个去中心化标识符（DID）与您的应用程序进行交互。这第一步会建立一个安全的会话，并为应用程序提供用户的主要 DID，所有后续的交互都将基于此 DID 构建。

可以把它想象成“使用钱包登录”按钮。它不要求提供具体的个人数据，只是要求用户通过选择一个账户来表明自己的身份。

何时使用

在几乎所有需要用户交互的工作流中，您都应该使用 authPrincipal 声明作为第一步，包括：

  • 用户登录： 最基本的用例，允许用户登录到您的应用程序。
  • 会话启动： 启动一个多步骤流程，之后您将请求更具体的信息或操作（例如，签署交易或出示凭证）。
  • 建立上下文： 当您需要知道用户的 DID 以个性化用户体验或检查与该 DID 关联的现有数据时。

参数

authPrincipal 声明可以通过以下参数进行配置，以根据您的需求定制请求。

参数类型描述
descriptionstring必需。 在用户钱包中显示给用户的消息，解释为什么要求他们连接。默认为：“请使用您的账户继续”。
targetstring可选。您建议钱包使用的特定 DID。如果用户不拥有该 DID 或选择了其他 DID，钱包可能会忽略此建议。
supervisedboolean可选。如果设置为 true，表示这是一个委托连接场景，钱包可能代表另一个 DID 行事。默认为 false。
targetTypeobject可选。一个指定所选 DID 期望属性的对象。这对于请求具有特定加密特性的 DID 很有用。

目标类型字段

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 数组中完成。

Requesting a Basic Connection

javascript
const claims = {
  authPrincipal: {
    description: '登录我们出色的应用',
  },
};

// 当生成供用户扫描的二维码时，您的 WalletAuthenticator 实例将使用此 claims 对象。

示例：请求特定类型的 DID

如果您的应用程序需要与特定的区块链交互或需要某种密钥类型，您可以使用 targetType。

Requesting an Ethereum-compatible DID

javascript
const claims = {
  authPrincipal: {
    description: '连接您的以太坊兼容账户',
    targetType: {
      key: 'ethereum',
      role: 'account',
    },
  },
};

钱包响应

用户在钱包中扫描二维码并批准请求后，您应用程序的 onConnect 和 onAuth 处理程序将被触发。onAuth 回调将收到一个包含用户所选 DID 和公钥的会话对象。

Example onAuth Callback

javascript
const handlers = new WalletHandlers({
  // ...其他处理程序
  onAuth: async (session) => {
    console.log('用户已连接！', session);
    // session 对象包含：
    // session.userDid - 例如，'z1...'（用户的地址）
    // session.userPk - 用户的 Base58 格式公钥

    // 您现在可以在数据库中创建一个用户会话
    // 或继续工作流的下一步。
  },
});

后续步骤

通过 authPrincipal 声明建立会话后，您可以继续向用户请求更详细的信息或操作。常见的后续步骤包括：

个人资料声明

请求用户的基本信息，如姓名、电子邮件或头像，以创建用户个人资料。

签名声明

要求用户签署消息或交易，以证明所有权或授权操作。