登录/ 注册
 找回密码
 立即注册
关闭

CSDN热搜

程序园 精品问答 技术交流 资源下载
返回列表 发新帖
首页 › 业界区 › 业界 ›在 django-ninja 中实现类似腾讯阿里云的应用鉴权机制 ...

在 django-ninja 中实现类似腾讯阿里云的应用鉴权机制

椎蕊 2025-7-10 10:57:42
前言

本文章介绍如何使用基于 AppClient 模型的 Django-Ninja API 鉴权机制。
这也是上次说的中台项目衍生物
中台项目相关的文章，我大概还会再写一篇
这个系列的文章注定是没什么人看的，毕竟还是小众了一些
不过我还是得写，没有读者也要记录，以后需要的时候就能用上
PS: 本文基于使用 DjangoStarter 框架，默认读者具备 DjangoStarter 3.0 以上版本的项目结构、基础设施
限于篇幅关系，本文无法贴出全部代码，有兴趣的同学可以在公众号后台回复「API鉴权」获取完整代码
概述

这套鉴权机制提供了以下功能：

  • 多种认证方式：支持查询参数、请求头和 Bearer Token 三种方式
  • IP 白名单：支持单个 IP 和 CIDR 网段限制
  • 权限范围控制：基于 scopes 的细粒度权限管理
  • 状态检查：自动验证 AppClient 的启用状态
  • 安全性：包含完整的认证和授权流程
搭配官方文档食用更佳哦~
https://django-ninja.dev/guides/authentication/
使用方法

为了能有个直观的体验
我先介绍使用方法
后面再来讲实现
1. 创建 AppClient

首先在 Django Admin 或通过代码创建一个 AppClient：
  1. from apps.app.models import AppClient
  3. app_client = AppClient.objects.create(
  4.     app_id="my-app",
  5.     app_name="我的应用",
  6.     secret_key="your-secret-key-here",
  7.     allowed_ips="192.168.1.0/24,10.0.0.1",  # 可选：IP 限制
  8.     scopes="project:read,project:write,user:read",  # 可选：权限范围
  9.     status=AppClient.Status.ACTIVE
  10. )
复制代码
2. 在 API 中使用认证
  1. from ninja import Router
  2. from core.authentication import (
  3.    api_key_auth,
  4.    api_key_header_auth,
  5.    api_key_bearer_auth,
  6.    require_app_client_scopes,
  7.    AppClientScopes,
  8. )
  10. router = Router()
  13. # 使用查询参数认证
  14. @router.get("/data", auth=api_key_auth)
  15. def get_data(request):
  16.    app_client = request.auth
  17.    return {"data": "success", "client": app_client.app_name}
  20. # 使用请求头认证
  21. @router.get("/info", auth=api_key_header_auth)
  22. def get_info(request):
  23.    return {"info": "success"}
  26. # 使用 Bearer Token 认证
  27. @router.get("/status", auth=api_key_bearer_auth)
  28. def get_status(request):
  29.    return {"status": "success"}
复制代码
3. 添加权限控制
  1. # 需要特定权限
  2. @router.get("/projects", auth=app_client_api_key)
  3. @require_app_client_scopes([AppClientScopes.PROJECT_READ])
  4. def list_projects(request):
  5.     return {"projects": []}
  7. # 需要多个权限
  8. @router.post("/projects", auth=app_client_api_key)
  9. @require_app_client_scopes([AppClientScopes.PROJECT_WRITE, AppClientScopes.USER_READ])
  10. def create_project(request):
  11.     return {"message": "项目创建成功"}
  13. # 手动检查权限
  14. @router.get("/custom-check", auth=app_client_api_key)
  15. def custom_permission_check(request):
  16.     from core.authentication import AppClientScopeChecker
  17.    
  18.     if AppClientScopeChecker.has_any_scope(request, [AppClientScopes.PROJECT_READ, AppClientScopes.PROJECT_WRITE]):
  19.         return {"access": "granted"}
  20.     else:
  21.         return {"access": "denied"}
复制代码
认证方式

1. 查询参数认证 (APIKeyQuery)

使用方式：
  1. GET /api/endpoint?api_key=your-secret-key
复制代码
代码示例：
  1. from core.authentication import api_key_auth
  4. @router.get("/data", auth=api_key_auth)
  5. def get_data(request):
  6.    return {"data": "success"}
复制代码
2. 请求头认证 (APIKeyHeader)

使用方式：
  1. GET /api/endpoint
  2. X-API-Key: your-secret-key
复制代码
代码示例：
  1. from core.authentication import api_key_header_auth
  4. @router.get("/data", auth=api_key_header_auth)
  5. def get_data(request):
  6.    return {"data": "success"}
复制代码
3. Bearer Token 认证 (HttpBearer)

使用方式：
  1. GET /api/endpoint
  2. Authorization: Bearer your-secret-key
复制代码
代码示例：
  1. from core.authentication import api_key_bearer_auth
  4. @router.get("/data", auth=api_key_bearer_auth)
  5. def get_data(request):
  6.    return {"data": "success"}
复制代码
权限范围 (Scopes) 系统

事先说明，scopes 方式只是实现起来最简单，但不代表最合适
毕竟在 Django 框架中，本来就有一套权限体系了，我也有想过接入那套权限体系，可以很方便地在后台编辑每个应用的权限
不过因为实现起来会稍微麻烦一点点，为了快速上线，我就先自己搞了个 scopes 系统了~
后续肯定是要试试 接入 Django 权限体系 的~！
权限格式

权限范围使用 resource:action 格式，例如：

  • project:read - 项目读取权限
  • project:write - 项目写入权限
  • user:* - 用户相关所有权限
  • * - 超级管理员权限
预定义权限常量
  1. from core.authentication import AppClientScopes
  3. # 项目权限
  4. AppClientScopes.PROJECT_READ     # "project:read"
  5. AppClientScopes.PROJECT_WRITE    # "project:write"
  6. AppClientScopes.PROJECT_DELETE   # "project:delete"
  7. AppClientScopes.PROJECT_ALL      # "project:*"
  9. # 用户权限
  10. AppClientScopes.USER_READ        # "user:read"
  11. AppClientScopes.USER_WRITE       # "user:write"
  12. AppClientScopes.USER_DELETE      # "user:delete"
  13. AppClientScopes.USER_ALL         # "user:*"
  15. # 超级权限
  16. AppClientScopes.SUPER_ADMIN      # "*"
复制代码
权限检查方法

1. 装饰器方式（推荐）
  1. from core.authentication import require_app_client_scopes, AppClientScopes
  3. @router.get("/projects", auth=app_client_api_key)
  4. @require_app_client_scopes([AppClientScopes.PROJECT_READ])
  5. def list_projects(request):
  6.     return {"projects": []}
复制代码
2. 手动检查方式
  1. from core.authentication import AppClientScopeChecker
  3. @router.get("/data", auth=app_client_api_key)
  4. def get_data(request):
  5.     # 检查是否具有所有指定权限
  6.     if AppClientScopeChecker.check_scopes(request, [AppClientScopes.PROJECT_READ]):
  7.         return {"data": "success"}
  8.    
  9.     # 检查是否具有任意一个权限
  10.     if AppClientScopeChecker.has_any_scope(request, [AppClientScopes.PROJECT_READ, AppClientScopes.PROJECT_WRITE]):
  11.         return {"data": "partial access"}
  12.    
  13.     # 获取客户端所有权限
  14.     scopes = AppClientScopeChecker.get_client_scopes(request)
  15.     return {"error": "权限不足", "your_scopes": scopes}
复制代码
IP 白名单

配置 IP 限制

在 AppClient 的 allowed_ips 字段中配置允许的 IP 地址：
  1. # 单个 IP
  2. app_client.allowed_ips = "192.168.1.100"
  4. # 多个 IP
  5. app_client.allowed_ips = "192.168.1.100,10.0.0.1,203.0.113.5"
  7. # CIDR 网段
  8. app_client.allowed_ips = "192.168.1.0/24,10.0.0.0/8"
  10. # 混合配置
  11. app_client.allowed_ips = "192.168.1.100,10.0.0.0/8,203.0.113.0/24"
  13. # 不限制 IP（留空或 None）
  14. app_client.allowed_ips = None
复制代码
IP 获取逻辑

系统会按以下优先级获取客户端 IP：

  • HTTP_X_FORWARDED_FOR 头部的第一个 IP（适用于代理/负载均衡环境）
  • REMOTE_ADDR（直接连接的 IP）
错误处理

认证失败

当认证失败时，会返回 HTTP 401 错误：
  1. {
  2.     "detail": "Unauthorized"
  3. }
复制代码
权限不足

当权限检查失败时，会返回 HTTP 403 错误：
  1. {
  2.     "detail": "缺少权限: project:write"
  3. }
复制代码
自定义错误处理
  1. from core.authentication import AppClientPermissionError
  3. @router.get("/custom", auth=app_client_api_key)
  4. def custom_endpoint(request):
  5.     if not some_condition:
  6.         raise AppClientPermissionError("自定义权限错误信息")
  7.     return {"data": "success"}
复制代码
测试 API

项目提供了完整的测试 API，可以用来验证认证和权限功能：
  1. # 测试 API Key 认证
  2. GET /api/app/test/api-key?api_key=your-secret-key
  4. # 测试请求头认证
  5. GET /api/app/test/api-key-header
  6. X-API-Key: your-secret-key
  8. # 测试 Bearer Token 认证
  9. GET /api/app/test/bearer
  10. Authorization: Bearer your-secret-key
  12. # 测试权限范围
  13. GET /api/app/test/scopes/project-read?api_key=your-secret-key
  14. GET /api/app/test/scopes/project-write?api_key=your-secret-key
  15. GET /api/app/test/scopes/multiple?api_key=your-secret-key
复制代码
最佳实践

以下是一些最佳实践的建议
无论是使用什么技术、框架，实际开发中都可以参考一下
1. 密钥管理


  • 使用强密钥（建议 32 字符以上）
  • 定期轮换密钥
  • 不要在代码中硬编码密钥
  • 使用环境变量或安全的配置管理系统
2. 权限设计


  • 遵循最小权限原则
  • 使用细粒度的权限范围
  • 定期审查和清理不必要的权限
  • 为不同的应用场景创建不同的 AppClient
3. IP 限制


  • 在生产环境中启用 IP 白名单
  • 使用 CIDR 网段而不是单个 IP（便于扩展）
  • 考虑 CDN 和代理的 IP 转发
4. 监控和日志
  1. import logging
  3. logger = logging.getLogger(__name__)
  5. @router.get("/sensitive-data", auth=app_client_api_key)
  6. @require_app_client_scopes([AppClientScopes.PROJECT_READ])
  7. def get_sensitive_data(request):
  8.     app_client = request.auth
  9.     logger.info(f"AppClient {app_client.app_id} accessed sensitive data")
  10.     return {"data": "sensitive information"}
复制代码
集成到现有 API

添加路由

在 config/apis.py 中添加 app 路由：
  1. from apps.app.apis import router as app_router
  3. api.add_router('app', app_router)
复制代码
混合认证

这是 django-ninja 提供的新功能
可以在同一个 API 中同时支持多种认证方式：
  1. from ninja.security import django_auth
  2. from core.authentication import api_key_auth
  5. # 同时支持 Django 用户认证和 AppClient 认证
  6. @router.get("/user-data", auth=[django_auth, api_key_auth])
  7. def get_data(request):
  8.    return {"user": request.user.username}
复制代码
更新主 API 配置

除此之外，还可以在主 API 配置全局认证和其他功能
  1. from django.contrib.admin.views.decorators import staff_member_required
  3. api = NinjaAPI(
  4.     title=f'{settings.DJANGO_STARTER["project_info"]["name"]} APIs',
  5.     description=settings.DJANGO_STARTER["project_info"]["description"],
  6.     renderer=JSONRespRenderer(),
  7.     csrf=True,
  8.     auth=[django_auth, api_key_auth, api_key_header_auth, api_key_bearer_auth],
  9.     urls_namespace='api',
  10.     docs=Swagger(settings={"persistAuthorization": True}),
  11.     docs_decorator=staff_member_required,
  12. )
复制代码
这里简单介绍一下
我这段配置：

  • 使用 auth=[django_auth, api_key_auth, api_key_header_auth, api_key_bearer_auth] 支持多种认证方式（其实还有一个JWT的，不过我这里没考虑）
  • 使用 docs_decorator=staff_member_required, 配置了访问swagger文档必须是已登录的 staff_member
实现

OK，最后再介绍一下具体实现 （应该没人会坚持看到这么后面吧…）
限于篇幅关系，本文无法贴出全部代码，有兴趣的同学可以在公众号后台回复「API鉴权」获取完整代码
模型

首先是 AppClient 模型，代码位于 src/apps/app/models.py 内
除了字段定义，还添加了一些方法用于 获取权限范围列表、获取允许的 IP 地址列表 之类的功能

按照DDD思想来讲，这个模型算是一个 充血模型
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

使用道具 举报
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册
发帖
椎蕊
2025-7-10 10:57:42

0

粉丝关注

12

主题发布

板块介绍填写区域，请于后台编辑
微信扫一扫