securing-authentication

身份验证与安全

在 Python、Rust、Go 和 TypeScript 中实现现代身份验证、授权和 API 安全。

何时使用此技能

在以下情况下使用此技能：

• 构建用户身份验证系统（登录、注册、SSO）
• 实现授权（角色、权限、访问控制）
• 保护 API（JWT 验证、速率限制）
• 添加无密码身份验证（Passkeys/WebAuthn）
• 从基于密码的身份验证迁移到现代身份验证
• 集成企业 SSO（SAML、OIDC）
• 实现细粒度权限（RBAC、ABAC、ReBAC）

OAuth 2.1 强制要求（2025 年标准）

┌─────────────────────────────────────────────────────────────┐
│           OAuth 2.1 MANDATORY REQUIREMENTS                  │
│                   (RFC 9798 - 2025)                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ✅ REQUIRED (Breaking Changes from OAuth 2.0)             │
│  ├─ PKCE (Proof Key for Code Exchange) MANDATORY           │
│  │   └─ S256 method (SHA-256), minimum entropy 43 chars   │
│  ├─ Exact redirect URI matching                            │
│  │   └─ No wildcard matching, no substring matching       │
│  ├─ Authorization code flow ONLY for public clients       │
│  │   └─ All other flows require confidential client       │
│  └─ TLS 1.2+ required for all endpoints                   │
│                                                             │
│  ❌ REMOVED (No Longer Supported)                          │
│  ├─ Implicit grant (security vulnerabilities)             │
│  ├─ Resource Owner Password Credentials grant              │
│  │   └─ Use OAuth 2.0 Device Flow (RFC 8628) instead      │
│  └─ Bearer token in query parameters                       │
│      └─ Must use Authorization header or POST body        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

关键提示： PKCE 现已成为所有 OAuth 流程的强制要求，而不仅仅适用于公共客户端。

JWT 最佳实践

签名算法（优先级顺序）

1. EdDSA with Ed25519（推荐）

   • 性能最快
   • 签名最小
   • 现代密码学

2. ES256（ECDSA with P-256）

   • 性能良好
   • 行业标准
   • 兼容性广

3. 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 参数

Algorithm: Argon2id
Memory cost (m): 64 MB (65536 KiB)
Time cost (t): 3 iterations
Parallelism (p): 4 threads
Salt length: 16 bytes (128 bits)
Target hash time: 150-250ms

实现

具体实现请参见 references/password-hashing.md。

要点：

• Argon2id 是混合算法：数据无关的计时 + 内存硬化
• 调整内存成本，使其在你的硬件上达到 150-250ms
• 验证时使用时序安全比较
• 逐步从 bcrypt 迁移（使用旧算法验证，再用新算法重新哈希）

Passkeys / WebAuthn

Passkeys 使用 FIDO2/WebAuthn 提供抗网络钓鱼的无密码身份验证。

何时使用 Passkeys

• 优先考虑安全性的面向用户应用程序
• 减少与密码相关的支持负担
• 移动优先应用程序（生物识别身份验证）
• 需要 MFA 但不使用 SMS 的应用程序

跨设备 Passkey 同步

• iCloud Keychain： Apple 生态系统（iOS 16+、macOS 13+）
• Google Password Manager： Android、Chrome
• 1Password、Bitwarden： 第三方密码管理器

实现指南请参见 references/passkeys-webauthn.md。

授权模型

┌─────────────────────────────────────────────────────────────┐
│                Authorization Model Selection                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Simple Roles (<20 roles)                                  │
│  └─ RBAC with Casbin (embedded, any language)              │
│      Example: Admin, User, Guest                           │
│                                                             │
│  Complex Attribute Rules                                    │
│  └─ ABAC with OPA or Cerbos                                │
│      Example: "Allow if user.clearance >= doc.level        │
│                AND user.dept == doc.dept"                   │
│                                                             │
│  Relationship-Based (Multi-Tenant, Collaborative)          │
│  └─ ReBAC with SpiceDB (Zanzibar model)                    │
│      Example: "Can edit if member of doc's workspace       │
│                AND workspace.plan includes feature"         │
│      Use cases: Notion-like, GitHub-like permissions       │
│                                                             │
│  Kubernetes / Infrastructure Policies                       │
│  └─ OPA (Gatekeeper for admission control)                 │
│      Example: Enforce pod security policies                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

详细对比请参见 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 + attestation
密码哈希	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 安全最佳实践

速率限制

// Tiered rate limiting (per IP + per user)
const rateLimits = {
  anonymous: '10 requests/minute',
  authenticated: '100 requests/minute',
  premium: '1000 requests/minute',
}

使用滑动窗口算法（而非固定窗口），并配合 Redis。

CORS 配置

// Restrictive CORS (production)
const corsOptions = {
  origin: ['https://app.example.com'],
  credentials: true,
  maxAge: 86400, // 24 hours
  allowedHeaders: ['Content-Type', 'Authorization'],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
}

// NEVER use origin: '*' with 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>Admin Controls</div>
}

常见工作流

1. OAuth 2.1 集成

1. 生成 PKCE challenge
2. 重定向到授权端点
3. 使用授权码处理回调
4. 用授权码交换令牌（附带 code_verifier）
5. 安全存储令牌
6. 实现刷新令牌轮换

完整实现请参阅 references/oauth21-guide.md。

2. JWT 实现

1. 使用 scripts/generate_jwt_keys.py 生成签名密钥
2. 配置令牌有效期（访问令牌 5-15 min，刷新令牌 1-7 day）
3. 实现令牌验证中间件
4. 设置刷新令牌轮换
5. 配置令牌存储方式（访问令牌存于内存，刷新令牌存于 HTTP-only cookie）

详细模式请参阅 references/jwt-best-practices.md。

3. Passkeys 设置

1. 在注册/设置期间注册凭据
2. 为注册生成 challenge
3. 验证 attestation
4. 存储凭据 ID 和公钥
5. 使用 assertion 实现身份验证流程

可运行的实现请参阅 examples/passkeys-demo/。

4. 授权引擎设置

1. 选择引擎（简单 RBAC 选 Casbin，ReBAC 选 SpiceDB）
2. 定义架构/策略
3. 实现检查函数
4. 与路由处理程序集成
5. 添加审计日志

详细对比请参阅 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

通过 OIDC 集成 FastAPI 的可自托管 Keycloak。

位置：examples/keycloak-fastapi/

Passkeys Demo

基于 @simplewebauthn 的可运行通行密钥实现。

位置：examples/passkeys-demo/

参考文档

• references/oauth21-guide.md - OAuth 2.1 实现指南
• references/jwt-best-practices.md - JWT 生成、验证和存储
• references/passkeys-webauthn.md - 通行密钥/WebAuthn 实现
• references/authorization-patterns.md - RBAC、ABAC、ReBAC 对比
• references/password-hashing.md - Argon2id 参数和迁移