Django REST framework SimpleJWT 中使用自定义用户ID字段导致黑名单刷新令牌失败的解决方案

问题背景

在使用Django REST framework SimpleJWT进行JWT认证时，许多开发者会选择自定义用户模型。一个常见场景是使用UUID而非传统的自增整数作为用户主键。然而，当配置了USER_ID_FIELD为自定义字段(如UUID)并启用令牌黑名单功能时，可能会遇到一个隐蔽的错误。

错误现象

当配置如下时：

SIMPLE_JWT = {
    'USER_ID_FIELD': 'uuid',  # 使用UUID字段而非默认的id
    'ROTATE_REFRESH_TOKENS': True,  # 启用刷新令牌轮换
    'BLACKLIST_AFTER_ROTATION': True,  # 轮换后将旧令牌加入黑名单
    # 其他配置...
}

在调用TokenRefreshView刷新令牌时，系统会抛出HTTP 500错误，核心错误信息为：

ValueError: Field 'id' expected a number but got '4faf8673-02f5-4a1d-8994-dd76adab934a'

问题根源分析

这个问题的本质在于SimpleJWT的黑名单机制实现方式。当启用BLACKLIST_AFTER_ROTATION时，系统会尝试将旧的刷新令牌存入黑名单。在这个过程中：

1. 令牌中存储的是配置的USER_ID_FIELD值(本例中是UUID字符串)
2. 但OutstandingToken模型的user字段默认关联的是Django的User模型的主键(通常是自增ID)
3. 系统直接尝试将UUID字符串赋值给期望数字ID的字段，导致类型不匹配错误

解决方案

官方修复方案

在SimpleJWT 5.5.0版本中，这个问题已被修复。升级到最新版本是最简单的解决方案：

pip install djangorestframework-simplejwt --upgrade

手动修复方案

如果暂时无法升级，可以创建自定义的Token类来修复这个问题：

from rest_framework_simplejwt.tokens import RefreshToken
from django.contrib.auth import get_user_model

class CustomRefreshToken(RefreshToken):
    def blacklist(self):
        jti = self.payload[api_settings.JTI_CLAIM]
        exp = self.payload["exp"]
        user_id = self.payload.get(api_settings.USER_ID_CLAIM)

        # 修复：通过USER_ID_FIELD查找用户对象
        user = get_user_model().objects.get(**{api_settings.USER_ID_FIELD: user_id})
        
        token, _ = OutstandingToken.objects.get_or_create(
            jti=jti,
            defaults={
                "user": user,  # 直接使用用户对象而非ID
                "created_at": self.current_time,
                "token": str(self),
                "expires_at": datetime_from_epoch(exp),
            },
        )

        return BlacklistedToken.objects.get_or_create(token=token)

然后在配置中指定使用自定义的Token类：

SIMPLE_JWT = {
    'REFRESH_TOKEN_CLASS': 'path.to.CustomRefreshToken',
    # 其他配置...
}

最佳实践建议

1. 保持SimpleJWT版本更新：定期检查并更新到最新版本，可以避免许多已知问题

2. 自定义用户模型设计：

   • 如果使用UUID作为主键，建议直接设置id = models.UUIDField(primary_key=True)
   • 这样系统各处都会统一使用UUID，避免类型不一致问题

3. 测试策略：

   • 在启用黑名单功能前，务必进行充分的测试
   • 特别关注令牌刷新和黑名单场景

4. 监控机制：

   • 在生产环境部署后，监控认证相关的500错误
   • 设置告警机制，及时发现类似问题

总结

这个问题展示了在使用自定义用户模型时可能遇到的典型兼容性问题。通过理解Django的用户认证机制和SimpleJWT的工作原理，开发者可以更好地预见和解决这类问题。随着SimpleJWT项目的持续更新，这类边界情况会得到更好的处理，但掌握其底层原理仍然对开发高质量的认证系统至关重要。