前言
本文章介绍如何使用基于 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:
python
from apps.app.models import AppClient
app_client = AppClient.objects.create(
app_id="my-app",
app_name="我的应用",
secret_key="your-secret-key-here",
allowed_ips="192.168.1.0/24,10.0.0.1", # 可选:IP 限制
scopes="project:read,project:write,user:read", # 可选:权限范围
status=AppClient.Status.ACTIVE
)
2. 在 API 中使用认证
python
from ninja import Router
from core.authentication import (
api_key_auth,
api_key_header_auth,
api_key_bearer_auth,
require_app_client_scopes,
AppClientScopes,
)
router = Router()
# 使用查询参数认证
@router.get("/data", auth=api_key_auth)
def get_data(request):
app_client = request.auth
return {"data": "success", "client": app_client.app_name}
# 使用请求头认证
@router.get("/info", auth=api_key_header_auth)
def get_info(request):
return {"info": "success"}
# 使用 Bearer Token 认证
@router.get("/status", auth=api_key_bearer_auth)
def get_status(request):
return {"status": "success"}
3. 添加权限控制
python
# 需要特定权限
@router.get("/projects", auth=app_client_api_key)
@require_app_client_scopes([AppClientScopes.PROJECT_READ])
def list_projects(request):
return {"projects": []}
# 需要多个权限
@router.post("/projects", auth=app_client_api_key)
@require_app_client_scopes([AppClientScopes.PROJECT_WRITE, AppClientScopes.USER_READ])
def create_project(request):
return {"message": "项目创建成功"}
# 手动检查权限
@router.get("/custom-check", auth=app_client_api_key)
def custom_permission_check(request):
from core.authentication import AppClientScopeChecker
if AppClientScopeChecker.has_any_scope(request, [AppClientScopes.PROJECT_READ, AppClientScopes.PROJECT_WRITE]):
return {"access": "granted"}
else:
return {"access": "denied"}
认证方式
1. 查询参数认证 (APIKeyQuery)
使用方式:
bash
GET /api/endpoint?api_key=your-secret-key
代码示例:
python
from core.authentication import api_key_auth
@router.get("/data", auth=api_key_auth)
def get_data(request):
return {"data": "success"}
2. 请求头认证 (APIKeyHeader)
使用方式:
bash
GET /api/endpoint
X-API-Key: your-secret-key
代码示例:
python
from core.authentication import api_key_header_auth
@router.get("/data", auth=api_key_header_auth)
def get_data(request):
return {"data": "success"}
3. Bearer Token 认证 (HttpBearer)
使用方式:
bash
GET /api/endpoint
Authorization: Bearer your-secret-key
代码示例:
python
from core.authentication import api_key_bearer_auth
@router.get("/data", auth=api_key_bearer_auth)
def get_data(request):
return {"data": "success"}
权限范围 (Scopes) 系统
事先说明,scopes 方式只是实现起来最简单,但不代表最合适
毕竟在 Django 框架中,本来就有一套权限体系了,我也有想过接入那套权限体系,可以很方便地在后台编辑每个应用的权限
不过因为实现起来会稍微麻烦一点点,为了快速上线,我就先自己搞了个 scopes 系统了~
后续肯定是要试试 接入 Django 权限体系 的~!
权限格式
权限范围使用 resource:action
格式,例如:
project:read
- 项目读取权限project:write
- 项目写入权限user:*
- 用户相关所有权限*
- 超级管理员权限
预定义权限常量
python
from core.authentication import AppClientScopes
# 项目权限
AppClientScopes.PROJECT_READ # "project:read"
AppClientScopes.PROJECT_WRITE # "project:write"
AppClientScopes.PROJECT_DELETE # "project:delete"
AppClientScopes.PROJECT_ALL # "project:*"
# 用户权限
AppClientScopes.USER_READ # "user:read"
AppClientScopes.USER_WRITE # "user:write"
AppClientScopes.USER_DELETE # "user:delete"
AppClientScopes.USER_ALL # "user:*"
# 超级权限
AppClientScopes.SUPER_ADMIN # "*"
权限检查方法
1. 装饰器方式(推荐)
python
from core.authentication import require_app_client_scopes, AppClientScopes
@router.get("/projects", auth=app_client_api_key)
@require_app_client_scopes([AppClientScopes.PROJECT_READ])
def list_projects(request):
return {"projects": []}
2. 手动检查方式
python
from core.authentication import AppClientScopeChecker
@router.get("/data", auth=app_client_api_key)
def get_data(request):
# 检查是否具有所有指定权限
if AppClientScopeChecker.check_scopes(request, [AppClientScopes.PROJECT_READ]):
return {"data": "success"}
# 检查是否具有任意一个权限
if AppClientScopeChecker.has_any_scope(request, [AppClientScopes.PROJECT_READ, AppClientScopes.PROJECT_WRITE]):
return {"data": "partial access"}
# 获取客户端所有权限
scopes = AppClientScopeChecker.get_client_scopes(request)
return {"error": "权限不足", "your_scopes": scopes}
IP 白名单
配置 IP 限制
在 AppClient 的 allowed_ips
字段中配置允许的 IP 地址:
python
# 单个 IP
app_client.allowed_ips = "192.168.1.100"
# 多个 IP
app_client.allowed_ips = "192.168.1.100,10.0.0.1,203.0.113.5"
# CIDR 网段
app_client.allowed_ips = "192.168.1.0/24,10.0.0.0/8"
# 混合配置
app_client.allowed_ips = "192.168.1.100,10.0.0.0/8,203.0.113.0/24"
# 不限制 IP(留空或 None)
app_client.allowed_ips = None
IP 获取逻辑
系统会按以下优先级获取客户端 IP:
HTTP_X_FORWARDED_FOR
头部的第一个 IP(适用于代理/负载均衡环境)REMOTE_ADDR
(直接连接的 IP)
错误处理
认证失败
当认证失败时,会返回 HTTP 401 错误:
json
{
"detail": "Unauthorized"
}
权限不足
当权限检查失败时,会返回 HTTP 403 错误:
json
{
"detail": "缺少权限: project:write"
}
自定义错误处理
python
from core.authentication import AppClientPermissionError
@router.get("/custom", auth=app_client_api_key)
def custom_endpoint(request):
if not some_condition:
raise AppClientPermissionError("自定义权限错误信息")
return {"data": "success"}
测试 API
项目提供了完整的测试 API,可以用来验证认证和权限功能:
bash
# 测试 API Key 认证
GET /api/app/test/api-key?api_key=your-secret-key
# 测试请求头认证
GET /api/app/test/api-key-header
X-API-Key: your-secret-key
# 测试 Bearer Token 认证
GET /api/app/test/bearer
Authorization: Bearer your-secret-key
# 测试权限范围
GET /api/app/test/scopes/project-read?api_key=your-secret-key
GET /api/app/test/scopes/project-write?api_key=your-secret-key
GET /api/app/test/scopes/multiple?api_key=your-secret-key
最佳实践
以下是一些最佳实践的建议
无论是使用什么技术、框架,实际开发中都可以参考一下
1. 密钥管理
- 使用强密钥(建议 32 字符以上)
- 定期轮换密钥
- 不要在代码中硬编码密钥
- 使用环境变量或安全的配置管理系统
2. 权限设计
- 遵循最小权限原则
- 使用细粒度的权限范围
- 定期审查和清理不必要的权限
- 为不同的应用场景创建不同的 AppClient
3. IP 限制
- 在生产环境中启用 IP 白名单
- 使用 CIDR 网段而不是单个 IP(便于扩展)
- 考虑 CDN 和代理的 IP 转发
4. 监控和日志
python
import logging
logger = logging.getLogger(__name__)
@router.get("/sensitive-data", auth=app_client_api_key)
@require_app_client_scopes([AppClientScopes.PROJECT_READ])
def get_sensitive_data(request):
app_client = request.auth
logger.info(f"AppClient {app_client.app_id} accessed sensitive data")
return {"data": "sensitive information"}
集成到现有 API
添加路由
在 config/apis.py
中添加 app 路由:
python
from apps.app.apis import router as app_router
api.add_router('app', app_router)
混合认证
这是 django-ninja 提供的新功能
可以在同一个 API 中同时支持多种认证方式:
python
from ninja.security import django_auth
from core.authentication import api_key_auth
# 同时支持 Django 用户认证和 AppClient 认证
@router.get("/user-data", auth=[django_auth, api_key_auth])
def get_data(request):
return {"user": request.user.username}
更新主 API 配置
除此之外,还可以在主 API 配置全局认证和其他功能
python
from django.contrib.admin.views.decorators import staff_member_required
api = NinjaAPI(
title=f'{settings.DJANGO_STARTER["project_info"]["name"]} APIs',
description=settings.DJANGO_STARTER["project_info"]["description"],
renderer=JSONRespRenderer(),
csrf=True,
auth=[django_auth, api_key_auth, api_key_header_auth, api_key_bearer_auth],
urls_namespace='api',
docs=Swagger(settings={"persistAuthorization": True}),
docs_decorator=staff_member_required,
)
这里简单介绍一下
我这段配置:
- 使用
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思想来讲,这个模型算是一个 充血模型 😃
python
import uuid
from django.db import models
from django.core.validators import RegexValidator
from django_starter.db.models import ModelExt
class AppClient(ModelExt):
"""应用客户端模型,用于管理第三方应用的访问权限"""
class Status(models.TextChoices):
ACTIVE = 'active', '启用'
INACTIVE = 'inactive', '禁用'
id = models.BigAutoField(
primary_key=True,
verbose_name='主键ID',
help_text='系统自动生成的唯一标识符',
db_comment='物理主键,自增ID'
)
guid = models.UUIDField(
default=uuid.uuid4,
unique=True,
editable=False,
verbose_name='全局唯一标识',
help_text='系统自动生成的UUID,用作逻辑主键',
db_comment='逻辑主键,GUID'
)
app_id = models.CharField(
max_length=100,
unique=True,
verbose_name='应用标识',
help_text='用于标识调用方系统的唯一ID,建议使用有意义的命名',
db_comment='应用标识,用于标识调用方系统',
validators=[
RegexValidator(
regex=r'^[a-zA-Z0-9_-]+$',
message='应用标识只能包含字母、数字、下划线和连字符'
)
]
)
app_name = models.CharField(
max_length=200,
verbose_name='应用名称',
help_text='调用方应用的显示名称或备注信息',
db_comment='应用名称,调用方的名称或备注信息'
)
secret_key = models.CharField(
max_length=100,
verbose_name='密钥',
help_text='用于API签名验证的密钥,请妥善保管',
db_comment='密钥,用于签名验证',
)
allowed_ips = models.TextField(
blank=True,
null=True,
verbose_name='允许访问的IP',
help_text='允许访问的IP地址列表,多个IP用逗号分隔,留空表示不限制',
db_comment='允许访问的 IP 列表,逗号分隔'
)
scopes = models.TextField(
blank=True,
null=True,
verbose_name='权限范围',
help_text='应用的权限范围,格式如:project:read,project:write',
db_comment='权限范围,如 project:read,project:write'
)
status = models.CharField(
max_length=10,
choices=Status.choices,
default=Status.ACTIVE,
verbose_name='状态',
help_text='应用的启用状态',
db_comment='启用/禁用状态'
)
class Meta:
db_table = 'app_client'
verbose_name = '应用客户端'
verbose_name_plural = '应用客户端'
ordering = ['-create_time']
indexes = [
models.Index(fields=['app_id']),
models.Index(fields=['status']),
models.Index(fields=['create_time']),
]
def __str__(self):
return f'{self.app_name} ({self.app_id})'
def is_active(self):
"""检查应用是否处于活跃状态"""
# todo 为什么这个 is_deleted 会变成 str 啊??
# return self.status == self.Status.ACTIVE and not self.is_deleted
return self.status == self.Status.ACTIVE
def get_scopes_list(self):
"""获取权限范围列表"""
if not self.scopes:
return []
return [scope.strip() for scope in self.scopes.split(',') if scope.strip()]
def get_allowed_ips_list(self):
"""获取允许的IP地址列表"""
if not self.allowed_ips:
return []
return [ip.strip() for ip in self.allowed_ips.split(',') if ip.strip()]
def save(self, *args, **kwargs):
"""重写save方法,添加自定义逻辑"""
# 确保app_name不为空
if not self.app_name:
self.app_name = self.app_id
super().save(*args, **kwargs)
测试接口
添加一些测试接口,方便后续调试
代码位于 src/apps/app/apis/client/apis.py
python
from typing import List
from ninja import Router
from django.http import HttpRequest
from core.authentication import (
api_key_auth,
api_key_header_auth,
api_key_bearer_auth,
require_app_client_scopes,
AppClientScopes,
AppClientScopeChecker,
)
from apps.app.models import AppClient
from .schemas import AppClientSchema, AppClientCreateSchema
router = Router(tags=['AppClient API'])
@router.get("/test/api-key", auth=api_key_auth)
def test_api_key_auth(request: HttpRequest):
"""测试API Key认证(查询参数方式)
使用方式: GET /api/app/test/api-key?api_key=your_secret_key
"""
app_client = request.auth
return {
"message": "API Key认证成功",
"app_id": app_client.app_id,
"app_name": app_client.app_name,
"scopes": app_client.get_scopes_list(),
}
@router.get("/test/api-key-header", auth=api_key_header_auth)
def test_api_key_header_auth(request: HttpRequest):
"""测试API Key认证(请求头方式)
使用方式: GET /api/app/test/api-key-header
Headers: X-API-Key: your_secret_key
"""
app_client = request.auth
return {
"message": "API Key Header认证成功",
"app_id": app_client.app_id,
"app_name": app_client.app_name,
"scopes": app_client.get_scopes_list(),
}
@router.get("/test/bearer", auth=api_key_bearer_auth)
def test_bearer_auth(request: HttpRequest):
"""测试Bearer Token认证
使用方式: GET /api/app/test/bearer
Headers: Authorization: Bearer your_secret_key
"""
app_client = request.auth
return {
"message": "Bearer Token认证成功",
"app_id": app_client.app_id,
"app_name": app_client.app_name,
"scopes": app_client.get_scopes_list(),
}
@router.get("/test/scopes/project-read", auth=api_key_auth)
@require_app_client_scopes([AppClientScopes.PROJECT_READ])
def test_project_read_scope(request: HttpRequest):
"""测试项目读取权限
需要权限: project:read
"""
return {
"message": "项目读取权限验证成功",
"required_scope": AppClientScopes.PROJECT_READ,
"client_scopes": AppClientScopeChecker.get_client_scopes(request),
}
@router.get("/test/scopes/project-write", auth=api_key_auth)
@require_app_client_scopes([AppClientScopes.PROJECT_WRITE])
def test_project_write_scope(request: HttpRequest):
"""测试项目写入权限
需要权限: project:write
"""
return {
"message": "项目写入权限验证成功",
"required_scope": AppClientScopes.PROJECT_WRITE,
"client_scopes": AppClientScopeChecker.get_client_scopes(request),
}
@router.get("/test/scopes/multiple", auth=api_key_auth)
@require_app_client_scopes([AppClientScopes.PROJECT_READ, AppClientScopes.USER_READ])
def test_multiple_scopes(request: HttpRequest):
"""测试多个权限要求
需要权限: project:read AND user:read
"""
return {
"message": "多权限验证成功",
"required_scopes": [AppClientScopes.PROJECT_READ, AppClientScopes.USER_READ],
"client_scopes": AppClientScopeChecker.get_client_scopes(request),
}
@router.get("/test/scopes/any", auth=api_key_auth)
def test_any_scope(request: HttpRequest):
"""测试任意权限检查
检查是否具有项目或用户相关的任意权限
"""
has_project_access = AppClientScopeChecker.has_any_scope(
request, [AppClientScopes.PROJECT_READ, AppClientScopes.PROJECT_WRITE]
)
has_user_access = AppClientScopeChecker.has_any_scope(
request, [AppClientScopes.USER_READ, AppClientScopes.USER_WRITE]
)
return {
"message": "权限检查完成",
"has_project_access": has_project_access,
"has_user_access": has_user_access,
"client_scopes": AppClientScopeChecker.get_client_scopes(request),
}
@router.get("/info", auth=api_key_auth)
def get_client_info(request: HttpRequest):
"""获取当前认证的AppClient信息"""
app_client = request.auth
return {
"app_id": app_client.app_id,
"app_name": app_client.app_name,
"status": app_client.status,
"scopes": app_client.get_scopes_list(),
"allowed_ips": app_client.get_allowed_ips_list(),
"create_time": app_client.create_time,
}
@router.get("/clients", auth=api_key_auth)
@require_app_client_scopes([AppClientScopes.SUPER_ADMIN])
def list_app_clients(request: HttpRequest) -> List[dict]:
"""列出所有AppClient(需要超级管理员权限)
需要权限: *
"""
clients = AppClient.objects.filter(is_deleted=False)
return [
{
"app_id": client.app_id,
"app_name": client.app_name,
"status": client.status,
"scopes": client.get_scopes_list(),
"create_time": client.create_time,
}
for client in clients
]
管理命令
为了方便使用,我又添加了俩命令
顾名思义,创建新的 AppClient 和 列出所有
src/apps/app/management/commands/create_app_client.py
src/apps/app/management/commands/list_app_clients.py
限于篇幅原因,无法贴出全部代码,有兴趣的同学可以在公众号后台回复「API鉴权」获取完整代码
核心逻辑
关于鉴权的核心逻辑,我单独创建一个 core
package 来存放
目录结构如下
sql
core
├─ exceptions
│ ├─ __init__.py
│ └─ permissions.py
├─ authentication
│ ├─ __init__.py
│ ├─ README.md
│ ├─ permissions.py
│ ├─ app.py
│ └─ api_key.py
└─ __init__.py
最关键的代码就是 src/core/authentication/app.py
中的这几个认证实例
代码中有详细注释,一看就能理解。
如果觉得这个还比较复杂,后续我再介绍一个极简的实现方式。
python
class AppClientAuthMixin:
"""AppClient认证混入类,提供通用的认证逻辑"""
def _get_client_ip(self, request: HttpRequest) -> str:
"""获取客户端真实IP地址"""
x_forwarded_for = request.META.get('HTTP_X_FORWARDED_FOR')
if x_forwarded_for:
ip = x_forwarded_for.split(',')[0].strip()
else:
ip = request.META.get('REMOTE_ADDR')
return ip
def _validate_ip_access(self, app_client: AppClient, request: HttpRequest) -> bool:
"""验证IP访问权限"""
allowed_ips = app_client.get_allowed_ips_list()
if not allowed_ips: # 如果没有设置IP限制,则允许所有IP
return True
client_ip = self._get_client_ip(request)
for allowed_ip in allowed_ips:
try:
# 支持单个IP和CIDR网段
if '/' in allowed_ip:
network = ipaddress.ip_network(allowed_ip, strict=False)
if ipaddress.ip_address(client_ip) in network:
return True
else:
if client_ip == allowed_ip:
return True
except (ipaddress.AddressValueError, ValueError):
# 忽略无效的IP格式
continue
return False
def _authenticate_app_client(self, request: HttpRequest, key: str) -> Optional[AppClient]:
"""认证AppClient的通用逻辑"""
try:
app_client = AppClient.objects.get(secret_key=key)
# 检查应用是否处于活跃状态
if not app_client.is_active():
return None
# 验证IP访问权限
if not self._validate_ip_access(app_client, request):
return None
# 将权限范围添加到request中,供后续权限检查使用
request.app_client_scopes = app_client.get_scopes_list()
return app_client
except AppClient.DoesNotExist:
return None
class AppClientApiKey(AppClientAuthMixin, APIKeyQuery):
"""基于查询参数的AppClient API Key认证"""
param_name = "api_key"
def authenticate(self, request: HttpRequest, key: str) -> Optional[AppClient]:
return self._authenticate_app_client(request, key)
class AppClientApiKeyHeader(AppClientAuthMixin, APIKeyHeader):
"""基于请求头的AppClient API Key认证"""
param_name = "X-API-Key"
def authenticate(self, request: HttpRequest, key: str) -> Optional[AppClient]:
return self._authenticate_app_client(request, key)
class AppClientBearer(AppClientAuthMixin, HttpBearer):
"""基于Bearer Token的AppClient认证"""
def authenticate(self, request: HttpRequest, token: str) -> Optional[AppClient]:
return self._authenticate_app_client(request, token)
# 创建认证实例,可以在API中直接使用
api_key_auth = AppClientApiKey()
api_key_header_auth = AppClientApiKeyHeader()
api_key_bearer_auth = AppClientBearer()
极简实现方式
这套完善的鉴权逻辑,如果你觉得太复杂了
没关系,我这还做了个极简版本,去掉了权限、IP限制等乱七八糟的东西,只校验 api-key 是否有效
实现代码在 src/core/authentication/api_key.py
自定义的 ApiKey
类继承自 ninja.security.APIKeyQuery
类,表明 api_key
参数需要放在 GET query params 里
python
from ninja.security import APIKeyQuery
from apps.app.models import AppClient
class ApiKey(APIKeyQuery):
param_name = "api_key"
def authenticate(self, request, key):
try:
c = AppClient.objects.get(secret_key=key)
print(f'api key authenticated: {c.secret_key}, app id: {c.app_id}')
return c
except AppClient.DoesNotExist:
pass
使用也很简单
python
from apps.app.models import AppClient
from core.authentication.api_key import ApiKey
@router.get("/data", auth=ApiKey())
def get_data(request):
assert isinstance(request.auth, AppClient)
return {"data": "success"}
客户端请求的时候需要在 GET query params 里带上 AppClient
的 secret_key
校验通过的话,ninja 会自动在 request.auth
添加 AppClient
实例,在接口代码里可以直接获取这个实例。
小结
这篇文章居然写了两万多字🕶
这还是在删减了很多代码的情况下...
再啰嗦一次,有兴趣的同学可以在公众号后台回复「API鉴权」获取完整代码
这么长的文章,大概不会有人有耐心看到最后吧~
溜了,溜了~