Zoom Apps SDK 安全加固完全指南从 OWASP 头、PKCE 到令牌存储的 Marketplace 合规实践【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins导读本文以 concepts/security.md 为核心骨架系统讲解运行于 Zoom 客户端内嵌浏览器中的 Zoom App 必须满足的安全要求OWASP 响应头、TLS、Cookie 策略、PKCE OAuth、令牌服务端存储、state 参数 CSRF 防护以及数据访问分层。文章结合仓库内 架构文档、OAuth 参考、In-Client OAuth 完整实现 与 常见问题排查 等配套文档帮助读者写出一份能顺利通过 Zoom Marketplace 安全审查、且在实际运行中不踩静默失败坑的 Zoom App。为什么 Zoom App 的安全要求与众不同Zoom App 不是普通网页它运行在 Zoom 客户端的嵌入式浏览器中Windows 为 WebView2/ChromiummacOS/iOS 为 WKWebView部分表面如 Camera Mode 使用 CEF。这意味着应用被跨源cross-origin嵌入浏览器默认会阻止 Zoom 以 iframe/frame 方式加载你的页面你的前端与后端处于不同源Cookie 默认不会被发送会话会静默断开客户端版本多样unsupportedApis可能导致部分能力在旧客户端上不可用。安全审查是Marketplace 上架的硬性门槛。本仓库的 SKILL.md 明确将 security.md 列为核心概念文档之一并在Critical Gotchas中反复强调 Cookie 配置与 state 校验可见安全不是可选项而是应用能跑起来、能过审、能长期稳定运行的前提。必装的 OWASP 响应头Zoom 安全审查要求所有响应都携带以下 HTTP 头Header必填值作用Strict-Transport-Securitymax-age31536000强制 1 年 HTTPSHSTSX-Content-Type-Optionsnosniff禁止 MIME 类型嗅探Content-Security-Policyframe-ancestors self zoom.us *.zoom.us允许 Zoom 嵌入你的应用Referrer-Policysame-origin限制 Referrer 信息外泄X-Frame-OptionsALLOW-FROM zoom.us遗留的 frame 控制Express 中间件实现app.use((req, res, next) { res.setHeader(Strict-Transport-Security, max-age31536000); res.setHeader(X-Content-Type-Options, nosniff); res.setHeader(Content-Security-Policy, frame-ancestors self zoom.us *.zoom.us ); res.setHeader(Referrer-Policy, same-origin); next(); });关键点frame-ancestors这条 CSP 指令是 Zoom 嵌入式浏览器能加载你应用的开关。缺失或写错时浏览器会直接拦截 frame表现就是面板空白。这与 常见问题 诊断表里App 在浏览器能打开、在 Zoom 里打不开 → CSP 头错误完全对应。X-Frame-Options: ALLOW-FROM属于遗留控制部分现代浏览器已不识别但 Zoom 审查仍要求保留。提示CSP 的frame-ancestors只解决能否被嵌入若你的前端还调用 CDN 资源如appssdk.zoom.us需同步在 Domain Allowlist 中放行这些域名两者缺一不可。TLS 要求与本地开发隧道所有端点必须 HTTPS最低 TLS 1.2HTTP 请求必须重定向到 HTTPS必须使用有效 SSL 证书自签名证书会直接失败本地开发用 ngrok 等隧道自动获得 HTTPS。本仓库 调试指南 给出了完整命令链ngrok http 3000把生成的https://xxxxx.ngrok.io填入 Marketplace。注意免费版 ngrok 每次重启 URL 都会变化需同步更新 4 处Home URL、Redirect URL、OAuth Allow List、Domain Allow List可考虑付费版固定子域名。预检 Runbook 还建议用curl -sS -i $ZOOM_APP_URL验证隧道可达性确认返回 200/3xx 与合法 HTML而不是 404/502。Cookie 安全SameSiteNone 是硬性要求Zoom 嵌入式浏览器跨源嵌入你的应用Cookie 必须特殊配置// Express cookie-session 示例 app.use(require(cookie-session)({ name: session, keys: [process.env.SESSION_SECRET], maxAge: 24 * 60 * 60 * 1000, // 24 小时 sameSite: none, // 必填 - Zoom 跨源嵌入你的应用 secure: true // 必填 - SameSiteNone 必须搭配 Secure }));为什么必须是SameSiteNone你的应用运行在 Zoom 嵌入式浏览器里与你的服务器不同源。不设SameSiteNone浏览器就不会把 Cookie 发给你的服务器会话静默断开。这正是 SKILL.md 中 Gotcha #8 与 common-issues.md 诊断表Cookies not persisting反复强调的问题。SESSION_SECRET用于 Cookie 签名应通过环境变量注入见 environment-variables.md绝不可硬编码。PKCE所有 OAuth 流程的强制项Zoom Apps 的所有 OAuth 流程Web 重定向、In-Client、第三方都必须使用 PKCEProof Key for Code Exchange防止授权码拦截攻击。const crypto require(crypto); // 生成 PKCE 对 const verifier crypto.randomBytes(32).toString(hex); const challenge crypto.createHash(sha256) .update(verifier) .digest(base64url); // verifier 只存在服务端会话中绝不发给前端 req.session.codeVerifier verifier; // challenge 可发给前端或直接拼进 OAuth 重定向 URL res.json({ codeChallenge: challenge, state: req.session.state });安全原理授权码换令牌时服务端用之前保存的code_verifier做校验。攻击者即使截获了授权码也拿不到code_verifier无法兑换令牌。code_verifier永远不离开服务器。完整后端实现来自 in-client-oauth.md// 生成 PKCE challenge state router.get(/api/auth/challenge, (req, res) { const verifier crypto.randomBytes(32).toString(hex); const challenge crypto.createHash(sha256) .update(verifier) .digest(base64url); const state crypto.randomBytes(16).toString(hex); req.session.codeVerifier verifier; req.session.state state; res.json({ codeChallenge: challenge, state }); }); // 用授权码换令牌 router.post(/api/auth/token, async (req, res) { const { code, state } req.body; if (state ! req.session.state) { return res.status(403).json({ error: Invalid state }); } const tokenResponse await axios.post(https://zoom.us/oauth/token, null, { params: { grant_type: authorization_code, code, redirect_uri: process.env.ZOOM_APP_REDIRECT_URI, code_verifier: req.session.codeVerifier }, headers: { Authorization: Basic Buffer.from( ${process.env.ZOOM_APP_CLIENT_ID}:${process.env.ZOOM_APP_CLIENT_SECRET} ).toString(base64) } }); req.session.tokens { access_token: tokenResponse.data.access_token, refresh_token: tokenResponse.data.refresh_token, expires_at: Date.now() (tokenResponse.data.expires_in * 1000) }; // 用完即清缩短泄露窗口 delete req.session.codeVerifier; delete req.session.state; res.json({ success: true }); });前端侧In-Client OAuth最佳体验流程为fetch(/api/auth/challenge)获取 challenge →zoomSdk.authorize({ codeChallenge, state })→ 监听onAuthorized事件把{ code, state }POST 给后端。详情见 in-client-oauth.md 与 oauth.md。注意 SKILL.md 强调config({ capabilities: [...] })中必须列出authorize和onAuthorized并且对应 OAuth scopezoomapp:inmeeting必须在 Marketplace 开启否则能力会静默失败。令牌存储永远留在服务端绝对禁止在前端localStorage、sessionStorage、Cookie存储任何访问令牌。参考选型表存储方案适用场景安全特性Redis多实例生产服务器快、支持 TTL 自动过期、可水平扩展加密会话单服务器、简单应用与服务器进程绑定Firestore/DynamoDBServerlessFirebase/Lambda持久化、托管服务加密数据库带用户账户的复杂应用完全可控、静态加密Redis 令牌存储示例const Redis require(ioredis); const redis new Redis(process.env.REDIS_URL); async function storeTokens(zoomUserId, tokens) { await redis.set( zoom:tokens:${zoomUserId}, JSON.stringify(tokens), EX, tokens.expires_in // 令牌过期即自动清除 ); } async function getTokens(zoomUserId) { const data await redis.get(zoom:tokens:${zoomUserId}); return data ? JSON.parse(data) : null; }令牌刷新1 小时过期是硬约束Zoom access token 1 小时后过期且 refresh token 为一次性每次刷新都会返回新的 refresh_token。仓库的 in-client-oauth.md 提供了过期前 5 分钟自动刷新的中间件模式async function ensureAuthorized(req, res, next) { if (!req.session.tokens) { return res.status(401).json({ error: Not authorized }); } // 5 分钟内过期则提前刷新 if (req.session.tokens.expires_at Date.now() 300000) { try { await refreshTokens(req); } catch (error) { return res.status(401).json({ error: Token refresh failed }); } } next(); }common-issues.md 明确指出REST API 返回 403 的常见原因就是令牌过期未刷新。State 参数OAuth 回调的 CSRF 防线每次发起 OAuth 前生成随机 state回调时严格比对const crypto require(crypto); // 重定向前生成 state 并存入会话 const state crypto.randomBytes(16).toString(hex); req.session.oauthState state; // 回调时校验 app.get(/auth, (req, res) { if (req.query.state ! req.session.oauthState) { return res.status(403).send(Invalid state - possible CSRF attack); } // 通过后继续换令牌 });从源码结构看oauth.md 的 Web 重定向流程、in-client-oauth.md 的/api/auth/token端点以及本 security.md 的/auth校验逻辑三处实现一致state 必须先存服务端会话、回调必须比对、不匹配必须 403。这是防止 CSRF攻击者诱导用户带上合法会话发起 OAuth的统一约定。数据访问分层与最小权限原则Zoom App 有三级数据访问面风险逐级递增层访问内容授权方式风险等级SDK上下文会议上下文、用户信息、UI 控件config()声明的 capabilities低 - 限定当前上下文REST API服务端完整 Zoom API用户、会议、录制OAuth access token中 - 数据面广X-Zoom-App-Context用户身份、会议信息Client Secret 解密低 - 只读身份信息其中X-Zoom-App-Context是 Zoom 加载前端时附带的加密头用 Client Secret 派生 AES-256-GCM 密钥解密后可得uid、mid、aud、iss、ts等字段可在不触发 OAuth 的情况下识别用户身份详细实现见 architecture.md 的decryptContext函数。最小权限原则只申请你真正需要的 OAuth scope 和 SDK capability。capabilities 必须与 Marketplace 中启用的 scope 一一对应例如getMeetingContext/getUserContext/shareApp都依赖zoomapp:inmeeting缺少 scope 时能力会静默失败或抛错且新增 scope 需要用户重新授权。Marketplace 安全审查自查清单在提交审查前逐项核对完整清单见 security.md所有响应都设置了 OWASP 头全站强制 HTTPS无 HTTP 端点OAuth 流程使用 PKCEOAuth 回调校验 state 参数令牌存服务端绝不放前端已实现令牌刷新令牌 1 小时过期Cookie 设置SameSiteNone; SecureCSP 允许frame-ancestors zoom.us *.zoom.us生产环境不把敏感数据打到 console所有密钥走环境变量无硬编码凭据关于环境变量管理仓库 environment-variables.md 给出约定ZOOM_APP_CLIENT_ID、ZOOM_APP_CLIENT_SECRET、ZOOM_APP_REDIRECT_URI必填SESSION_SECRET建议必填ZOOM_ACCESS_TOKEN/ZOOM_REFRESH_TOKEN是运行期值OAuth 流程中动态生成严禁写进仓库文件Client Secret 仅存在于服务端并建议开发与生产使用独立的应用凭据。易踩坑速查结合 common-issues.md 与 SKILL.md 的 Gotchas安全相关的高频故障如下现象根因修复面板空白域名未加 Domain Allowlist或 CSP 头缺失Marketplace 加白名单 补frame-ancestorsCookie 不持久未设sameSite:none/secure:true按上文 cookie-session 配置OAuth 换令牌 400redirect URI 与 Marketplace 不一致两边逐字符对齐REST API 403access token 过期用 refresh_token 实现刷新能力静默失败capability 与 scope 不匹配config() 与 Marketplace Scopes 双向核对小结Zoom App 的安全基线可以概括为五条主线响应头管嵌入frame-ancestors是生死线、TLS 管传输最低 1.2、自签必挂、Cookie 管会话SameSiteNone; Secure缺一不可、PKCE state 管授权防授权码拦截与 CSRF、服务端令牌管数据前端零令牌、1 小时过期必刷新。按 security.md 的清单逐项落地再配合 RUNBOOK.md 的预检流程验证即可同时满足 Marketplace 审查要求与生产环境稳定性。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考