账户登录 Cluster（AccountLogin）

Cluster ID: 0x050E  |  所在 Endpoint: 媒体端点（流媒体设备、智能电视上的内容应用）

AccountLogin 负责在智能电视或流媒体设备上完成内容提供商的账户认证。 当用户的手机 App 已登录某个视频服务（如 Netflix、YouTube）， 想让电视上的对应内容应用也获得该账户的访问权限时，就需要通过这个 Cluster 完成认证。 它不负责播放控制（那是 MediaPlayback 的事）， 而是解决「电视怎么知道你是谁」这个问题。

认证流程

AccountLogin 的认证是一个三步握手流程，由手机 App（Commissioner）主导：

1. 请求 PIN：手机 App 向电视上的内容应用发送 GetSetupPIN， 携带一个临时账户标识（TempAccountIdentifier）。 这个标识由手机端的内容提供商 App 生成，通常是一个关联到用户账户的临时令牌
2. 获取 PIN：电视端的内容应用验证临时标识后， 返回一个临时 Setup PIN（最长 8 个字符）。 这个 PIN 是一次性的，用于下一步的登录
3. 执行登录：手机 App 将临时标识和 Setup PIN 一起发送 Login 命令， 电视端验证通过后，该节点获得内容访问权限

命令（Commands）

AccountLogin Cluster 共有 3 个命令和 1 个响应。 其中 GetSetupPIN 有专属的响应结构体 GetSetupPINResponse， Login 和 Logout 通过通用 Status 返回结果。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

GetSetupPIN —— 请求 Setup PIN（0x00）

由手机 App（Client）发送给电视端的内容应用（Server），请求一个临时的 Setup PIN。 内容应用收到后，会根据 TempAccountIdentifier 查询对应的用户账户信息， 如果确认有效，则生成并返回一个临时 PIN。

↑ 返回命令列表

GetSetupPINResponse —— 返回 Setup PIN（0x01）

电视端内容应用对 GetSetupPIN 的响应。如果临时账户标识有效，返回一个可用于 Login 的临时 PIN。

↑ 返回命令列表

Login —— 登录（0x02）

使用前面获取的临时账户标识和 Setup PIN 完成登录。 登录成功后，发起请求的节点获得该内容应用的访问权限，可以浏览和播放用户订阅的内容。

↑ 返回命令列表

Logout —— 登出（0x03）

撤销之前通过 Login 获得的访问权限。登出后，对应节点将无法再访问该内容应用的用户内容。

↑ 返回命令列表

属性说明

AccountLogin Cluster 没有应用层面的自定义属性。 它只包含 Matter 规范要求的全局属性（Global Attributes），这些属性描述 Cluster 本身的元信息。

安全机制

AccountLogin 涉及用户账户认证，安全要求高于普通控制类 Cluster。 Matter 规范对它施加了以下约束：

Timed Invoke（限时调用）

所有三个命令都必须使用 Timed Invoke 发送。 Timed Invoke 的工作方式：

1. Client 先发一个 TimedRequest，声明后续命令的超时时间
2. Server 回复确认并开始计时
3. Client 在超时窗口内发送实际命令（如 Login）
4. 超时窗口关闭后，Server 不再接受该命令

这种机制的核心目的是防止重放攻击：即使攻击者截获了 Login 命令的完整数据包， 也无法在超时窗口关闭后重新发送。

临时 PIN 机制

Setup PIN 是认证流程中的第二道防线：

• PIN 由电视端内容应用动态生成，不是固定密码
• PIN 绑定到特定的 TempAccountIdentifier，不能跨账户使用
• PIN 应设置有效期（规范建议尽可能短），过期后即使知道 PIN 也无法登录
• PIN 使用后应立即失效，防止被二次使用

访问权限要求

AccountLogin 的命令需要 Administer 级别的访问权限（Access Privilege）。 这意味着只有在设备 ACL 中拥有管理员权限的节点才能调用这些命令， 普通的 Operate 级别权限不够。

示例数据

Cluster 属性读取

读取 AccountLogin Cluster 的全部属性（仅全局属性）：

{
  // --- 全局属性 ---
  "0xFFF8": [0, 1],            // GeneratedCommandList = [GetSetupPINResponse]
  "0xFFF9": [0, 2, 3],         // AcceptedCommandList = [GetSetupPIN, Login, Logout]
  "0xFFFB": [                   // AttributeList
    0xFFF8, 0xFFF9,
    0xFFFB, 0xFFFC, 0xFFFD
  ],
  "0xFFFC": 0,                  // FeatureMap = 0（无可选特性）
  "0xFFFD": 2                   // ClusterRevision = 2
}

GetSetupPIN 交互示例

手机 App 向电视内容应用请求 Setup PIN：

// 手机 App → 电视内容应用：请求 Setup PIN
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 3,
      "clusterId": "0x050E",
      "commandId": "0x00"              // GetSetupPIN
    },
    "commandFields": {
      "TempAccountIdentifier": "user_abc_token_20260901"
                                       // 手机端生成的临时账户标识
    },
    "timedRequest": true,              // 必须使用 Timed Invoke
    "interactionTimeoutMs": 10000
  }]
}

// 电视内容应用 → 手机 App：返回 Setup PIN
{
  "invokeResponseMessage": [{
    "commandPath": {
      "endpointId": 3,
      "clusterId": "0x050E",
      "commandId": "0x01"              // GetSetupPINResponse
    },
    "commandFields": {
      "SetupPIN": "34567890"           // 临时 PIN，用于后续 Login
    }
  }]
}

Login 交互示例

使用获取到的 PIN 完成登录：

// 手机 App → 电视内容应用：使用 PIN 登录
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 3,
      "clusterId": "0x050E",
      "commandId": "0x02"              // Login
    },
    "commandFields": {
      "TempAccountIdentifier": "user_abc_token_20260901",
      "SetupPIN": "34567890",          // GetSetupPINResponse 返回的 PIN
      "Node": "0x0000000012345678"     // 可选：指定授权的节点 ID
    },
    "timedRequest": true,
    "interactionTimeoutMs": 10000
  }]
}

// 电视内容应用 → 手机 App：Status = SUCCESS

Logout 交互示例

登出当前账户：

// 手机 App → 电视内容应用：登出
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 3,
      "clusterId": "0x050E",
      "commandId": "0x03"              // Logout
    },
    "commandFields": {
      "Node": "0x0000000012345678"     // 可选：指定要登出的节点 ID
    },
    "timedRequest": true,
    "interactionTimeoutMs": 10000
  }]
}

// 电视内容应用 → 手机 App：Status = SUCCESS

常见场景