Django REST Framework API密钥

为Django REST Framework提供API密钥权限。

简介

Django REST Framework API密钥是一个库，允许服务器端客户端安全地使用您的API。 这些客户端通常是第三方后端和服务（即机器），它们没有用户账户，但仍需要以安全的方式与您的API交互。

功能

• ✌️ 简单易用：通过管理站点创建、查看和撤销API密钥，或使用内置助手以编程方式创建API密钥。
• 🔒 尽可能安全：API密钥像用户密码一样受到同样的关注。它们仅在创建时可见，并在存储到数据库之前进行哈希处理。
• 🎨 可定制：通过构建自己的自定义API密钥模型、权限类和管理面板来满足特定的业务需求。

我应该使用API密钥吗？

在切换到API密钥访问控制方案之前，您需要考虑一些重要的安全方面。我们在安全注意事项中列出了一些这些内容，包括通过HTTPS提供您的API。

此外，请参阅何时以及为什么使用API密钥以获取有关API密钥是否适合您的用例的提示。

以下情况下API密钥非常理想：

• 阻止匿名流量。
• 通过API密钥实现限流。（请注意，Django REST Framework已经为此用例提供了许多内置工具。）
• 通过记录API密钥和请求信息来识别使用模式。

它还可以为授权内部服务提供足够的安全保障，例如您的API服务器和内部前端应用程序。

请注意，此包**不适用于身份验证**。您**不应**使用此包直接或间接地识别单个用户。

如果您需要服务器到服务器的身份验证，您可能需要考虑OAuth。例如，django-oauth-toolkit库可以帮助。

快速入门

使用pip安装

pip install "djangorestframework-api-key==3.*"

注意：强烈建议将依赖项锁定到最新的主要版本（如上图所示），因为主版本之间可能会发生破坏性更改。

将应用添加到您的INSTALLED_APPS

# settings.py

INSTALLED_APPS = [
  # ...
  "rest_framework",
  "rest_framework_api_key",
]

运行包含的迁移

python manage.py migrate

有关如何配置权限和管理API密钥的信息，请参阅文档。

变更日志

请参阅CHANGELOG.md。

贡献

请参阅CONTRIBUTING.md。

许可证

MIT

变更日志

此项目的所有重大更改都将记录在此文件中。

格式基于Keep a Changelog。此项目遵循语义版本控制。

3.0.0 - 2023-09-30

更改

• 使用基于SHA512的快速密钥哈希器代替密码哈希器。通过使API密钥验证速度提高数个数量级（根据估计，网络延迟除外，10倍到30倍）来减少服务器负载。哈希密钥将在第一次调用.is_valid()时透明升级。（Pull #244，Pull #251）

删除

• 取消对已达到EOL的Python 3.7的支持。（Pull #247）
• 当使用DRF 3.14.0或更高版本时，删除了冗余的BaseHasAPIKey上的.has_object_permission()实现。（Pull #240）

添加

• 添加对Python 3.11的官方支持。（Pull #247）

2.3.0 - 2023-01-19

删除

• 取消对已达到EOL的Python 3.6的支持。（Pull #210）

修复

• 修复在非默认数据库上运行迁移0004时的问题。（Pull #215）

2.2.0 - 2022-03-11

添加

• 添加对Django不同版本的配置检测支持（PR #187）

更改

• 添加对Django 3.2和Python 3.9及3.10的官方支持（PR #189）
• 将hashed_key字段的max_length从100增加到150，以解决与argon2-cffi的长度问题（PR #193）

2.1.0 - 2021-09-24

添加

• 添加对自定义API keyword的支持。（Pull #175）

2.0.0 - 2020-04-07

注意：此版本删除了对某些Python和Django版本的支持，但不含其他破坏性更改。有关详细迁移步骤，请参阅升级到2.0。

删除

• 取消对Django 2.0和Django 2.1的支持。（Pull #126）
• 取消对Python 3.5的支持。（Pull #84）

添加

• 添加对Django 3.0的支持。（Pull #82）
• 添加对Python 3.8的支持。（Pull #81）
• 添加BaseAPIKeyManager.get_from_key()以允许从视图中检索API密钥。（Pull #93）
• 添加类型注解，并部分支持django-stubs和djangorestframework-stubs。（Pull #88，Pull #122）

1.4.1 - 2019-08-24

添加

• 现在包含类型注解（PEP 561）。（Pull #73）

1.4.0 - 2019-07-16

注意：此版本包含迁移。有关详细说明，请参阅升级到v1.4。

添加

• prefix和hashed_key现在存储在APIKey模型上的专用字段中。（Pull #62）

1.3.0 - 2019-06-28

注意：此版本包含迁移。在您的Django项目中，请使用以下命令运行它们：

python manage.py migrate rest_framework_api_key

添加

• 添加抽象API密钥模型（AbstractAPIKey）和基管理器（BaseAPIKeyManager）。（Pull #36）
• 添加基本权限（BaseHasAPIKey）。（拉取请求 #46）

更改

• APIKey 的 id 字段现在不可编辑。
• APIKeyModelAdmin 不再定义 fieldsets。这允许子类从 Django 的自动字段集中受益。（拉取请求 #52）

修复

• 在 setup.py 中显式使用 utf-8 编码，这可能会在特定系统上安装时导致问题。（拉取请求 #58）

1.2.1 - 2019-06-03

修复

• 修复了 APIKeyModelAdmin 中的严重错误，该错误阻止了 rest_framework_api_key 通过 Django 系统检查。（拉取请求 #39）

1.2.0 - 2019-05-29

注意：此版本包含迁移。在您的Django项目中，请使用以下命令运行它们：

python manage.py migrate rest_framework_api_key

添加

• API 密钥现在可以有一个可选的 expiry_date。如果设置了 expiry_date，并且它是在过去，则 HasAPIKey 将拒绝访问，即 API 密钥已过期。（拉取请求 #33）
• 现在可以在 API 密钥管理面板中按 prefix 进行搜索。
• prefix 现在在 API 密钥管理面板的编辑视图中显示。

1.1.0 - 2019-05-14

添加

• 改进了有关使用的密码散列器的文档。
• 添加了对 Argon2、BcryptSHA256 和 PBKDF2SHA1 散列器的测试。（拉取请求 #32）

修复

• 修复了对生成包含点号的散列的密码散列器的支持。（拉取请求 #31）

1.0.0 - 2019-04-24

本版本与 0.x 不兼容。有关迁移步骤，请参阅升级到 1.0。

删除

• 删除 HasAPIKeyOrIsAuthenticated 权限类。现在应使用位运算组合，例如 HasAPIKey | IsAuthenticated。
• 删除 DRF_API_KEY_* 设置。（拉取请求 #19）

更改

• 切换到新的 API 密钥生成和验证方案。客户端现在必须使用单个 API 密钥头进行授权（拉取请求 #19）。默认情况下，头是 Authorization。可以使用 API_KEY_CUSTOM_HEADER 设置进行自定义（拉取请求 #26）。使用 name 字段来识别客户端。

添加

• 添加了对 Django 2.2 的支持。（拉取请求 #27）
• 添加了使用 APIKey.objects.create_key() 进行程序化 API 密钥创建的功能。（拉取请求 #19）

修复

• 使用 Django 的密码散列辅助函数改进了 API 密钥存储。使用默认的 Django 密码散列器。（拉取请求 #19）

0.4.0 - 2019-04-21

删除

• 停止支持 Python 3.4。现在只支持 3.5、3.6 和 3.7。
• 停止支持 Django < 2.0。现在只支持 2.0 和 2.1。

修复

• HasAPIKey 现在实现了 .has_object_permissions()，这允许与其他权限类组合并执行对象级权限检查。（拉取请求 #25）

0.3.1 - 2018-11-17

初始变更日志条目。

添加

• APIKey 模型。
• HasAPIKey 和 HasAPIKeyOrIsAuthenticated 权限类。
• 从 Django 管理员生成、查看和撤销 API 密钥。
• 使用 Api-Token 和 Api-Secret-Key 头部进行请求身份验证。可以通过 DRF_API_KEY_TOKEN_HEADER 和 DRF_API_KEY_SECRET_KEY_HEADER 设置进行自定义。