54 lines
1.5 KiB
Markdown
54 lines
1.5 KiB
Markdown
---
|
|
title: API Key 认证 (API Key Authentication)
|
|
created: 2025-04-15
|
|
updated: 2026-05-01
|
|
type: concept
|
|
tags: []
|
|
sources: []
|
|
---
|
|
|
|
# API Key 认证 (API Key Authentication)
|
|
|
|
**通过预共享密钥验证客户端身份的简单认证机制**，常见于 API 网关和微服务间通信。
|
|
|
|
## 常见形式
|
|
|
|
| 形式 | HTTP 头格式 | 示例 |
|
|
|------|------------|------|
|
|
| API Key | `X-API-Key: <key>` | `X-API-Key: sk-abc123` |
|
|
| Bearer Token | `Authorization: Bearer <token>` | `Authorization: Bearer eyJ...` |
|
|
| Basic Auth | `Authorization: Basic <base64>` | `Authorization: Basic dXNlcjpwYXNz` |
|
|
|
|
## 在反向代理层实现
|
|
|
|
API Key 认证最适合在 [[reverse-proxy-authentication|反向代理层]] 实现——网关检查请求头，未携带有效 Key 的请求在到达后端前即被拒绝。
|
|
|
|
### 单 Key 校验
|
|
```
|
|
@unauthorized { not header X-API-Key "the-key" }
|
|
respond @unauthorized "Unauthorized" 401
|
|
```
|
|
|
|
### 多 Key 白名单
|
|
```
|
|
@authorized {
|
|
header X-API-Key "key-001"
|
|
header X-API-Key "key-002"
|
|
}
|
|
@unauthorized { not @authorized }
|
|
respond @unauthorized "Unauthorized" 401
|
|
```
|
|
|
|
## 适用场景
|
|
|
|
- ✅ 服务间 API 调用（内部微服务）
|
|
- ✅ 简单 Webhook 接收端点
|
|
- ✅ 开发/测试环境快速保护
|
|
- ❌ 需要用户身份/权限细分的场景 → 使用 JWT 或 [[forward-authentication|外部认证]]
|
|
|
|
## 相关概念
|
|
|
|
- [[reverse-proxy-authentication]] — 反向代理层认证
|
|
- [[forward-authentication]] — 复杂认证委托
|
|
- [[caddy-reverse-proxy-auth]] — Caddy 配置方案
|