HarmonyOS 7 + User Authentication Kit + Asset Store Kit 技术干货：生物认证、敏感操作授权与关键资产安全闭环【鸿蒙心迹】

NNNbied

40人浏览 · 2026-09-29 00:14:10

NNNbied · 2026-09-29 00:14:10 发布

认证成功并不等于“敏感数据就安全了”。真正完整的安全链路，应该把“谁在操作、这次操作有没有被授权、授权之后能访问什么、敏感数据存在哪里”几件事连起来。这篇文章用一个安全资产中心 Demo，把 User Authentication Kit 与 Asset Store Kit 的职责边界和工程落地过程拆开来看。

一、为什么我不再把“指纹验证”当成一个登录按钮

第一次在应用里接用户认证时，最容易做成这样的流程：点按钮，弹出指纹或人脸认证，成功以后进入下一页。功能看起来完整，实际只是把“认证”做出来了。

问题在于，真实业务里的敏感操作远不止登录。

比如查看 API 密钥、读取登录凭据、进入隐私相册、导出敏感资料、修改支付设置，这些动作往往发生在用户已经登录以后。此时真正要解决的不是“用户是不是登录过”，而是当前这一次敏感操作，是否经过了可信身份确认。

这也是 User Authentication Kit 更适合承担的角色。系统提供统一身份认证接口，可结合锁屏口令、人脸、指纹等认证方式，对敏感操作做二次确认。认证凭据本身由系统安全环境处理，应用拿到的是认证结果，而不是生物特征原始数据。

但认证只是第一层。

如果认证成功后，应用仍然把 API Key、Token 或密码直接明文写到 Preferences、数据库字段甚至普通文件里，那么前面的认证更多只是“门口有一道锁”，资产本身并没有进入更合适的存储区域。

所以我这次把需求拆成两段：

User Authentication Kit 负责证明“当前操作者是谁、这次敏感动作是否获授权”；Asset Store Kit 负责保存和管理短敏感数据。

把两层分开之后，整个安全模型才真正立住。

二、先定边界：认证不是存储，存储也不是认证

这类需求最容易踩的第一个坑，就是把两个能力混成一个概念。

User Authentication Kit 的重点是“认证动作”：

当前设备是否存在可用认证凭据；
业务需要什么认证类型；
认证信任等级如何设置；
用户取消、超时、冻结时怎么处理；
认证结果是否允许继续敏感操作。

Asset Store Kit 的重点则完全不同：

哪些数据属于关键资产；
如何新增、查询、更新、删除关键资产；
是否要求认证保护；
数据读取的条件如何限制；
敏感数据怎样避免暴露到普通业务存储。

换句话说，一个解决“人”，一个解决“数据”。

这次 Demo 我把它设计成一个“安全资产中心”。页面里有三类敏感内容：API 密钥、登录凭据和加密业务数据。没有完成认证时，只显示资产名称和掩码；通过认证以后，才允许进入资产详情。

这个页面的价值不在视觉，而在于它把安全边界直接反映到了交互上。用户能看到资产存在，但不能因为“已经进了应用”就默认拥有读取权限。

三、发起认证之前，先别急着 start()

在工程里，我更建议把认证过程单独封装，而不是在页面按钮里直接写一堆认证代码。

原因很简单：认证不是普通异步方法，它有明确的状态和结果分支。用户可能认证成功，也可能取消、超时、凭据未录入，甚至当前认证方式处于锁定状态。如果这些判断全堆在页面里，后面再增加其他敏感入口时，逻辑很快会重复。

下面这段代码就是我会保留的一层认证服务。示例使用较新的 getUserAuthInstance() 方式，不再走旧的 getAuthInstance()：

import { userAuth } from '@kit.UserAuthenticationKit'
import { cryptoFramework } from '@kit.CryptoArchitectureKit'

export class AuthService {
  authenticate(): Promise<boolean> {
    return new Promise((resolve, reject) => {
      const random = cryptoFramework.createRandom()
      const challenge = random.generateRandomSync(16).data

      const authParam: userAuth.AuthParam = {
        challenge,
        authType: [
          userAuth.UserAuthType.FINGERPRINT,
          userAuth.UserAuthType.FACE,
          userAuth.UserAuthType.PIN
        ],
        authTrustLevel: userAuth.AuthTrustLevel.ATL3
      }

      const widgetParam: userAuth.WidgetParam = {
        title: '验证身份后访问安全资产'
      }

      const instance = userAuth.getUserAuthInstance(authParam, widgetParam)

      instance.on('result', {
        onResult: (result) => {
          if (result.result === userAuth.UserAuthResultCode.SUCCESS) {
            resolve(true)
          } else {
            resolve(false)
          }
        }
      })

      try {
        instance.start()
      } catch (err) {
        reject(err)
      }
    })
  }
}

这段代码里我最在意的不是参数本身，而是三件事。

第一，challenge 每次认证都应该是业务这一次认证上下文的一部分，而不是长期复用一个固定值。第二，认证方式最好根据业务风险等级做组合，而不是所有场景都只用一种方式。第三，认证实例本身是“一次认证一次实例”的思路，完成后不要把它当成长生命周期对象继续复用。

另外，涉及生物认证时要关注对应权限和设备能力。如果设备没有录入相应凭据，页面不应该只报“认证失败”，而应该把“未录入”“当前不支持”“认证被冻结”等状态转换成用户能理解的提示。

四、认证结果不要直接变成“全局通行证”

做完认证以后，还有一个很容易被忽略的问题：认证成功到底授权什么？

如果实现成“认证一次，整个应用之后都可以访问所有敏感数据”，安全边界就被放得太大了。

我更推荐把认证结果和敏感操作绑定。

比如用户点“查看 API 密钥”，认证成功后只允许完成这次 API 密钥读取；用户稍后再点“导出全部凭据”，应该重新判断是否需要认证，而不是因为刚才认证过一次就永久放行。

业务上可以维护一个非常轻的授权上下文：

interface SensitiveActionGrant {
  action: 'READ_API_KEY' | 'READ_CREDENTIAL' | 'EXPORT_SECRET'
  grantedAt: number
  expireAt: number
}

class GrantManager {
  private currentGrant?: SensitiveActionGrant

  grant(action: SensitiveActionGrant['action'], ttlMs: number = 60_000) {
    const now = Date.now()
    this.currentGrant = {
      action,
      grantedAt: now,
      expireAt: now + ttlMs
    }
  }

  canAccess(action: SensitiveActionGrant['action']): boolean {
    if (!this.currentGrant) return false
    return this.currentGrant.action === action && Date.now() < this.currentGrant.expireAt
  }

  clear() {
    this.currentGrant = undefined
  }
}

这不是为了自己再造一套安全认证，而是为了把“系统认证结果”和“业务操作范围”收口。系统负责证明用户身份，业务负责决定认证成功后允许做什么。

这两层不要混。

五、敏感数据落地时，Asset Store 才是第二道核心边界

认证完成以后，我才会进入资产读取或写入逻辑。

Asset Store Kit 的定位非常适合这类短敏感数据，比如密码类数据、Token、账号凭据、密钥材料等。它和普通数据库最大的区别，不是“API 写法不一样”，而是它从设计上就面向关键资产的安全存储和管理。

所以我的业务代码里不会出现“认证成功以后从普通 JSON 文件把密码读出来”这种路径，而是通过独立的 AssetService 去处理关键资产。

示意结构可以这样写：

import { asset } from '@kit.AssetStoreKit'

export class AssetService {
  async saveCredential(alias: string, secret: Uint8Array): Promise<void> {
    const attrs: asset.AssetMap = new Map()
    attrs.set(asset.Tag.ALIAS, alias)
    attrs.set(asset.Tag.SECRET, secret)
    attrs.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED)
    await asset.add(attrs)
  }

  async queryCredential(alias: string): Promise<asset.AssetResult[]> {
    const query: asset.AssetMap = new Map()
    query.set(asset.Tag.ALIAS, alias)
    query.set(asset.Tag.RETURN_TYPE, asset.ReturnType.ALL)
    return await asset.query(query)
  }
}

不同 SDK 版本里的枚举、属性名和可配置项可能继续变化，接入时应该以当前 API 参考为准，但架构思路不会变：敏感数据不要绕过资产存储层直接进入普通业务存储。