事后分析：意外的 JWT `iss` 变更

概述#

在 2024-03-18，Logto Cloud 中的一次更新改变了 JWT 签发者行为，导致具有自定义域和 iss 验证的用户的认证流程中断。解决该问题需要这些用户更新其验证逻辑。

• 受影响的用户：启用了自定义域并执行 iss 验证的用户。
• 严重性：严重，破坏了认证流程中的 iss 验证。

根本原因#

本次更新将 iss 字段更改为匹配请求的域，破坏了原来期望默认签发者的现有验证。

时间线#

• 2024-03-18 10:00 (UTC)：更新部署，改变 iss 行为。
• 2024-03-18 23:30 (UTC)：收到第一个用户报告，现有行为中断。
• 2024-03-19 12:00 (UTC)：确认问题并开始调查。
• 2024-03-19 14:00 (UTC)：确定根本原因和影响。
• 2024-03-20 20:00 (UTC)：准备发送给受影响用户的电子邮件。
• 2024-03-20 06:00 (UTC)：发送电子邮件给所有受影响的用户。

影响分析#

发布详情#

Logto Cloud 支持自定义域进行认证，启用自定义域的租户开发者可以在 SDK 中将终端设置为自定义域，然后最终用户将使用这个终端来初始化认证过程并获取令牌。一些令牌是以 JWT 形式存在的，其中包括一个 iss 字段来指示这个令牌的签发者。之前，即使使用自定义域终端请求访问令牌，签发者仍默认是我们的标准域([tenant-id].logto.app)。

然而，签发者的域应该与请求终端相同。因此，我们发布了一次更新来修复这个问题，现在 iss 字段将自动反映请求中使用的域。

对于那些已经在使用自定义域授予令牌并在资源服务器中实现了 iss 字段验证的用户而言，这可能是一个重大变更。由于签发者的更改，现有的认证检查将失败。为了解决这个问题，开发者需要更改验证代码，用自定义域替换预期的签发者。

我们未能充分考虑对现有 iss 验证的影响，结果是这次发布在没有提前通知的情况下成为一个重大变更。

解决方案#

通过电子邮件通知受影响的用户，建议他们更新 iss 验证以匹配请求的域。

回滚？#

该变更是签发者字段的必要修复，一些用户可能已经适应了新的行为。回滚会导致混乱和不一致。

经验教训#

• 影响核心认证的代码修改必须得到团队的批准，除了常规审核之外。
• 自动化测试应该涵盖更多案例，特别是在云特定的场景中。

纠正和预防措施#

• 添加集成测试：为此次事件中的场景添加测试案例。
• 功能监控项目：除了 Logto Cloud 之外，还创建我们自己的附属项目，并与 Logto 深度集成，以在发布前捕获潜在问题。