系统设计：API密钥认证 - 作者：Alexander - 发布于Substack

API密钥认证的系统设计

API密钥是一种常见的Web API身份验证机制。表面上看，它通过创建唯一密钥并将其分配给API使用者，提供了一种简单且可靠的调用方验证方式。然而，在基于面向服务设计原则构建的系统中，这一问题已被多次以不同方式解决。

本文将介绍一种经过实践验证的API密钥认证参考实现，该实现已成功应用于多个项目，支持数百万调用者，并经受住了产品生命周期的考验。

API密钥的基本原理

API密钥由服务器端生成并传递给API调用方。随后，密钥会被转换并存储在安全的数据存储中，仅供授权机构和验证器访问。以下是API密钥的核心原则：

• 密钥的安全性：存储的数据必须允许引用，但不得允许重建密钥本身。密钥的秘密部分仅由API调用方知道，API管理机构在密钥交付后不应知晓其内容。这与系统不应存储用户密码的原则类似。
• 请求中的携带方式：API密钥必须包含在每个请求中。在HTTP环境中，通常通过Authorization或x-API-Key等请求头字段传递密钥。如果使用Authorization字段，建议在密钥前添加标识符，以便与JWT等其他认证方式区分。

API密钥的生成与存储

1. 创建API密钥对

• 生成密钥ID：创建一个唯一标识符，用于标记该密钥。
• 生成秘密部分：创建密钥的秘密部分，用于身份验证。

2. 存储密钥

• 密钥转换：通过argon2密钥推导函数对秘密部分进行转换，确保其安全性。
• 数据存储：将密钥ID（明文）、argon2密钥哈希以及其他可选信息（如租户、计费账户、到期时间等）存储在数据存储中。

3. 密钥交付

• 密钥格式化：使用分隔符将密钥ID和秘密部分连接成一个字符串。分隔符需确保唯一性，且不属于密钥生成算法的字符集。
• 密钥传输：将格式化后的密钥传递给调用方。
• 激活密钥：调用方验证密钥并将其状态从“挂起”改为“活动”。

API密钥的验证流程

1. 调用方发起请求：使用包含API密钥的请求（如HTTP请求头）。
2. 解析密钥：被调用方从请求中提取密钥，并拆分为密钥ID和秘密部分。
3. 查找密钥信息：根据密钥ID在数据存储中查找相关信息。
4. 验证密钥：使用请求中的秘密部分验证存储中的argon2哈希。
5. 授权请求：验证成功后，清除请求中的API密钥信息，并将请求转发给处理程序；验证失败则拒绝请求。

密钥轮换机制

密钥轮换是API密钥认证中至关重要的安全特性。以下是密钥轮换的基本流程：

1. 发起轮换：调用方使用旧密钥（A）发起密钥轮换请求。
2. 标记新密钥：将新密钥（B）标记为“挂起”状态，并将其设为旧密钥（A）的继任者。
3. 完成轮换：调用方使用新密钥完成轮换操作。
4. 更新调用：从此之后，所有API调用均使用新密钥（B）。

API密钥的结构与设计原则

密钥结构

• API_KEY_ID：密钥的唯一标识符，用于服务执行、调试和跟踪。
• 分隔符：用于分隔密钥ID和秘密部分的字符，需确保唯一性。
• API_KEY_SECRET：密钥的秘密部分，是安全的核心信息，不得记录、显示或转发。

设计原则

• 模块化设计：将认证子系统独立为单独的服务，或通过中间件与业务逻辑结合。
• 信息隔离：在请求处理前，移除原始API密钥，避免泄露敏感信息。
• 高效存储：密钥存储需支持快速查找，同时确保安全性。

API密钥与JWT的对比

JWT的特点

• 优势：JWT允许将信息存储在令牌中，并在服务器端验证其完整性和有效性，避免每次请求都查找数据库。
• 缺点：JWT中的信息通常不加密，可能暴露敏感数据；此外，JWT一旦泄露，难以撤销。

适用场景

• JWT：适用于用户对系统的身份验证。
• API密钥：更适合系统对系统的身份验证。

安全性与最佳实践

1. 日志保护：避免记录明文API密钥，可通过定制日志记录方式隐藏敏感信息。
2. 高熵密钥生成：确保密钥生成算法具有高熵，避免可预测模式。
3. 入侵检测：通过异常行为警报和限制生产系统访问，提升安全性。
4. 密码哈希参数：存储哈希时包含算法参数，支持验证旧密钥的同时更新算法。

总结

API密钥认证是一种高效且安全的身份验证机制，适用于系统间的交互。通过合理的密钥生成、存储和验证流程，以及密钥轮换和安全设计的最佳实践，可以有效提升系统的安全性和可扩展性。在实际应用中，根据具体需求选择合适的认证方式（如JWT或API密钥），并结合完善的安全策略，能够为系统提供可靠的保护。

原文链接: https://substack.com/home/post/p-151514611