动态身份验证
动态身份验证
您的 API 可能需要动态身份验证,其中凭据需要为每个请求生成或刷新,例如签名短期 JWT 或轮换令牌。Python SDK 通过方法重写支持这种模式。
方法重写模式
对于 Python SDK,您可以通过扩展生成的客户端并重写方法来注入身份验证逻辑来实现动态身份验证。
示例:短期 JWT 签名
以下是如何为 Python SDK 实现 JWT 签名:
这种方法需要单独重写每个方法。您需要重写所有进行 API 调用的方法,以确保 JWT 身份验证在您的 SDK 中一致应用。
其他身份验证模式
这种相同的模式适用于其他动态身份验证场景:
- OAuth 令牌刷新:在每个请求之前自动刷新过期的访问令牌
- HMAC(基于哈希的消息认证码)签名:基于请求内容使用 HMAC 签名对请求进行签名
- 轮换 API 密钥:基于速率限制在多个 API 密钥之间切换
- 基于时间的令牌:生成包含时间戳或随机数的令牌
重要注意事项
安全注意事项
- 安全密钥存储:绝不要硬编码私钥;使用环境变量或安全的密钥管理系统
- 避免双重身份验证:如果您的 API 在 Fern 定义中已经使用了 bearer token 身份验证,请注意不要覆盖现有的
Authorization标头。考虑使用不同的标头名称或有条件地设置标头
性能
- 令牌记忆化:考虑缓存令牌以避免在每个请求上重新生成它们。您可以添加一个简单的缓存,在令牌过期之前刷新令牌
- 宽限期:在令牌过期前稍早刷新令牌(例如,提前 2 秒)以避免令牌在请求处理期间过期的边缘情况
标头合并
- 保留现有标头:在注入身份验证标头时,始终与现有标头合并,以避免覆盖 SDK 或用户设置的标头
- 请求选项:Python SDK 接受
request_options作为关键字参数,可以包含自定义标头
时间同步
- 时钟偏移:注意客户端和服务器之间潜在的时钟偏移。考虑为您的令牌过期检查添加容差
- 时间戳精度:为
iat和exp声明使用 Unix 时间戳(自纪元以来的秒数)以匹配 JWT 标准
最佳实践
- 重写所有方法:确保您重写所有 API 方法以在您的 SDK 中保持一致的身份验证
- 适当缓存令牌:在安全性(更短的令牌生命周期)和性能(较少的重新生成频率)之间取得平衡
- 优雅地处理错误:为身份验证失败和令牌刷新错误实现重试逻辑
- 彻底测试:确保您的包装器处理所有边缘情况,包括并发请求、令牌过期和网络故障
- 监控令牌使用:记录令牌生成和刷新事件以帮助调试生产环境中的身份验证问题