用途:在 API 服务器、worker 与服务间集成中处理 Clerk 认证,包括验证传入请求、对服务端资源执行授权、安全使用 Clerk Backend API,并明确跨域令牌行为。优先使用官方 SDK 与中间件;缺少框架级 SDK 时,采用 Clerk 文档中的令牌校验与 Backend API 模式,避免手写 JWT 解析。
核心流程:接收请求→在代理中保留认证相关头与 Cookie→用官方 SDK/helper 认证→从已验证状态取得身份、会话、组织和令牌类型→执行授权→校验应用输入→数据访问或副作用→返回明确的 401 或 403(除非有意使用 Clerk 默认行为)。
主要能力:Express 中先注册 clerkMiddleware(),再用 getAuth(req) 或 requireAuth();Fastify 注册 clerkPlugin() 后从 request.auth 或 getAuth(request) 取状态。跨域时前端用 const token = await getToken() 并发送 Authorization: Bearer <token>,后端需正确配置 CORS 并拒绝缺失、无效、过期、环境不符或令牌类型不符的请求。
多语言要点:Go 用 Clerk SDK 或按其 issuer/JWKS/audience 规则校验后提取声明;Python/FastAPI 用依赖注入,Django/Flask 用中间件加装饰器;Rails 用中间件或 controller concern;Spring 用过滤器或 Security 认证提供者;ASP.NET Core 用认证中间件或自定义处理器;Laravel 用 HTTP 中间件配合策略/门。均需校验签名、issuer、audience、过期与令牌类型后才能信任声明。
授权与限制:区分认证与授权,比较 userId 与资源归属、组织 ID、角色/权限与令牌类型,默认拒绝未知角色、缺失组织、待处理会话与不支持令牌类型。不要信任请求体中的用户/组织/角色/计划信息。Backend API 客户端仅限可信服务端环境,绝不可暴露密钥;高流量端点宜从请求状态取 ID,并用 webhook 做异步反规范化。代理须保留 Authorization、Accept、Host、Origin、Referer、X-Forwarded-Host、X-Forwarded-Proto 等头。Webhook 路由应绕过会话保护并用 verifyWebhook() 或 Svix 验证签名。诊断时用 curl 测试,勿记录令牌、密钥、会话 ID 或签名。具体价格、平台与效果资料暂未提供。