跳到主要内容

Key Authentication (Key Auth)

概述​

Key Authentication (key-auth) 策略通过要求 API 消费者在其请求头中包含有效的 API Key 来强制执行 API 安全性。此机制确保只有授权的用户或应用程序可以访问 API。

密钥认证的工作原理​

  • API 消费者必须在请求头中提供 valid API Key。
  • API 网关在处理请求之前验证 API 密钥。
  • 如果 API 密钥是 missing 或 invalid，请求将因身份验证错误而被拒绝。

何时使用密钥认证​

  • 限制 API 访问到 authorized clients。
  • 当需要 API consumer identification 机制时。
  • 当 combining multiple authentication methods（例如，key-auth + JWT）。

Note: 如果同时启用 key-auth 和 JWT authentication，则必须传递 both 身份验证方法以成功请求。

配置详情​

创建 API 密钥​

在应用 Key Authentication 策略之前，必须生成 API 密钥。请按照以下步骤操作：

Step 1: Open the API Key Management Page
  • 在 APIM 控制台中导航到 APIM Management 菜单
  • 选择要创建 API 密钥的项目。
Step 2: Generate a New API Key
  • 点击 Create API Key 按钮。
  • 输入 API 密钥的 description（例如，“移动应用访问的密钥”）。
  • 系统将 automatically generate a unique API Key。

Step 3: Check and view the API Key stored in management screen:
  • 一旦创建，API 密钥将在 API 密钥管理屏幕中显示。
  • 用户可以查找 API 密钥并在需要时再次复制。

配置字段​

Key Authentication 策略包括以下设置：

Field NameDescriptionData Input
头部名称HTTP header 中应包含 API 密钥的请求。默认头部名称是 x-apim-key。在 Kubernetes 部署 'apim-dff' 中，您可以通过环境变量更改头部名称。修改这些变量将重新启动 APIM 控制台，并可能导致短暂的服务中断。可以通过环境变量配置（仅限 K8s）。
API 密钥验证系统在允许 API 访问之前验证提供的 API 密钥是否已注册且有效。
注意：API 密钥通常是 32 个字符的字母数字字符串。		自动验证
错误处理如果未提供有效的 API 密钥，请求将被拒绝，并返回 HTTP 401 Unauthorized 响应。自动响应

带密钥认证的示例 API 调用​

要进行经过身份验证的 API 请求，请在请求头中包含 API Key：

GET /api/resource HTTP/1.1
Host: api.example.com
headers: { "x-apim-key": "202cb962ac59075b964b07152d234b70" }


如果 API 密钥有效，请求将成功处理。否则，响应将返回：

{
    "message": "无效的身份验证凭据",
    "status": 401
}