增强 Webhook 安全性
我们不断致力于提升开发者体验和 Messaging API 的安全性,并荣幸地宣布已将 Webhook 签名验证功能添加到 Messaging API 文档中。截至本次更新:
-
该文档现在完整解释了机器人服务器在从 LINE 平台接收 webhook 请求时应如何验证 webhook 签名。
-
开发人员指南已更新,将签名验证作为推荐的最佳实践之一。
为什么签名验证如此重要🚨
当用户与官方帐户进行交互时(通过将其添加为好友、发送消息或单击丰富的菜单操作),LINE 平台会向Webhook URL
LINE 开发者控制台中配置的 HTTP POST webhook 发送。
然而,通过公共网络传输的 Webhook 可能会被伪造、重放或篡改。如果不验证来源和完整性,恶意攻击者可能会伪造请求或更改 Webhook 负载来误导您的机器人。
通过验证 HTTP 标头中包含的签名,您的服务器证明:
-
该消息确实来自 LINE。
-
请求在传输过程中未被更改。
-
您可以放心地信任和处理随附的事件数据。
跳过此步骤可能会使您的机器人面临安全漏洞、网络钓鱼威胁和数据完整性问题。
Webhook 安全性 签名验证工作流程概述
以下是端到端的概述:
-
LINE 平台使用您频道的频道密钥和 HMAC-SHA256 算法对每个 webhook 有效负载进行签名。
-
生成的签名经过 base64 编码并添加到
X‑LINE‑Signature
webhook 请求的 HTTP 标头中。 -
收到 webhook 后,您的机器人会:
-
读取原始请求主体(JSON)。
-
使用您的频道密钥计算其自己的 HMAC-SHA256 摘要。
-
对摘要进行 Base64 编码并将其与提供的
X-LINE-Signature
标头进行比较。
-
-
如果签名匹配,则表示该 Webhook 已通过身份验证且未被篡改。如果签名不匹配,则拒绝该请求并返回 HTTP 400 Bad Request 响应。
这确保了消息的真实性、数据的完整性和安全的 webhook 处理。
必要的准备工作
在验证签名之前,请确保您具有以下内容:
-
频道秘密
-
登录 LINE 开发者控制台并打开您的频道。
-
在基本设置部分下,复制频道机密。
-
将其安全地存储在您的服务器上(例如,环境变量或秘密管理器)。
-
-
原始请求主体访问
-
签名必须使用精确的原始 JSON 主体来计算,不得修改。
-
避免使用解析、格式化或转换正文的中间件(例如自动 JSON 解析器或额外填充)。
-
例如,在 Express.js 中:
jsapp.post('/callback', bodyParser.json({ verify: (req, res, buf) => {
req.rawBody = buf;
}}), (req, res) => { /* signature logic */ });
-
保留
req.rawBody
以进行签名验证。
-
-
HMAC‑SHA256 加密支持
-
确保您的服务器语言/平台支持 HMAC-SHA256 和 Base64 编码(大多数主要环境都支持)。
-
逐步签名验证
1. 检索签名头
从请求中获取签名字符串:
X‑LINE‑Signature: O2XwJaj5tLbi...
如果缺少标头,则立即使用 HTTP 400 状态代码进行响应。
2. 重新计算签名
计算原始主体的 HMAC:
const hmac = crypto.createHmac('sha256', CHANNEL_SECRET);
hmac.update(req.rawBody); // Buffer or string precise
const computedSignature = hmac.digest('base64');
3. 比较签名
使用恒定时间比较方法来避免时序攻击:
if (!crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(req.get('X‑LINE‑Signature')))) {
return res.sendStatus(400);
}
如果不匹配,则拒绝该请求。
4. 匹配成功后,处理有效载荷
仅当签名经过验证时,您的代码才应该:
const events = JSON.parse(req.rawBody.toString()).events;
for (const event of events) {
// handle each event
}
res.sendStatus(200);
在签名验证发生之前切勿处理有效载荷事件。
常见签名失败及提示
以下是一些常见的验证问题及其补救措施:
-
渠道秘密不匹配
请从开发者控制台验证您使用的是正确的渠道秘密。 -
更改的请求主体
确保签名计算使用收到的精确 JSON 字节,并且不进行格式更改。 -
错误的哈希方法
仅支持 HMAC-SHA256。 -
缺少或格式错误的标头如果标头缺少或为空,
则提前拒绝请求。X-LINE-Signature
-
空格或编码问题
使用恒定时间缓冲区比较来避免隐藏的差异,例如尾随换行符或编码不匹配。 -
中间件干扰
对您的主体解析器进行排序,以便在其他转换之前捕获原始数据。
这些因素中的每一个都可能导致签名不匹配;确保您的实现正确处理它们。
更新的开发指南(最佳实践)
为了增强安全性,我们更新的消息传递 API 开发指南现在包括:
-
处理之前务必验证 webhook 签名。
-
立即丢弃或忽略无效的 webhook 请求。
-
不要通过可公开访问的代码或客户端捆绑包泄露您的频道秘密。
-
记录失败的验证尝试,但绝不会在日志中暴露未经清理的第三方输入。
-
如果渠道机密遭到泄露,则定期轮换渠道机密,并相应地更新正在运行的机器人。
遵守这些做法可以增强您的机器人的安全态势。
其他安全注意事项
您可以进一步强化您的 webhook 系统:
-
IP 允许列表:仅接受来自 LINE 平台 IP 范围的 webhook。
-
重放保护:检查 POST
timestamp
或包含您自己的nonce
机制。 -
TLS 强制执行:始终使用具有有效证书的 HTTPS。
-
安全存储:将机密存储在安全的保险库和环境变量中,并避免使用纯文本配置文件。
-
弹性措施:及时响应 LINE软件的 5 秒超时要求,以避免传送失败。
这些措施与签名验证相结合,构建了一个强大的 webhook 端点。
鼓励所有开发人员实施
将 Webhook 签名验证添加到 Messaging API 文档中,是我们致力于帮助开发者构建安全可靠的机器人的承诺之一。验证签名可确保:
-
您的服务器仅处理真实、未篡改的消息
-
针对 Webhook 端点的潜在攻击媒介被阻止
-
开发人员有信心信任他们的机器人基础设施
我们鼓励所有开发人员实施这些步骤,升级到最新的文档和库,并遵循我们更新的安全 webhook 处理指南。
我们将一如既往地致力于在未来进一步完善文档和工具。如果您遇到问题或有任何改进建议,请通过 LINE 开发者支持渠道联系我们。