Open edX 平台认证模式标准化JwtAuthentication 统一 DRF API 认证方案的技术决策与实践【免费下载链接】openedx-platformThe Open edX LMS Studio, powering education sites around the world!项目地址: https://gitcode.com/GitHub_Trending/ed/openedx-platform导读Open edX 平台的 REST API 长期存在多种认证机制并存、安全方案声明与实际认证行为不一致的问题导致外部集成方难以判断该用哪种方式认证、内部团队难以维持统一的认证模式。本文基于 Open edX 平台 ADR0034-unify-auth-oauth2-dot-v2其应用级索引位于 openedx/core/djangoapps/oauth_dispatch/docs/decisions/0017-standardize-authentication-patterns.rst系统讲解平台的认证标准化决策以JwtAuthentication作为所有用户认证型 DRF 端点的统一标准弃用BearerAuthentication系列类并给出完整的端点迁移方案、代码示例与回滚计划。读完本文你将掌握如何在 Open edX 中正确配置认证类、如何审计并迁移既有端点以及迁移过程中的关键注意事项。背景Open edX 认证模式为何需要标准化历史遗留的认证不一致问题Open edX 平台本仓库openedx-platform的 API 层长期存在以下认证混乱状况多种认证机制全局启用但应用不一致平台默认开启了多个认证类但各端点实际生效的组合参差不齐安全方案声明与实际认证行为脱节API 文档中声明的认证方案与端点真正接受的认证方式不一致外部集成方无法可靠预判认证方式开发者不知道该实现 OAuth2、JWT 还是 Bearer 中的哪一种内部 API 混合使用认证机制缺乏清晰、可复用的模式约束。这一问题同时影响外部开发者、内部维护团队、安全审查与合规评估以及依赖可预测认证行为的自动化工具因而催生了本决策。两条并存的 JWT 签发路径在讨论认证之前需要先厘清一个常见混淆点OAuth2 与 JWT 在 Open edX 中并不是互斥的两套机制。Django OAuth ToolkitDOT签发的 OAuth2 access token 本身就是 JWT统一由JwtAuthentication校验。仓库中存在两条 JWT 签发路径定义于 openedx/core/djangoapps/oauth_dispatch/jwt.py签发函数用途特性create_jwt_token_dict()将 DOT OAuth2 access token 包装为 JWT有数据库记录支撑可撤销、可刷新面向外部客户端见 jwt.pycreate_jwt_for_user()直接为用户签发 JWT不经过 OAuth2 流程无数据库行、不可撤销、不可刷新面向内部服务间通信见 jwt.py被弃用的BearerAuthentication处理的是旧的 Bearer token与上述 JWT 机制完全不同二者不可混淆。核心决策五条标准化规则该 ADR 的决策主体可归纳为五条规则JwtAuthentication是唯一标准所有接收用户认证请求的 DRF API 端点必须统一使用JwtAuthentication依据 Open edX 提案 OEP-0042。此规则不适用于 admin 视图、/oauth2/access_token/端点以及 HMAC/webhook 端点——这些端点拥有各自独立的认证机制。JwtAuthentication与SessionAuthentication并行接受二者共同构成平台默认认证方案。真正被弃用的是BearerAuthentication家族。BearerAuthentication与BearerAuthenticationAllowInactiveUser弃用新代码中禁止使用。OAuth2Authentication与OAuth2AuthenticationAllowInactiveUser是弃用别名二者分别是BearerAuthentication系列的别名新代码同样禁止使用。新端点不得显式设置authentication_classes除非偏离平台默认值——平台默认已提供JwtAuthentication和SessionAuthentication偏离如纯 JWT 的服务间认证、或通过SessionAuthenticationAllowInactiveUser允许非活跃用户会话访问必须显式声明并加注释说明。既有 API 必须审计并移除BearerAuthentication。平台默认认证配置与源码印证DEFAULT_AUTHENTICATION_CLASSES平台默认认证类配置位于 openedx/envs/common.pyDEFAULT_AUTHENTICATION_CLASSES: [ openedx.core.djangolib.default_auth_classes.DefaultJwtAuthentication, openedx.core.djangolib.default_auth_classes.DefaultSessionAuthentication, ],这两个默认类的定义位于 openedx/core/djangolib/default_auth_classes.pyDefaultSessionAuthentication继承自标准SessionAuthentication会通过 session 拦截非活跃用户DefaultJwtAuthentication继承自JwtAuthentication用于过渡期行为追踪。当前违规的认证配置ADR 明确指出当前view_auth_classes装饰器openedx/core/lib/api/view_utils.py的配置违反了 OEP-0042——它同时启用了 JWT、已弃用的 Bearer 和 sessionfunc_or_class.authentication_classes ( JwtAuthentication, BearerAuthenticationAllowInactiveUser, # deprecated per OEP-0042 SessionAuthenticationAllowInactiveUser )从当前仓库源码看view_auth_classes在 content_libraries/rest_api、content_staging/views.py、olx_rest_api/views.py、xblock/rest_api/views.py 等多处被引用是迁移的主战场之一——ADR 提到一次修改即可覆盖 49 个端点。被弃用的 BearerAuthentication 实现细节BearerAuthentication系列定义于 openedx/core/lib/api/authentication.py基于oauth2_providerDjango OAuth Toolkit校验 access tokenBearerAuthentication从请求的Authorization头解析Bearer前缀通过dot_models.AccessToken查询 token 记录见 authentication.py校验过期时间token.expires now()并检查用户是否活跃allow_inactive_users False未确认邮箱的用户会被拒绝BearerAuthenticationAllowInactiveUser覆写allow_inactive_users True允许未验证邮箱的用户访问历史上用于移动端端点OAuth2Authentication/OAuth2AuthenticationAllowInactiveUser仅为兼容仓库外部引用而存在的临时别名见 authentication.py外部仓库迁移完成后应一并移除。端点迁移方案与代码示例迁移的通用规则新端点不显式设置authentication_classes直接依赖DEFAULT_AUTHENTICATION_CLASSES提供的DefaultJwtAuthentication与DefaultSessionAuthentication既有端点目标是从authentication_classes元组中移除BearerAuthentication剩余内容取决于端点现状当前认证类组合迁移后目标(JwtAuthentication, BearerAuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)(JwtAuthentication, SessionAuthenticationAllowInactiveUser)(BearerAuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)(JwtAuthentication, SessionAuthenticationAllowInactiveUser)显式例外必须注释说明偏离理由服务间service-to-service端点若必须排除 session 认证可写为authentication_classes (JwtAuthentication,)。示例一标准 API——仅移除 Bearer以 lms/djangoapps/course_home_api/dates/views.py 的DatesTabView为例当前状态为# Current state authentication_classes ( JwtAuthentication, BearerAuthenticationAllowInactiveUser, # to be removed per Decision #3 SessionAuthenticationAllowInactiveUser, )目标状态为仅移除BearerAuthentication其余保持不变# Target state — remove BearerAuthentication; keep the rest unchanged. authentication_classes ( JwtAuthentication, SessionAuthenticationAllowInactiveUser, )示例二MFE/浏览器 API——添加 JWT 并移除 Bearer以 lms/djangoapps/teams/views.py 的TeamsDashboardView为例面向 MFE/浏览器场景当前状态为# Current state authentication_classes ( BearerAuthenticationAllowInactiveUser, # to be removed per Decision #3 SessionAuthenticationAllowInactiveUser, )目标状态为按决策第 1 条添加JwtAuthentication、按决策第 3 条移除BearerAuthentication# Target state — add JwtAuthentication per Decision #1; remove BearerAuthentication. authentication_classes ( JwtAuthentication, SessionAuthenticationAllowInactiveUser, )迁移中的关键实现注意事项JwtAuthentication默认不检查user.is_active它默认允许非活跃用户SessionAuthenticationAllowInactiveUser同样跳过活跃用户检查。需要强制校验用户活跃状态的端点应使用权限类permission class而非认证类。保留SessionAuthenticationAllowInactiveUser的显式声明已使用该类的端点迁移时必须保留——若完全移除认证类覆写会静默切换到默认的DefaultSessionAuthentication它通过 session 拦截非活跃用户从而改变端点行为。view_auth_classes是主迁移目标该装饰器的一次改动即可批量移除 49 个端点中的BearerAuthentication。迁移前核实外部客户端从任何端点移除BearerAuthentication之前必须确认没有活跃的外部客户端仍在使用 Bearer token。JWT_AUTH_ADD_KID_HEADER开关已过期定义于 openedx/core/djangoapps/oauth_dispatch/jwt.py原定于 2024-04-20 移除当前应将其设为常开KID header 恒存在 JWK 头部并删除该开关。平台中的实际落地范围OAuth2/DOT 与认证现状OAuth2/DOT 在 edx-platform 中的位置LMS 使用 Django OAuth Toolkit挂载于/oauth2/路径配置见 lms/urls.py实现见 openedx/core/djangoapps/oauth_dispatch。关键设置包括OAUTH2_PROVIDER_APPLICATION_MODEL指定 DOT 的 Application 模型OAUTH2_VALIDATOR_CLASS如EdxOAuth2Validator控制 token 校验逻辑DOT 通过create_jwt_token_dict()将 access token 以 JWT 形式签发。本仓库内的关联 ADRoauth_dispatch 应用内还记录了与认证演进相关的历史决策可对照阅读0006-enforce-scopes-in-LMS-APIs.rstLMS API 中强制 scope 的历史决策0013-mobile-migration-to-jwt.rst移动端迁移到 JWT 的历史决策。决策后果评估收益Pros各 API 用例的认证模式清晰、可预测认证机制得到正确分离安全性提升对齐 OEP-0042将弃用的BearerAuthentication移出活跃使用外部开发者集成更简单统一标准JWT内部服务通信更简化共用同一JwtAuthentication类浏览器端获得更好的会话认证体验。代价Cons/Costs既有 API 需要审计与重构以匹配新模式团队需要理解并正确选择认证方式何时用 JWT、何时用 session仍在使用 Bearer token 的外部客户端必须迁移到 JWT当前混合使用认证机制的服务需要投入迁移成本token 过期时间差异视配置而定Bearer token 有效期约 2 周而 JWT 约 1 小时——迁移后长时间运行但不检查过期时间的任务若复用了旧 token将开始失败。回滚计划Rollout Plan审计既有 API 并分类标记所有使用BearerAuthentication系列变体的端点移除过期的JWT_AUTH_ADD_KID_HEADER开关将 KID header 设为常开。与BearerAuthentication弃用和移除相关的其余步骤监控活跃使用情况、在源码中标记弃用、迁移外部客户端、token 过期考量、第三方沟通等统一跟踪在 edx-drf-extensions 的DEPR: BearerAuthentication工单中对应仓库 openedx/core/djangoapps/oauth_dispatch/docs/decisions/0017-standardize-authentication-patterns.rst 中引用的工单。参考文档索引平台级 ADR 全文docs/decisions/0034-unify-auth-oauth2-dot-v2.rst应用级决策索引openedx/core/djangoapps/oauth_dispatch/docs/decisions/0017-standardize-authentication-patterns.rst认证类实现openedx/core/lib/api/authentication.py视图认证装饰器openedx/core/lib/api/view_utils.py平台默认认证类openedx/core/djangolib/default_auth_classes.pyJWT 签发工具openedx/core/djangoapps/oauth_dispatch/jwt.py平台默认 DRF 配置openedx/envs/common.py标准 API 迁移示例lms/djangoapps/course_home_api/dates/views.pyMFE/浏览器 API 迁移示例lms/djangoapps/teams/views.py【免费下载链接】openedx-platformThe Open edX LMS Studio, powering education sites around the world!项目地址: https://gitcode.com/GitHub_Trending/ed/openedx-platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考