如何为 Cap 组织启用 SAML SSO 并完成 WorkOS 配置【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap如果你的 Cap 组织需要让员工通过企业身份提供方IdP登录就需要为组织启用 SAML SSO。Cap 使用 WorkOS Single Sign-On 与现有 NextAuth 会话集成每个组织拥有独立的 SSO 权益和显式的 WorkOS 组织映射。完成这篇文章后你可以按顺序完成服务端环境变量配置、WorkOS 重定向与限流配置、组织内的购买与域名验证操作以及启用客户前的数据库预检与真实登录流程验证。依据来自 docs/saml-sso.md。服务端环境变量在部署环境server-only中设置以下变量这是 SSO 运行的前置条件变量要求WORKOS_API_KEY目标 WorkOS 环境中可用的密钥WORKOS_CLIENT_ID同一 WorkOS 环境的 client IDWEB_URL、NEXTAUTH_URL规范的 HTTPS 部署源地址NEXTAUTH_SECRET现有的高强度会话密钥同时用于签署短期 SSO intentSTRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET与同一环境匹配的 Stripe 凭据和 webhook 端点凭据STRIPE_SAML_SSO_PRICE_ID可选的生产环境覆盖值如需使用单独的测试/开发 Stripe 价格则为必需注意 API key 与 client ID 必须来自同一个 WorkOS 环境。计费方面SSO 订阅与 Cap Pro 席位和 Signed BAA 附加项独立计费。默认生产价格为price_1UBJpTFJxA1XpeSsQmAOhibr其支持的货币金额从 Stripe 读取而不在浏览器端换算在生产之外做测试时应使用每月、数量为 1 的测试价格和测试 Stripe 密钥因为生产价格 ID 在 Stripe 测试模式下不存在。配置 WorkOS 重定向与限流在 WorkOS 端为相同环境配置重定向设置用途生产 URLOAuth callback / redirect URIhttps://cap.so/api/auth/callback/workosSSO 登录 / initiate-login 端点https://cap.so/loginAdmin Portal 返回/成功基础地址https://cap.so/dashboard/settings/organization/securityCap 会提供组织范围内的 Admin Portal 返回与成功 URLAPI 生成的链接是短期的 bearer 凭据应当立即打开不要存储或写入日志。做完整的 Admin Portal 测试时请使用 HTTPS 预览源。同时配置 Vercel Firewall SDK 限流规则rl_auth_sso_start文档给出的示例是每 IP 每分钟 20 次。需要知道共享限流助手是尽力而为的规则缺失或防火墙不可用时会 fail open——仅仅部署规则 ID 并不会启用限流。自托管部署应提供等价的边界保护。组织内购买与 SAML 设置操作以下操作在 Cap 产品界面内完成角色有明确区分只有 owner 可以购买和管理计费owner 和 admin 可以配置 WorkOSmember 无法获取 Admin Portal 链接。组织 owner 打开Settings → Organization → Security Compliance购买每月 SAML SSO 附加项。已有订阅者自动沿用当前 Stripe 计费货币无需选择货币没有现有订阅的 owner 可以选择已配置的 USD、GBP 或 EUR 金额。Checkout 在打开支付会话前会再次校验 owner 的计费货币。支付确认后owner 和 admin 可以使用Verify domain。Cap 会创建或复用该组织的 WorkOS 组织并打开托管的域名验证流程域名已验证的组织跳过此步骤。域名验证完成后Set up SAML SSO打开 WorkOS 的 SSO 设置流程由 IT 管理员配置身份提供方。如还需验证更多域名Verify domains仍然可用。仅完成支付不会验证任何域名。团队随后在登录页选择 SAML SSO输入工作邮箱/域名或通过组织的登录链接进入IdP 发起的访问/login?connection_id...走同样的受保护授权流程。已有 Cap 账户的用户可以通过/login?sso1显式进入 SSO。登录成功后的归属行为已验证身份会被绑定用户加入对应的 Cap 组织。新成员获得member角色且不带 Pro 席位已有角色、席位和默认组织保持不变SSO 组织成为活动组织。注意组织登录链接在已登录状态下也能工作但 SSO 身份不能附加到另一个当前已登录的账户该用户必须先登出。启用客户前的数据库预检与迁移在应用迁移0041_saml_sso之前暂停对 WorkOS 组织绑定的变更并在目标数据库的主连接上运行文档给出的只读预检查询SELECT COUNT(*) AS duplicate_mapping_groups FROM ( SELECT workosOrganizationId FROM organizations WHERE workosOrganizationId IS NOT NULL GROUP BY workosOrganizationId HAVING COUNT(*) 1 ) AS duplicate_mappings;该结果必须在任何 schema 部署前为零。此查询覆盖所有组织包括已标记删除的行和空字符串绑定因为唯一约束对这些行同样生效。查询失败或返回非零数量时先停止不要应用任何迁移 DDL独立核对冲突的 Cap 与 WorkOS 身份用 compare-and-set 更新对账绑定绝不自动删除、合并或改派组织。对账后重复执行查询并在唯一约束落地前保持绑定写入暂停。通过该关卡后先部署增量迁移再部署应用变更。迁移对应文件为 0041_saml_sso.sql新建organization_sso表含组织、购买者、Stripe 客户/订阅、支付确认的访问周期和持久的 checkout 预留并在organizations.workosOrganizationId上添加唯一约束。迁移由 schema.ts 通过bun run db:generate --namesaml_sso生成生成 SQL 及其 snapshot/journal 元数据应一起提交不要手工编辑 SQL。迁移0041跟随现有 recording-jobs 迁移并保留其 snapshot 谱系。已有映射的组织需要对账而不是静默授予未付费访问。某个环境或更早时间的成功预检不能授权另一次部署也不要为了测试把 schema 直接推送到共享的本地或生产数据库。启用客户前的验证在启用某个客户之前在候选部署上用真实的 WorkOS 流程逐项验证文档列出的清单是owner 购买/确认、admin 设置与域名验证、SP 发起与 IdP 发起的登录、新成员、已有账户、重复/并发登录、错误域名/组织的拒绝以及 native app 返回。另外在 Stripe 测试模式下检查取消、续费失败、webhook 重试以及 Pro/BAA 隔离。代码层面的回归测试位于 apps/web/tests/unit/sso-*.test.ts与现有 auth、mobile、Pro、BAA、webhook 回归套件并列apps/web/tests/integration/sso-database.test.ts 使用真实 MySQL要求CAP_SSO_TEST_DATABASE_URL指向一个名为cap_sso_*的本地会话级数据库它拒绝生产/非本地 URL并保留其合成 fixture 供检查。注意单元测试、mock 和本地数据库测试不能证明真实 IdP 往返因此上述真实流程验证不可省略。已知限制启用 SSO 前需要向团队说明边界文档明确列出该功能不提供不强制 SSO-only 登录标准 Cap 登录仍然可用不实现 SCIM/去配给用户离开 IdP 时不撤销其现有 Cap 会话不提供 SAML 单点登出single logout。文档提醒不要把这些当作已交付的企业级管控来呈现。另外当默认连接存在歧义时基于域名的发现会被阻断但设置页仍可访问以便修复显式的活动 IdP 连接仍会与映射组织做校验。设置页和登录会直接查询 WorkOS因此禁用/重置连接无需 webhook 缓存即可被识别。【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何为 Cap 组织启用 SAML SSO 并完成 WorkOS 配置？
如何为 Cap 组织启用 SAML SSO 并完成 WorkOS 配置【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap如果你的 Cap 组织需要让员工通过企业身份提供方IdP登录就需要为组织启用 SAML SSO。Cap 使用 WorkOS Single Sign-On 与现有 NextAuth 会话集成每个组织拥有独立的 SSO 权益和显式的 WorkOS 组织映射。完成这篇文章后你可以按顺序完成服务端环境变量配置、WorkOS 重定向与限流配置、组织内的购买与域名验证操作以及启用客户前的数据库预检与真实登录流程验证。依据来自 docs/saml-sso.md。服务端环境变量在部署环境server-only中设置以下变量这是 SSO 运行的前置条件变量要求WORKOS_API_KEY目标 WorkOS 环境中可用的密钥WORKOS_CLIENT_ID同一 WorkOS 环境的 client IDWEB_URL、NEXTAUTH_URL规范的 HTTPS 部署源地址NEXTAUTH_SECRET现有的高强度会话密钥同时用于签署短期 SSO intentSTRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET与同一环境匹配的 Stripe 凭据和 webhook 端点凭据STRIPE_SAML_SSO_PRICE_ID可选的生产环境覆盖值如需使用单独的测试/开发 Stripe 价格则为必需注意 API key 与 client ID 必须来自同一个 WorkOS 环境。计费方面SSO 订阅与 Cap Pro 席位和 Signed BAA 附加项独立计费。默认生产价格为price_1UBJpTFJxA1XpeSsQmAOhibr其支持的货币金额从 Stripe 读取而不在浏览器端换算在生产之外做测试时应使用每月、数量为 1 的测试价格和测试 Stripe 密钥因为生产价格 ID 在 Stripe 测试模式下不存在。配置 WorkOS 重定向与限流在 WorkOS 端为相同环境配置重定向设置用途生产 URLOAuth callback / redirect URIhttps://cap.so/api/auth/callback/workosSSO 登录 / initiate-login 端点https://cap.so/loginAdmin Portal 返回/成功基础地址https://cap.so/dashboard/settings/organization/securityCap 会提供组织范围内的 Admin Portal 返回与成功 URLAPI 生成的链接是短期的 bearer 凭据应当立即打开不要存储或写入日志。做完整的 Admin Portal 测试时请使用 HTTPS 预览源。同时配置 Vercel Firewall SDK 限流规则rl_auth_sso_start文档给出的示例是每 IP 每分钟 20 次。需要知道共享限流助手是尽力而为的规则缺失或防火墙不可用时会 fail open——仅仅部署规则 ID 并不会启用限流。自托管部署应提供等价的边界保护。组织内购买与 SAML 设置操作以下操作在 Cap 产品界面内完成角色有明确区分只有 owner 可以购买和管理计费owner 和 admin 可以配置 WorkOSmember 无法获取 Admin Portal 链接。组织 owner 打开Settings → Organization → Security Compliance购买每月 SAML SSO 附加项。已有订阅者自动沿用当前 Stripe 计费货币无需选择货币没有现有订阅的 owner 可以选择已配置的 USD、GBP 或 EUR 金额。Checkout 在打开支付会话前会再次校验 owner 的计费货币。支付确认后owner 和 admin 可以使用Verify domain。Cap 会创建或复用该组织的 WorkOS 组织并打开托管的域名验证流程域名已验证的组织跳过此步骤。域名验证完成后Set up SAML SSO打开 WorkOS 的 SSO 设置流程由 IT 管理员配置身份提供方。如还需验证更多域名Verify domains仍然可用。仅完成支付不会验证任何域名。团队随后在登录页选择 SAML SSO输入工作邮箱/域名或通过组织的登录链接进入IdP 发起的访问/login?connection_id...走同样的受保护授权流程。已有 Cap 账户的用户可以通过/login?sso1显式进入 SSO。登录成功后的归属行为已验证身份会被绑定用户加入对应的 Cap 组织。新成员获得member角色且不带 Pro 席位已有角色、席位和默认组织保持不变SSO 组织成为活动组织。注意组织登录链接在已登录状态下也能工作但 SSO 身份不能附加到另一个当前已登录的账户该用户必须先登出。启用客户前的数据库预检与迁移在应用迁移0041_saml_sso之前暂停对 WorkOS 组织绑定的变更并在目标数据库的主连接上运行文档给出的只读预检查询SELECT COUNT(*) AS duplicate_mapping_groups FROM ( SELECT workosOrganizationId FROM organizations WHERE workosOrganizationId IS NOT NULL GROUP BY workosOrganizationId HAVING COUNT(*) 1 ) AS duplicate_mappings;该结果必须在任何 schema 部署前为零。此查询覆盖所有组织包括已标记删除的行和空字符串绑定因为唯一约束对这些行同样生效。查询失败或返回非零数量时先停止不要应用任何迁移 DDL独立核对冲突的 Cap 与 WorkOS 身份用 compare-and-set 更新对账绑定绝不自动删除、合并或改派组织。对账后重复执行查询并在唯一约束落地前保持绑定写入暂停。通过该关卡后先部署增量迁移再部署应用变更。迁移对应文件为 0041_saml_sso.sql新建organization_sso表含组织、购买者、Stripe 客户/订阅、支付确认的访问周期和持久的 checkout 预留并在organizations.workosOrganizationId上添加唯一约束。迁移由 schema.ts 通过bun run db:generate --namesaml_sso生成生成 SQL 及其 snapshot/journal 元数据应一起提交不要手工编辑 SQL。迁移0041跟随现有 recording-jobs 迁移并保留其 snapshot 谱系。已有映射的组织需要对账而不是静默授予未付费访问。某个环境或更早时间的成功预检不能授权另一次部署也不要为了测试把 schema 直接推送到共享的本地或生产数据库。启用客户前的验证在启用某个客户之前在候选部署上用真实的 WorkOS 流程逐项验证文档列出的清单是owner 购买/确认、admin 设置与域名验证、SP 发起与 IdP 发起的登录、新成员、已有账户、重复/并发登录、错误域名/组织的拒绝以及 native app 返回。另外在 Stripe 测试模式下检查取消、续费失败、webhook 重试以及 Pro/BAA 隔离。代码层面的回归测试位于 apps/web/tests/unit/sso-*.test.ts与现有 auth、mobile、Pro、BAA、webhook 回归套件并列apps/web/tests/integration/sso-database.test.ts 使用真实 MySQL要求CAP_SSO_TEST_DATABASE_URL指向一个名为cap_sso_*的本地会话级数据库它拒绝生产/非本地 URL并保留其合成 fixture 供检查。注意单元测试、mock 和本地数据库测试不能证明真实 IdP 往返因此上述真实流程验证不可省略。已知限制启用 SSO 前需要向团队说明边界文档明确列出该功能不提供不强制 SSO-only 登录标准 Cap 登录仍然可用不实现 SCIM/去配给用户离开 IdP 时不撤销其现有 Cap 会话不提供 SAML 单点登出single logout。文档提醒不要把这些当作已交付的企业级管控来呈现。另外当默认连接存在歧义时基于域名的发现会被阻断但设置页仍可访问以便修复显式的活动 IdP 连接仍会与映射组织做校验。设置页和登录会直接查询 WorkOS因此禁用/重置连接无需 webhook 缓存即可被识别。【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考