Wagtail v3 API 认证指南Bearer Token 的创建、安全模型与权限管控【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail本文基于 Wagtail 仓库的官方文档 v3 API authentication 展开系统讲解 Wagtail API v3 的 Bearer Token 认证机制如何携带令牌发起请求、如何通过管理后台与命令行创建令牌、令牌的 HMAC 摘要存储与SECRET_KEY轮换机制、撤销与审计记录的生命周期管理以及令牌即用户的权限模型与多级管理门槛。读完本文你将能安全地为自己或服务账号签发 API 令牌并在生产环境中正确地轮换密钥、审计令牌使用与回收令牌。v3 API 的认证模型令牌绑定用户权限与后台一致Wagtail v3 API位于 wagtail/api/v3使用Bearer Token不记名令牌认证请求。核心设计是每个令牌都绑定到一个用户账号API 请求以该用户的身份执行并继承该用户全部 Wagtail 权限——这与在后台界面操作时所使用的权限体系完全相同。这意味着你不需要为 API 单独维护一套权限规则一个用户能做什么他的令牌就能做什么。唯一的差异在于几个本文下面会提到的边界情况如匿名降级、令牌管理权限门槛等。从源码结构看这一认证逻辑由 wagtail/api/v3/auth.py 中的BearerTokenAuth类实现它继承自 Ninja 框架的HttpBearer接收Authorization: Bearer token请求头在APIToken表中按令牌摘要查找对应令牌再将request.user设置为令牌所属用户最后把令牌对象挂到request.auth上供后续使用。携带令牌发起请求在每个请求的Authorization请求头中发送令牌即可完成认证curl -H Authorization: Bearer wagtail_… https://example.com/api/v3/whoami/用/whoami/端点验证令牌GET /api/v3/whoami/是一个专门用于验证令牌及其访问级别的端点返回当前认证用户的用户信息、个人资料profile和所属分组groups。该端点由 wagtail/api/v3/routers/whoami.py 实现返回结构如下{ user: { id: 1, username: deploy, email: deployexample.com, first_name: , last_name: , is_superuser: false }, profile: { avatar_url: null }, groups: [Editors] }其响应中的WhoAmISchema定义了user、profile、groups三个字段用户字段包含id以字符串形式返回、username、email、first_name、last_name、is_superuserprofile 目前仅包含avatar_url取自已关联的wagtail_userprofilegroups是用户所属分组的名称列表。由于自定义用户模型可能没有email、first_name等字段实现中使用getattr(..., ) or 做了容错处理。/whoami/端点通过authBearerTokenAuth()声明必须认证访问——也就是说不带令牌访问它会返回未认证错误这与下面要讲的公开只读端点行为不同。匿名请求与认证失败静默降级公开的只读端点例如 pages、images、documents、redirects同时允许匿名访问和已认证访问。在这类端点上缺失令牌、无效令牌或被撤销的令牌一律被当作匿名请求处理不会返回 401 错误换言之认证失败不会让公开端点报错而是降级为匿名访问返回公开可读的内容。这一行为由 wagtail/api/v3/auth.py 中的AllowAnonymous类配合实现公开只读端点使用auth[BearerTokenAuth(), AllowAnonymous()]的组合——先尝试令牌认证失败则显式标记为匿名。源码中有一个值得注意的细节BearerTokenAuth.authenticate()在令牌无效或用户未激活is_active为假时会主动将request.user覆盖为AnonymousUser注释中明确说明这是为了覆盖 Django 认证后端例如 session设置的 user防止浏览器中登录后台的会话 cookie 意外抬升 API 请求的权限。即使一个已登录后台的编辑者带着自己的 session cookie 访问公开 API 端点API 仍只按匿名或令牌身份处理。创建令牌后台与命令行两种方式在管理后台创建只要INSTALLED_APPS中包含wagtail.api.v3拥有相应权限的用户即可在Settings设置→ API tokens下管理令牌。创建令牌时需要注意令牌明文只在创建那一刻显示一次之后系统只保存其摘要。页面会提示你立即将令牌复制并存放到安全位置关闭页面后便无法再查看原文。该后台管理界面由 wagtail/users/views/api_tokens.py 中的APITokenViewSet注册它挂载到设置菜单add_to_settings_menu True、使用key图标、菜单名为api_tokens管理 URL 前缀为api-tokens。列表页展示令牌前缀、名称、所属用户、创建时间、最后使用时间与撤销状态并提供按用户、创建时间、最后使用时间、是否已撤销等条件的过滤APITokenFilterSet。在命令行创建./manage.py api_tokens create --userdeploy --namedeploy bot该命令会直接打印令牌明文非常适合脚本化使用例如TOKEN$(./manage.py api_tokens create --userdeploy --nameci)需要结构化输出时加--json参数./manage.py api_tokens list用于列出令牌展示 ID、前缀、名称、所属用户、创建时间、最后使用时间、撤销状态api_tokens revoke则按--id或--user--prefix撤销令牌。该命令的实现位于 wagtail/management/commands/api_tokens.py共三个子命令各参数说明如下子命令参数说明create--user必填令牌所属用户的USERNAME_FIELD值--name必填令牌的显示名称/标签--json可选输出 JSON 对象而非裸令牌list--user可选只列出指定用户的令牌--include-revoked可选同时列出已撤销的令牌revoke--id令牌 ID与--user/--prefix二选一--user--prefix按用户与前缀定位令牌须同时提供--json输出的 JSON 对象包含token明文、prefix、name、user、created五个字段其中created为 ISO 8601 格式时间戳。revoke子命令要求--id或--user--prefix至少一组若前缀过短匹配到多个未撤销令牌命令会报错并提示Use a longer --prefix or --id防止误撤销。无论是后台还是 CLI 创建/撤销操作都会写入审计日志wagtail.apitoken.create/wagtail.apitoken.revokeCLI 操作额外记录data{source: management_command}。令牌安全模型只存摘要、前缀可识别、密钥可轮换只存储 HMAC-SHA-256 摘要数据库里保存的不是令牌明文而是每个令牌的 HMAC-SHA-256 摘要digest且摘要与你的SECRET_KEY绑定。令牌明文只存在于创建的那一刻create_token的返回值既不会写入数据库也不会被记录进日志。从 wagtail/models/api.py 可以看到具体机制hash_token()使用 Django 的salted_hmac以wagtail.apitoken为盐、SECRET_KEY为密钥、SHA-256 算法计算摘要key_hash字段存储该 64 字符十六进制摘要且设置了unique约束。这意味着即使数据库泄露攻击者也无法反向还原出可用令牌。wagtail_前缀与校验和令牌字符串带有wagtail_前缀和内置校验和checksum一方面让客户端和密钥扫描器secret scanner能够识别出这是 Wagtail API 令牌另一方面让系统可以离线快速校验令牌格式。generate_token()生成形如wagtail_secretchecksum的令牌secret 部分由 20 字节安全随机数secrets.token_bytes经 Base62 编码而来checksum 由 CRC32 计算并 Base62 编码。validate_token_format()则会离线检查前缀、总长度、字符集Base62与 CRC32 校验和且使用常量时间比较secrets.compare_digest防止时序攻击。格式校验失败说明令牌不可能存在校验通过也不代表令牌一定有效还需查库确认摘要匹配且未被撤销。轮换SECRET_KEY的注意事项由于摘要与SECRET_KEY绑定轮换密钥对既有令牌有直接影响使用SECRET_KEY_FALLBACKS平滑轮换在旧密钥被列入SECRET_KEY_FALLBACKS期间旧密钥签发的令牌仍然有效从SECRET_KEY_FALLBACKS中移除旧密钥后对应令牌才全部失效。这与 Django session 认证的轮换机制完全一致。不带 fallback 直接轮换如果直接更换SECRET_KEY而不保留任何 fallback所有令牌会一次性全部失效。背后的实现见APIToken.candidate_key_hashes()wagtail/models/api.py查询时按[SECRET_KEY, *SECRET_KEY_FALLBACKS]逐个计算候选摘要只要令牌是用当前密钥或任一 fallback 密钥签发的就能命中。相关测试位于 wagtail/api/v3/tests/test_auth.py分别覆盖了轮换后无 fallback 全部失效与轮换后 fallback 保留期间仍可用两种场景。令牌生命周期撤销留痕、审计可查、使用频率可控撤销是软删除保留审计线索撤销令牌后台界面或 CLI只是设置一个撤销时间戳revoked_at而不是删除数据库记录目的是保留完整的审计线索。APIToken.revoke()wagtail/models/api.py只做revoked_at timezone.now()这一件事后台的RevokeView在撤销后写入wagtail.apitoken.revoke审计日志并给出成功提示。token 的创建与撤销动作都会被记录在 审计日志 中可在后台侧边栏查看令牌的历史记录。令牌模型迁移文件见 wagtail/migrations/0098_apitoken.py包含user外键CASCADE删除、name、key_hash唯一、prefix、created、revoked_at、last_used_at七个字段。注意user采用级联删除用户被删除时其令牌也会一并删除。last_used_at节流写入令牌通过last_used_at时间戳记录使用情况但写入频率受到节流限制在WAGTAILAPI_TOKEN_LAST_USED_INTERVAL指定的间隔秒默认60内每个令牌最多只写一次数据库。# settings.py WAGTAILAPI_TOKEN_LAST_USED_INTERVAL 60 # 默认值实现见BearerTokenAuth._touch_last_used()wagtail/api/v3/auth.py当间隔为None时直接返回、不做任何写入否则仅当last_used_at为空或距上次写入已超过间隔时才通过QuerySet.update()更新一次避免在繁忙 API 上产生大量无意义的写操作。该设置也收录在 settings 参考文档WAGTAILAPI_TOKEN_LAST_USED_INTERVAL一节。将间隔设为None可完全禁用该写入例如在只读数据库上运行站点时WAGTAILAPI_TOKEN_LAST_USED_INTERVAL None # 完全禁用 last_used_at 写入权限模型令牌等于用户管理令牌另有门槛令牌的访问范围等于其用户令牌允许的访问级别与所绑定用户账号完全一致。因此文档建议慎重权衡两种用法直接使用真实用户账号签发令牌适合个人用途但令牌与真人账号绑定引入专用服务账号service account为 API 集成创建拥有最小权限集的独立用户令牌被泄露或需要下线时直接撤销令牌/停用账号不会影响任何真实用户。管理令牌自身的权限门槛令牌管理本身是权限受限的共分三层实现在 wagtail/users/utils.py 的user_can_manage_token()与get_manageable_token_owners()中操作所需权限附加约束管理自己账号的令牌wagtailcore对 API tokens 模型的add/change/delete权限可在Settings → Groups中分配无管理其他用户的令牌除上述权限外还需要用户模型user model的change权限该权限同时授予敏感账号管理能力如密码重置、分组管理务必谨慎管理**超级用户superuser**的令牌仅超级用户本人可以普通用户即使持有上述权限也无法管理超管的令牌从实现上看get_manageable_token_owners()的逻辑是拥有用户模型change权限的用户可管理除超级用户以外的所有用户非超管视角会过滤掉is_superuserTrue没有该权限的用户只能管理自己User.objects.filter(pkcurrent_user.pk)。user_can_manage_token()则在每次创建/撤销时做最终裁决普通用户对超管令牌的管理请求会被拒绝。快速上手清单确认INSTALLED_APPS中包含wagtail.api.v3并已执行迁移0098_apitoken会创建APIToken模型。为集成方创建服务账号最小权限集然后签发令牌./manage.py api_tokens create --userdeploy --nameci --json将令牌明文安全存放仅出现一次在请求头中携带curl -H Authorization: Bearer wagtail_… https://example.com/api/v3/whoami/用GET /api/v3/whoami/验证令牌身份与权限范围。定期用./manage.py api_tokens list检查令牌使用情况不再需要时用./manage.py api_tokens revoke --idid撤销撤销会保留审计记录。轮换SECRET_KEY时务必先通过SECRET_KEY_FALLBACKS保留旧密钥确认令牌全部迁移/重建后再移除避免一次性吊销全部令牌。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Wagtail v3 API 认证指南：Bearer Token 的创建、安全模型与权限管控
Wagtail v3 API 认证指南Bearer Token 的创建、安全模型与权限管控【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail本文基于 Wagtail 仓库的官方文档 v3 API authentication 展开系统讲解 Wagtail API v3 的 Bearer Token 认证机制如何携带令牌发起请求、如何通过管理后台与命令行创建令牌、令牌的 HMAC 摘要存储与SECRET_KEY轮换机制、撤销与审计记录的生命周期管理以及令牌即用户的权限模型与多级管理门槛。读完本文你将能安全地为自己或服务账号签发 API 令牌并在生产环境中正确地轮换密钥、审计令牌使用与回收令牌。v3 API 的认证模型令牌绑定用户权限与后台一致Wagtail v3 API位于 wagtail/api/v3使用Bearer Token不记名令牌认证请求。核心设计是每个令牌都绑定到一个用户账号API 请求以该用户的身份执行并继承该用户全部 Wagtail 权限——这与在后台界面操作时所使用的权限体系完全相同。这意味着你不需要为 API 单独维护一套权限规则一个用户能做什么他的令牌就能做什么。唯一的差异在于几个本文下面会提到的边界情况如匿名降级、令牌管理权限门槛等。从源码结构看这一认证逻辑由 wagtail/api/v3/auth.py 中的BearerTokenAuth类实现它继承自 Ninja 框架的HttpBearer接收Authorization: Bearer token请求头在APIToken表中按令牌摘要查找对应令牌再将request.user设置为令牌所属用户最后把令牌对象挂到request.auth上供后续使用。携带令牌发起请求在每个请求的Authorization请求头中发送令牌即可完成认证curl -H Authorization: Bearer wagtail_… https://example.com/api/v3/whoami/用/whoami/端点验证令牌GET /api/v3/whoami/是一个专门用于验证令牌及其访问级别的端点返回当前认证用户的用户信息、个人资料profile和所属分组groups。该端点由 wagtail/api/v3/routers/whoami.py 实现返回结构如下{ user: { id: 1, username: deploy, email: deployexample.com, first_name: , last_name: , is_superuser: false }, profile: { avatar_url: null }, groups: [Editors] }其响应中的WhoAmISchema定义了user、profile、groups三个字段用户字段包含id以字符串形式返回、username、email、first_name、last_name、is_superuserprofile 目前仅包含avatar_url取自已关联的wagtail_userprofilegroups是用户所属分组的名称列表。由于自定义用户模型可能没有email、first_name等字段实现中使用getattr(..., ) or 做了容错处理。/whoami/端点通过authBearerTokenAuth()声明必须认证访问——也就是说不带令牌访问它会返回未认证错误这与下面要讲的公开只读端点行为不同。匿名请求与认证失败静默降级公开的只读端点例如 pages、images、documents、redirects同时允许匿名访问和已认证访问。在这类端点上缺失令牌、无效令牌或被撤销的令牌一律被当作匿名请求处理不会返回 401 错误换言之认证失败不会让公开端点报错而是降级为匿名访问返回公开可读的内容。这一行为由 wagtail/api/v3/auth.py 中的AllowAnonymous类配合实现公开只读端点使用auth[BearerTokenAuth(), AllowAnonymous()]的组合——先尝试令牌认证失败则显式标记为匿名。源码中有一个值得注意的细节BearerTokenAuth.authenticate()在令牌无效或用户未激活is_active为假时会主动将request.user覆盖为AnonymousUser注释中明确说明这是为了覆盖 Django 认证后端例如 session设置的 user防止浏览器中登录后台的会话 cookie 意外抬升 API 请求的权限。即使一个已登录后台的编辑者带着自己的 session cookie 访问公开 API 端点API 仍只按匿名或令牌身份处理。创建令牌后台与命令行两种方式在管理后台创建只要INSTALLED_APPS中包含wagtail.api.v3拥有相应权限的用户即可在Settings设置→ API tokens下管理令牌。创建令牌时需要注意令牌明文只在创建那一刻显示一次之后系统只保存其摘要。页面会提示你立即将令牌复制并存放到安全位置关闭页面后便无法再查看原文。该后台管理界面由 wagtail/users/views/api_tokens.py 中的APITokenViewSet注册它挂载到设置菜单add_to_settings_menu True、使用key图标、菜单名为api_tokens管理 URL 前缀为api-tokens。列表页展示令牌前缀、名称、所属用户、创建时间、最后使用时间与撤销状态并提供按用户、创建时间、最后使用时间、是否已撤销等条件的过滤APITokenFilterSet。在命令行创建./manage.py api_tokens create --userdeploy --namedeploy bot该命令会直接打印令牌明文非常适合脚本化使用例如TOKEN$(./manage.py api_tokens create --userdeploy --nameci)需要结构化输出时加--json参数./manage.py api_tokens list用于列出令牌展示 ID、前缀、名称、所属用户、创建时间、最后使用时间、撤销状态api_tokens revoke则按--id或--user--prefix撤销令牌。该命令的实现位于 wagtail/management/commands/api_tokens.py共三个子命令各参数说明如下子命令参数说明create--user必填令牌所属用户的USERNAME_FIELD值--name必填令牌的显示名称/标签--json可选输出 JSON 对象而非裸令牌list--user可选只列出指定用户的令牌--include-revoked可选同时列出已撤销的令牌revoke--id令牌 ID与--user/--prefix二选一--user--prefix按用户与前缀定位令牌须同时提供--json输出的 JSON 对象包含token明文、prefix、name、user、created五个字段其中created为 ISO 8601 格式时间戳。revoke子命令要求--id或--user--prefix至少一组若前缀过短匹配到多个未撤销令牌命令会报错并提示Use a longer --prefix or --id防止误撤销。无论是后台还是 CLI 创建/撤销操作都会写入审计日志wagtail.apitoken.create/wagtail.apitoken.revokeCLI 操作额外记录data{source: management_command}。令牌安全模型只存摘要、前缀可识别、密钥可轮换只存储 HMAC-SHA-256 摘要数据库里保存的不是令牌明文而是每个令牌的 HMAC-SHA-256 摘要digest且摘要与你的SECRET_KEY绑定。令牌明文只存在于创建的那一刻create_token的返回值既不会写入数据库也不会被记录进日志。从 wagtail/models/api.py 可以看到具体机制hash_token()使用 Django 的salted_hmac以wagtail.apitoken为盐、SECRET_KEY为密钥、SHA-256 算法计算摘要key_hash字段存储该 64 字符十六进制摘要且设置了unique约束。这意味着即使数据库泄露攻击者也无法反向还原出可用令牌。wagtail_前缀与校验和令牌字符串带有wagtail_前缀和内置校验和checksum一方面让客户端和密钥扫描器secret scanner能够识别出这是 Wagtail API 令牌另一方面让系统可以离线快速校验令牌格式。generate_token()生成形如wagtail_secretchecksum的令牌secret 部分由 20 字节安全随机数secrets.token_bytes经 Base62 编码而来checksum 由 CRC32 计算并 Base62 编码。validate_token_format()则会离线检查前缀、总长度、字符集Base62与 CRC32 校验和且使用常量时间比较secrets.compare_digest防止时序攻击。格式校验失败说明令牌不可能存在校验通过也不代表令牌一定有效还需查库确认摘要匹配且未被撤销。轮换SECRET_KEY的注意事项由于摘要与SECRET_KEY绑定轮换密钥对既有令牌有直接影响使用SECRET_KEY_FALLBACKS平滑轮换在旧密钥被列入SECRET_KEY_FALLBACKS期间旧密钥签发的令牌仍然有效从SECRET_KEY_FALLBACKS中移除旧密钥后对应令牌才全部失效。这与 Django session 认证的轮换机制完全一致。不带 fallback 直接轮换如果直接更换SECRET_KEY而不保留任何 fallback所有令牌会一次性全部失效。背后的实现见APIToken.candidate_key_hashes()wagtail/models/api.py查询时按[SECRET_KEY, *SECRET_KEY_FALLBACKS]逐个计算候选摘要只要令牌是用当前密钥或任一 fallback 密钥签发的就能命中。相关测试位于 wagtail/api/v3/tests/test_auth.py分别覆盖了轮换后无 fallback 全部失效与轮换后 fallback 保留期间仍可用两种场景。令牌生命周期撤销留痕、审计可查、使用频率可控撤销是软删除保留审计线索撤销令牌后台界面或 CLI只是设置一个撤销时间戳revoked_at而不是删除数据库记录目的是保留完整的审计线索。APIToken.revoke()wagtail/models/api.py只做revoked_at timezone.now()这一件事后台的RevokeView在撤销后写入wagtail.apitoken.revoke审计日志并给出成功提示。token 的创建与撤销动作都会被记录在 审计日志 中可在后台侧边栏查看令牌的历史记录。令牌模型迁移文件见 wagtail/migrations/0098_apitoken.py包含user外键CASCADE删除、name、key_hash唯一、prefix、created、revoked_at、last_used_at七个字段。注意user采用级联删除用户被删除时其令牌也会一并删除。last_used_at节流写入令牌通过last_used_at时间戳记录使用情况但写入频率受到节流限制在WAGTAILAPI_TOKEN_LAST_USED_INTERVAL指定的间隔秒默认60内每个令牌最多只写一次数据库。# settings.py WAGTAILAPI_TOKEN_LAST_USED_INTERVAL 60 # 默认值实现见BearerTokenAuth._touch_last_used()wagtail/api/v3/auth.py当间隔为None时直接返回、不做任何写入否则仅当last_used_at为空或距上次写入已超过间隔时才通过QuerySet.update()更新一次避免在繁忙 API 上产生大量无意义的写操作。该设置也收录在 settings 参考文档WAGTAILAPI_TOKEN_LAST_USED_INTERVAL一节。将间隔设为None可完全禁用该写入例如在只读数据库上运行站点时WAGTAILAPI_TOKEN_LAST_USED_INTERVAL None # 完全禁用 last_used_at 写入权限模型令牌等于用户管理令牌另有门槛令牌的访问范围等于其用户令牌允许的访问级别与所绑定用户账号完全一致。因此文档建议慎重权衡两种用法直接使用真实用户账号签发令牌适合个人用途但令牌与真人账号绑定引入专用服务账号service account为 API 集成创建拥有最小权限集的独立用户令牌被泄露或需要下线时直接撤销令牌/停用账号不会影响任何真实用户。管理令牌自身的权限门槛令牌管理本身是权限受限的共分三层实现在 wagtail/users/utils.py 的user_can_manage_token()与get_manageable_token_owners()中操作所需权限附加约束管理自己账号的令牌wagtailcore对 API tokens 模型的add/change/delete权限可在Settings → Groups中分配无管理其他用户的令牌除上述权限外还需要用户模型user model的change权限该权限同时授予敏感账号管理能力如密码重置、分组管理务必谨慎管理**超级用户superuser**的令牌仅超级用户本人可以普通用户即使持有上述权限也无法管理超管的令牌从实现上看get_manageable_token_owners()的逻辑是拥有用户模型change权限的用户可管理除超级用户以外的所有用户非超管视角会过滤掉is_superuserTrue没有该权限的用户只能管理自己User.objects.filter(pkcurrent_user.pk)。user_can_manage_token()则在每次创建/撤销时做最终裁决普通用户对超管令牌的管理请求会被拒绝。快速上手清单确认INSTALLED_APPS中包含wagtail.api.v3并已执行迁移0098_apitoken会创建APIToken模型。为集成方创建服务账号最小权限集然后签发令牌./manage.py api_tokens create --userdeploy --nameci --json将令牌明文安全存放仅出现一次在请求头中携带curl -H Authorization: Bearer wagtail_… https://example.com/api/v3/whoami/用GET /api/v3/whoami/验证令牌身份与权限范围。定期用./manage.py api_tokens list检查令牌使用情况不再需要时用./manage.py api_tokens revoke --idid撤销撤销会保留审计记录。轮换SECRET_KEY时务必先通过SECRET_KEY_FALLBACKS保留旧密钥确认令牌全部迁移/重建后再移除避免一次性吊销全部令牌。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
