名称: 安全身份验证 描述: 身份验证、授权和API安全实现。用于构建用户系统、保护API或实施访问控制。涵盖OAuth 2.1/OIDC、JWT模式、会话、Passkeys/WebAuthn、RBAC/ABAC/ReBAC、策略引擎（OPA、Casbin、SpiceDB）、托管身份验证（Clerk、Auth0）、自托管（Keycloak、Ory）和API安全最佳实践。—
身份验证与安全
在Python、Rust、Go和TypeScript中实现现代身份验证、授权和API安全。
何时使用此技能
使用此技能当：
- 构建用户身份验证系统（登录、注册、单点登录）
- 实现授权（角色、权限、访问控制）
- 保护API（JWT验证、速率限制）
- 添加无密码身份验证（Passkeys/WebAuthn）
- 从基于密码的身份验证迁移到现代身份验证
- 集成企业单点登录（SAML、OIDC）
- 实现细粒度权限（RBAC、ABAC、ReBAC）
OAuth 2.1强制要求（2025标准）
┌─────────────────────────────────────────────────────────────┐
│ OAuth 2.1强制要求 │
│ (RFC 9798 - 2025) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ✅ 必选（与OAuth 2.0的破坏性变更） │
│ ├─ PKCE（代码交换证明密钥）强制要求 │
│ │ └─ S256方法（SHA-256），最小熵43字符 │
│ ├─ 精确重定向URI匹配 │
│ │ └─ 无通配符匹配，无子字符串匹配 │
│ ├─ 仅公开客户端使用授权码流程 │
│ │ └─ 所有其他流程需要机密客户端 │
│ └─ 所有端点需要TLS 1.2+ │
│ │
│ ❌ 移除（不再支持） │
│ ├─ 隐式授权（安全漏洞） │
│ ├─ 资源所有者密码凭据授权 │
│ │ └─ 使用OAuth 2.0设备流程（RFC 8628）代替 │
│ └─ 查询参数中的承载令牌 │
│ └─ 必须使用Authorization头或POST体 │
│ │
└─────────────────────────────────────────────────────────────┘
关键点： PKCE现在对所有OAuth流程强制要求，不仅限于公开客户端。
JWT最佳实践
签名算法（优先级顺序）
-
EdDSA与Ed25519（推荐）
- 最快性能
- 最小签名大小
- 现代密码学
-
ES256（ECDSA与P-256）
- 良好性能
- 行业标准
- 广泛兼容性
-
RS256（RSA）
- 传统兼容性
- 较大签名
- 较慢性能
绝不允许alg: none或算法切换攻击。
令牌生命周期（具体值）
- 访问令牌： 5-15分钟
- 刷新令牌： 1-7天，带轮换
- ID令牌： 与访问令牌相同（5-15分钟）
刷新令牌轮换： 每次刷新生成新的访问和刷新令牌，并使旧刷新令牌失效。
令牌存储
- 访问令牌： 仅内存（永不使用localStorage）
- 刷新令牌： HTTP-only cookie + SameSite=Strict
- CSRF令牌： 单独的非HTTP-only cookie
- 永不记录令牌： 在应用日志中脱敏
JWT声明（必选）
{
"iss": "https://auth.example.com",
"sub": "user-id-123",
"aud": "api.example.com",
"exp": 1234567890,
"iat": 1234567890,
"jti": "unique-token-id",
"scope": "read:profile write:data"
}
使用Argon2id进行密码哈希
OWASP 2025参数
算法: Argon2id
内存成本 (m): 64 MB (65536 KiB)
时间成本 (t): 3次迭代
并行度 (p): 4线程
盐长度: 16字节 (128位)
目标哈希时间: 150-250ms
实现
具体实现，请参见references/password-hashing.md。
关键点：
- Argon2id是混合型：数据无关时序 + 内存硬
- 调整内存成本以在您的硬件上实现150-250ms
- 使用时序安全比较进行验证
- 从bcrypt逐步迁移（用旧验证，用新重新哈希）
Passkeys / WebAuthn
Passkeys使用FIDO2/WebAuthn提供防钓鱼、无密码身份验证。
何时使用Passkeys
- 优先安全的用户面向应用
- 减少密码相关支持负担
- 移动优先应用（生物识别身份验证）
- 需要MFA但无SMS的应用
跨设备Passkey同步
- iCloud钥匙串： 苹果生态系统（iOS 16+, macOS 13+）
- 谷歌密码管理器： Android、Chrome
- 1Password、Bitwarden： 第三方密码管理器
实现指南，请参见references/passkeys-webauthn.md。
授权模型
┌─────────────────────────────────────────────────────────────┐
│ 授权模型选择 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 简单角色（<20个角色） │
│ └─ 使用Casbin的RBAC（嵌入式，任何语言） │
│ 示例: 管理员、用户、访客 │
│ │
│ 复杂属性规则 │
│ └─ 使用OPA或Cerbos的ABAC │
│ 示例: "允许如果user.clearance >= doc.level │
│ AND user.dept == doc.dept" │
│ │
│ 基于关系（多租户、协作） │
│ └─ 使用SpiceDB的ReBAC（Zanzibar模型） │
│ 示例: "可以编辑如果是文档工作空间成员 │
│ AND workspace.plan包含功能" │
│ 用例: Notion-like、GitHub-like权限 │
│ │
│ Kubernetes / 基础设施策略 │
│ └─ OPA（用于准入控制的Gatekeeper） │
│ 示例: 强制实施pod安全策略 │
│ │
└─────────────────────────────────────────────────────────────┘
详细比较，请参见references/authorization-patterns.md。
按语言库选择
TypeScript
| 用例 | 库 | Context7 ID | 信任度 | 备注 |
|---|---|---|---|---|
| 身份验证框架 | Auth.js v5 | /websites/authjs_dev |
87.4 | 多框架（Next、Svelte、Solid） |
| JWT | jose 5.x | - | - | 支持EdDSA、ES256、RS256 |
| Passkeys | @simplewebauthn/server 11.x | - | - | FIDO2服务器 |
| 验证 | Zod 3.x | /colinhacks/zod |
90.4 | 模式验证 |
| 策略引擎 | Casbin.js 1.x | - | - | RBAC/ABAC嵌入式 |
Python
| 用例 | 库 | 备注 |
|---|---|---|
| 身份验证框架 | Authlib 1.3+ | OAuth/OIDC客户端+服务器 |
| JWT | joserfc 1.x | 现代、维护中 |
| Passkeys | py_webauthn 2.x | WebAuthn服务器 |
| 密码哈希 | argon2-cffi 24.x | OWASP参数 |
| 验证 | Pydantic 2.x | FastAPI集成 |
| 策略引擎 | PyCasbin 1.x | RBAC/ABAC嵌入式 |
Rust
| 用例 | 库 | 备注 |
|---|---|---|
| JWT | jsonwebtoken 10.x | EdDSA、ES256、RS256 |
| OAuth客户端 | oauth2 5.x | OAuth 2.1流程 |
| Passkeys | webauthn-rs 0.5.x | WebAuthn + 认证 |
| 密码哈希 | argon2 0.5.x | 原生Argon2id |
| 策略引擎 | Casbin-RS 2.x | RBAC/ABAC嵌入式 |
Go
| 用例 | 库 | 备注 |
|---|---|---|
| JWT | golang-jwt v5 | 社区维护 |
| OAuth客户端 | go-oidc v3 | 仅OIDC客户端 |
| Passkeys | go-webauthn 0.11.x | Duo维护 |
| 密码哈希 | golang.org/x/crypto/argon2 | 标准库 |
| 策略引擎 | Casbin v2 | 原始实现 |
托管身份验证服务
| 服务 | 最佳适用 | 关键特性 |
|---|---|---|
| Clerk | 快速开发、初创公司 | 预构建UI、Next.js SDK |
| Auth0 | 企业、成熟公司 | 25+社交提供商、SSO |
| WorkOS AuthKit | B2B SaaS、企业SSO | SAML/SCIM、管理门户 |
| Supabase Auth | Postgres用户 | 基于Postgres、RLS |
详细比较，请参见references/managed-auth-comparison.md。
自托管解决方案
| 解决方案 | 语言 | 用例 |
|---|---|---|
| Keycloak | Java | 企业、本地部署 |
| Ory | Go | 云原生、微服务 |
| Authentik | Python | 现代、开发者友好 |
设置指南，请参见references/self-hosted-auth.md。
API安全最佳实践
速率限制
// 分层速率限制（每IP + 每用户）
const rateLimits = {
anonymous: '10请求/分钟',
authenticated: '100请求/分钟',
premium: '1000请求/分钟',
}
使用滑动窗口算法（非固定窗口）与Redis。
CORS配置
// 限制性CORS（生产）
const corsOptions = {
origin: ['https://app.example.com'],
credentials: true,
maxAge: 86400, // 24小时
allowedHeaders: ['Content-Type', 'Authorization'],
methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
}
// 绝不使用origin: '*'与credentials: true
安全头
const securityHeaders = {
'Strict-Transport-Security': 'max-age=63072000; includeSubDomains; preload',
'X-Frame-Options': 'DENY',
'X-Content-Type-Options': 'nosniff',
'Referrer-Policy': 'strict-origin-when-cross-origin',
'Permissions-Policy': 'geolocation=(), microphone=(), camera=()',
'Content-Security-Policy': "default-src 'self'; script-src 'self'",
}
完整API安全指南，请参见references/api-security.md。
前端集成模式
保护路由（Next.js）
// middleware.ts
import { withAuth } from 'next-auth/middleware'
export default withAuth({
callbacks: {
authorized: ({ token, req }) => {
if (req.nextUrl.pathname.startsWith('/dashboard')) {
return !!token
}
if (req.nextUrl.pathname.startsWith('/admin')) {
return token?.role === 'admin'
}
return true
},
},
})
export const config = {
matcher: ['/dashboard/:path*', '/admin/:path*'],
}
基于角色的UI渲染
import { useSession } from 'next-auth/react'
export function AdminPanel() {
const { data: session } = useSession()
if (session?.user?.role !== 'admin') {
return null
}
return <div>管理员控制</div>
}
常见工作流
1. OAuth 2.1集成
- 生成PKCE挑战
- 重定向到授权端点
- 使用授权码处理回调
- 交换令牌（使用code_verifier）
- 安全存储令牌
- 实现刷新令牌轮换
完整实现，请参见references/oauth21-guide.md。
2. JWT实现
- 使用
scripts/generate_jwt_keys.py生成签名密钥 - 配置令牌生命周期（5-15分钟访问，1-7天刷新）
- 实现令牌验证中间件
- 设置刷新令牌轮换
- 配置令牌存储（访问令牌用内存，刷新令牌用HTTP-only cookie）
详细模式，请参见references/jwt-best-practices.md。
3. Passkeys设置
- 在注册/设置期间注册凭据
- 生成注册挑战
- 验证认证
- 存储凭据ID和公钥
- 实现带断言的认证流程
可运行实现，请参见examples/passkeys-demo/。
4. 授权引擎设置
- 选择引擎（简单RBAC用Casbin，ReBAC用SpiceDB）
- 定义模式/策略
- 实现检查函数
- 与路由处理程序集成
- 添加审计日志
详细比较，请参见references/authorization-patterns.md。
与其他技能集成
表单技能
- 带验证的登录/注册表单
- 身份验证失败的错误状态
- 密码强度指示器
- 电子邮件验证
API模式技能
- JWT中间件集成
- 错误响应格式（401、403）
- OpenAPI安全模式
- CORS配置
仪表板技能
- 基于角色的组件可见性
- 用户个人资料显示
- 基于权限的数据过滤
- 审计跟踪可视化
可观测性技能
- 身份验证事件日志（登录、登出、权限拒绝）
- 失败登录跟踪
- 令牌刷新监控
- 安全事件警报
脚本
生成JWT密钥
python scripts/generate_jwt_keys.py --algorithm EdDSA
生成用于JWT签名的EdDSA或ES256密钥对。
验证OAuth 2.1配置
python scripts/validate_oauth_config.py --config oauth.json
验证OAuth 2.1合规性（PKCE启用、精确重定向URI等）。
示例
Auth.js + Next.js
完整实现，带OAuth提供商、凭据和会话管理。
位置：examples/authjs-nextjs/
Keycloak + FastAPI
自托管Keycloak与FastAPI通过OIDC集成。
位置：examples/keycloak-fastapi/
Passkeys演示
可运行Passkeys实现，使用@simplewebauthn。
位置：examples/passkeys-demo/
参考文档
references/oauth21-guide.md- OAuth 2.1实现指南references/jwt-best-practices.md- JWT生成、验证、存储references/passkeys-webauthn.md- Passkeys/WebAuthn实现references/authorization-patterns.md- RBAC、ABAC、ReBAC比较references/password-hashing.md- Argon2id参数、迁移