三方授权对接流程说明

三方授权观看限制对接文档

三方授权是活动观看限制的一种类型：开启后，由主办方自行决定观众能否观看直播，通过“主办方服务端生成签名、平台校验签名”的方式实现。本文档面向开发者，介绍该能力的接入前提、签名规则、代码示例与联调方法。

名词约定

平台：提供直播服务与开放平台的 SaaS 服务方，即本文档发布方。控制台、观看页及签名校验等能力均由平台提供。

主办方：在平台开通账号、通过控制台创建并运营直播活动的企业，即活动所属账号的持有方。若您是为该企业提供技术服务的集成商、外包或供应商，“主办方”即指您所服务的企业。

主办方服务端：承担签名计算的服务端，可由主办方自行开发与部署，也可由其委托的技术服务商开发与维护。

观众：通过嵌入观看页观看直播的人。

三方授权：观看限制的一种类型，即本文档所述能力。

嵌入观看页：可嵌入主办方自有页面使用的活动观看页，支持 iframe 或 WebView 嵌入。三方授权仅对该观看页生效。

应用：主办方在平台开放平台创建的应用，用于取得 app_key 与 secret_key。

1. 功能说明

1.1 能力概述

主办方服务端按本文规则生成签名，观众进入嵌入观看页时由平台校验签名，校验通过方可观看。签名密钥 secret_key 仅由主办方服务端持有，主办方为哪些观众生成签名，即决定了哪些观众可以观看。

签名生成与校验的具体规则见第 5 节。

1.2 限制说明

仅支持为活动开启三方授权，专题暂不支持。

仅支持通过嵌入观看页接入，普通观看页与 SDK 观看入口不适用。

当活动所属专题已配置观看限制时，专题观看限制优先生效。

主持人、助理等特殊角色沿用平台原有规则，不受三方授权影响。

三方授权与活动报名表单互斥，两者不能同时开启。

2. 对接前提

开始对接前，请确认以下事项：

已在平台开放平台创建应用，并取得 app_key 和 secret_key。

应用已处于启用状态。

应用归属于活动所属的主办方账号。

已在活动管理后台将观看限制设置为“三方授权”。

活动观看入口已采用嵌入观看页。

安全要求：secret_key 仅允许保存在主办方服务端，严禁写入网页源码、前端脚本或客户端 App，也不得通过 URL 传递。

3. 对接流程

观众登录主办方业务系统。

主办方业务系统确认该观众允许观看目标活动。

主办方服务端按第 5 节规则为该观众计算签名 auth_sign。

主办方将签名相关参数拼接至活动嵌入观看页 URL，并将该链接提供给观众。拼接格式见第 4 节。

观众通过该链接进入嵌入观看页，由观看页完成签名验证。验证通过后，本次签名被绑定到当前浏览器，绑定规则见第 7 节，观众即可正常进入直播间。

若验证失败，观众将在观看页看到失败提示，无法观看。失败原因与排查方式见第 9 节。

4. 嵌入观看页签名参数

下表仅列出参与签名的参数；嵌入观看页的其余字段不参与签名，相关说明请参见《嵌入观看页对接文档》。

参数	类型	说明
`app_key`	字符串	开放平台应用标识，须归属于活动所属的主办方账号。
`auth_ts`	整型	生成签名时的 Unix 秒级时间戳（10 位数字），不是毫秒时间戳。
`webinar_id`	整型	当前需要访问的活动 ID。
`email`	字符串	观众邮箱。活动开启三方授权时必填，且必须为合法邮箱。
`auth_sign`	字符串	按第 5 节规则生成的 HMAC-SHA256 签名结果，64 位小写十六进制字符串。该字段本身不参与签名。

携带签名参数的 URL 示例：

https://live.example.com/v3/lives/embedclientfull/watch/42?email=alice%40example.com&app_key=app-key&auth_ts=1700000000&auth_sign=9c5b66b43527979012af97bbe6b1818680be874f39c4c4e0ef9bca513bbeed72&nickname=xiaoming

参数一致性要求：URL 中 app_key、email 的取值必须与生成签名时编码后的结果完全一致。请勿在拼接 URL 时对其再次编码，例如将 alice%40example.com 再次编码为 alice%2540example.com，否则平台解析出的参数值与签名原文不一致，将导致校验失败。

5. 签名规则

5.1 签名算法

auth_sign = lowercase_hex(HMAC-SHA256(canonical_string, secret_key))

签名算法：HMAC-SHA256，非普通 SHA-256

HMAC 密钥：应用的 secret_key，须使用平台提供的完整原始值，首尾勿带入空白字符

输入：签名原文按 UTF-8 编码为字节序列

输出：小写十六进制字符串，固定 64 个字符

5.2 参数预处理

参与签名原文的字段共 4 个：app_key、webinar_id、email、auth_ts。各字段处理规则如下：

字符串字段 app_key、email：先 trim 去除首尾空白，再按 RFC 3986 进行百分号编码。编码针对原始值，请勿对已编码结果二次编码。

整型字段 webinar_id、auth_ts：以十进制整数直接拼入，无需 trim 或百分号编码；不得包含空格、加号、小数点、科学计数法或前导零。

全部字段按 5.3 节固定顺序以 key=value 形式拼接，字段之间用 & 连接。

5.3 签名原文固定顺序

签名原文必须严格按照以下顺序组装：

app_key={encoded_app_key}&webinar_id={webinar_id}&email={encoded_email}&auth_ts={auth_ts}

不得按参数名重新排序，不得增加其他字段，也不得直接使用整个页面 URL 作为签名原文。

5.4 签名样例

原始参数：

字段	值
`app_key`	`app-key`
`webinar_id`	`42`
`email`	`alice@example.com`
`auth_ts`	`1700000000`
`secret_key`	`secret`

签名原文：

app_key=app-key&webinar_id=42&email=alice%40example.com&auth_ts=1700000000

签名结果：

9c5b66b43527979012af97bbe6b1818680be874f39c4c4e0ef9bca513bbeed72

若使用相同样例参数无法得到上述签名结果，请参见第 10.1 节排查。

6. 签名代码示例

以下示例仅供参考，请结合实际开发语言规范进行调整。

6.1 PHP

6.2 Java

7. 有效期与浏览器绑定

7.1 首次使用有效期

签名首次使用时，必须满足：

0 <= 平台服务器当前时间 - auth_ts <= 180 秒

即签名首次使用的有效期为 3 分钟。平台不接受未来时间戳，也不提供额外的时钟偏差兼容。

请确保生成签名所在服务器的系统时间准确，建议开启 NTP 时间同步。由于有效期仅 3 分钟，签名应在观众即将进入观看页时实时生成，不适合提前批量生成后延时分发。

7.2 同一浏览器刷新

签名首次验证成功后，会与当前浏览器完成绑定：

同一浏览器内刷新观看页时，可继续使用原签名。

浏览器绑定的有效期为首次验证成功后的 2 天，且不因刷新而延长。

绑定有效期内，即使原 auth_ts 已超过 3 分钟，同一浏览器仍可正常完成验证。

当 app_key、webinar_id、email、auth_ts 或 auth_sign 任一参数发生变化时，原有的浏览器绑定结果不再适用。

7.3 链接复制与多浏览器观看

将已使用过的嵌入观看链接复制到其他浏览器访问，签名验证会失败。

同一邮箱需在其他浏览器观看时，主办方服务端应重新生成一份新签名。

不同签名可以基于同一邮箱生成，因此同一观众可以在多个浏览器中分别观看。

8. 应用状态与配置生效时间

平台在校验签名的同时，还会检查生成签名所用的应用，确认 app_key 是否存在、是否处于启用状态，以及是否归属于活动所属的主办方账号。

平台对应用信息存在短时缓存，配置变更后按以下时间生效：

删除或禁用应用后，相关变更最长可能延迟 5 分钟生效。

即使签名已在某浏览器绑定成功，后续访问仍会持续检查该应用的状态与归属。

9. 失败处理

当第 3 节第 6 步的验证失败时，观众将在观看页看到失败提示，无法进入直播间。平台将失败原因归为以下错误码：

错误码	默认提示（观看页展示文案）	常见场景
`512627`	无法观看，主办方设置了验证方式	通过普通观看页、SDK 或其他非嵌入入口访问开启了三方授权的活动。
`512628`	您不符合观看要求	参数缺失、邮箱为空、时间戳无效、应用无效或归属错误、签名错误、签名已绑定其他浏览器等。

补充说明：

主办方可在活动观看限制配置中自定义观看失败提示，最长 50 个字符；未配置时使用系统默认提示“您不符合观看要求”。

出于安全考虑，平台不会向观众区分签名错误、应用错误、时间戳过期或浏览器绑定冲突等具体失败原因。主办方应在服务端记录必要的请求标识用于排查，但不得记录 secret_key。

10. 常见问题

10.1 为什么签名结果不一致？

请依次检查：

auth_ts 是否为秒级时间戳，而非毫秒时间戳。

字符串字段 app_key、email 是否已 trim；整型字段无需 trim。

是否使用 RFC 3986 编码，而非表单编码；是否对已编码结果二次编码。

字段顺序是否为 app_key、webinar_id、email、auth_ts。

是否使用 HMAC-SHA256，而非普通 SHA-256。

是否输出完整的 64 位小写十六进制字符串。

是否误将 secret_key 拼入签名原文。

10.2 `email` 是否可以省略？

不可以。email 去除首尾空白后必须非空，且必须是合法邮箱地址。

10.3 前端可以直接生成签名吗？

不可以。签名必须由主办方服务端生成；若在前端生成，secret_key 将面临泄露风险。

10.4 活动同时开启三方 K 值时应如何处理？

可以同时配置。三方 K 值是平台提供的另一项观看校验能力，与三方授权相互独立，其开启与配置方式参见相关文档。当活动同时开启两者时，观众需分别通过两项验证，方可观看。

11. 联调检查清单

上线前建议完成以下检查：

前置配置

应用已启用，且归属于活动所属的主办方账号

活动的观看限制已设置为“三方授权”

使用嵌入观看页进行联调

secret_key 仅保存在服务端

签名实现

email 必填且为合法邮箱

字符串字段 app_key、email 已执行 trim

auth_ts 使用秒级时间戳

签名字段顺序与 RFC 3986 编码正确，未对已编码结果二次编码

签名结果为完整的 64 位小写十六进制字符串

使用本文固定样例验证本地签名实现

业务验证

验证首次使用 3 分钟边界

验证同浏览器刷新可继续观看

验证复制链接到其他浏览器后不可观看

验证同一邮箱使用新签名可在其他浏览器观看

验证应用禁用或删除后的处理结果

验证默认失败提示与活动自定义失败提示

三方授权观看限制对接文档#

名词约定#

1. 功能说明#

1.1 能力概述#

1.2 限制说明#

2. 对接前提#

3. 对接流程#

4. 嵌入观看页签名参数#

5. 签名规则#

5.1 签名算法#

5.2 参数预处理#

5.3 签名原文固定顺序#

5.4 签名样例#

6. 签名代码示例#

6.1 PHP#

6.2 Java#

7. 有效期与浏览器绑定#

7.1 首次使用有效期#

7.2 同一浏览器刷新#

7.3 链接复制与多浏览器观看#

8. 应用状态与配置生效时间#

9. 失败处理#

10. 常见问题#

10.1 为什么签名结果不一致？#

10.2 email 是否可以省略？#

10.3 前端可以直接生成签名吗？#

10.4 活动同时开启三方 K 值时应如何处理？#

11. 联调检查清单#