单点登录
让成员通过公司的身份提供商使用 SAML 登录,并可要求组织成员必须通过此方式登录。
单点登录(SSO)让公司成员通过 Okta、Microsoft Entra ID 等身份提供商登录 Lingo.dev。你只需通过 SAML 2.0 连接一次身份提供商。此后,凡是身份提供商允许登录、且邮箱属于已连接域名的用户,都会在首次登录时加入你的组织,无需邀请。
你也可以强制使用 SSO。启用后,只有通过身份提供商登录的用户才能访问组织。
开始之前 #
- 使用 SSO 需要 Enterprise 套餐。请参阅账单和功能访问。
- 相关设置位于设置 → SSO。
- 只有所有者才能连接、更改、强制使用或断开 SSO。拥有
org:manage_settings但并非所有者的成员可以查看设置,但不能更改。他们会看到:“只有所有者才能更改单点登录。请联系此组织的所有者进行操作。”请参阅角色与权限。 - 所有者是指在 Lingo.dev 组织中拥有所有者角色的用户。Okta 或 Microsoft Entra ID 的管理员身份并不赋予此角色。身份提供商的管理员负责在相应平台中配置应用,再由 Lingo.dev 所有者连接该应用。
- SSO 设置仅限所有者更改,因为控制身份提供商的人可以以任何使用 SSO 的成员身份登录,包括所有者。
- 开启强制使用 SSO还必须由已通过身份提供商登录的所有者操作。请参阅开启。
- 使用你要连接的域名下已验证的邮箱地址,通过密码、邮件链接或 Google 登录 Lingo.dev。
- 你的身份提供商必须支持 SAML 2.0。
身份提供商所需的配置值 #
设置 → SSO 会显示以下配置值,并提供复制按钮。所有组织使用的值都相同。
| Lingo.dev 标签 | 值 | Okta 字段 | Microsoft Entra ID 字段 |
|---|---|---|---|
| 实体 ID | https://auth.lingo.dev/auth/v1/sso/saml/metadata | 受众 URI(SP 实体 ID) | 标识符(实体 ID) |
| ACS URL | https://auth.lingo.dev/auth/v1/sso/saml/acs | 单点登录 URL | 回复 URL(断言使用者服务 URL) |
| 服务提供商元数据 | https://auth.lingo.dev/auth/v1/sso/saml/metadata | 不需要 | 不需要 |
仅当身份提供商支持通过 URL 读取这些设置时,才使用服务提供商元数据 URL。
连接 SSO 后,设置 → SSO 还会显示组织的仪表板登录链接。该链接用于仪表板磁贴,而非 SAML 应用。请参阅通过仪表板磁贴登录。
SAML 响应必须包含用户的邮箱地址:
- 在 Okta 中,将名称 ID 格式设为 EmailAddress,并添加一条
email属性语句。 - 在 Microsoft Entra ID 中,通过 Entra 管理中心创建的应用默认会发送
emailaddress声明和电子邮件格式的名称 ID。创建时未包含默认声明的应用(例如通过 API 创建的应用)不会发送邮箱地址。请在属性 & 声明中添加电子邮件声明(user.mail)。
连接身份提供商 #
- 在身份提供商中,使用上述配置值为 Lingo.dev 创建 SAML 应用。分步指南:Okta 和 Microsoft Entra ID。
- 将需要使用 Lingo.dev 的人员或组分配给该应用。
- 复制应用的 SAML 元数据 URL。该 URL 以
https://开头。 - 在 Lingo.dev 中,打开设置 → SSO。
- 将 URL 粘贴到身份提供商元数据 URL 中。
- 在邮箱域名中输入公司的邮箱域名,多个域名用逗号分隔。例如,
example.com, eu.example.com。 - 选择连接。
此时,状态会显示连接时间及相应日期。要测试连接,请打开浏览器隐私窗口,按成员如何登录中的说明,使用一位已分配用户的身份登录。
域名规则 #
- 每个域名必须与你自己的邮箱域名相同,或是其子域名。如果你以
jane@example.com登录,可以添加example.com和eu.example.com,但不能添加example.org。如需添加其他域名,请联系使用该域名邮箱的管理员。 - 不接受免费或临时邮箱服务商的域名及其子域名,例如
gmail.com或yahoo.es。同样不接受lingo.dev。 - 成员只能通过已添加的域名加入组织,且域名必须完全匹配。添加
example.com并不涵盖eu.example.com:请逐一添加成员登录时使用的子域名。 - 可以使用国家二级注册域下的公司域名,例如
acme.net.ua或acme.co.uk,但不接受注册域本身,例如net.ua。 - 一个域名只能属于一个组织。如果该域名已被其他组织使用,请发送邮件至 support@lingo.dev 申请转移。
- 域名一旦添加,就会一直归属于你的组织,无法移除,即使断开连接后也不例外。
- 添加新域名时,所有者必须通过密码、邮件链接或 Google 登录。通过 SSO 创建的账号无法添加域名。
更改连接 #
要添加域名或更改元数据 URL,请编辑设置 → SSO 中的字段,然后选择保存。此操作仅限所有者执行,且需要 Enterprise 套餐。
一个身份提供商只能连接一个组织。如需为组织更换身份提供商,或将身份提供商从其他组织转移过来,请发送邮件至 support@lingo.dev。
身份提供商轮换签名证书后,请打开设置 → SSO,无需更改任何字段,直接选择保存。这会从 URL 重新加载包含新证书的元数据。请勿依赖 Lingo.dev 自动获取新证书。在选择保存之前,登录可能会失败,并提示“单点登录未完成”。
成员如何登录 #
- 在 Lingo.dev 登录页面上,选择使用 SSO 继续。
- 输入工作邮箱,然后选择登录。
- 在公司的登录页面上登录。
- 你将以组织成员身份返回 Lingo.dev。
你输入的邮箱仅用于查找公司的身份提供商,能否登录由身份提供商决定。如果浏览器已登录身份提供商,就会继续使用该账号,通常无需再次输入密码。随后,Lingo.dev 会使用身份提供商发送的邮箱地址。
退出 Lingo.dev 不会同时退出身份提供商。只要该会话仍然有效,下次选择使用 SSO 继续就会直接重新登录。
用户首次通过 SSO 登录时就会加入组织,无需邀请。
- 如果你的套餐启用了角色功能,用户加入时将没有角色。请在设置 → 团队中为其分配角色。请参阅团队。
- 如果未启用角色功能,用户将以所有者身份加入。
通过 SCIM 添加的用户则会以邀请中指定的角色加入。请参阅通过 SCIM 预配成员。
CLI(lingo login)和 MCP 客户端会打开 Lingo.dev 登录页面,该页面也提供使用 SSO 继续选项。
SSO 会创建独立账号
首次通过 SSO 登录时,系统会创建一个新的 Lingo.dev 账号,即使用户已有使用相同邮箱通过密码、邮件链接或 Google 登录的账号。这些账号不会合并。SSO 账号不会继承旧账号的角色、组织或个人 API 密钥。
团队列表中可能会出现两个相同的邮箱地址,分别对应旧账号和 SSO 账号。请为 SSO 账号分配用户所需的角色,并在不再需要旧账号时将其移除。
通过仪表板磁贴登录 #
成员也可以通过 Okta 仪表板或 Microsoft“我的应用”中的 Lingo.dev 磁贴登录。磁贴必须打开设置 → SSO 中的仪表板登录链接。该链接的形式为 https://lingo.dev/auth/sso?domain=example.com,其中包含你首次连接的域名。
该链接会从 Lingo.dev 发起登录,成员无需输入邮箱。他们会前往身份提供商,并在登录后返回,与使用 SSO 继续的流程相同。
- 在 Okta 中,使用该链接添加一个书签应用,并隐藏 SAML 应用自身的图标。请参阅通过 Okta 仪表板登录。
- 在 Microsoft Entra ID 中,将该链接粘贴到 SAML 应用的登录 URL 中。请参阅通过 Microsoft“我的应用”登录。
如果不使用该链接,SAML 应用自身的磁贴无法完成登录。你会进入 Lingo.dev 首页,但仍处于未登录状态。
强制使用 SSO #
开启强制使用 SSO 后:
- 用户必须通过身份提供商登录,才能访问此组织。
- 密码、邮件链接和 Google 登录将无法用于访问此组织。用户仍可通过这些方式登录,其他组织也不受影响。你的组织会在他们的列表中显示需要 SSO,打开时会提示使用 SSO 继续。
- 非 SSO 加入的账号所创建的个人 API 密钥,将无法在此组织中使用。
- 组织服务密钥仍可用于 Lingo.dev API 的各项操作。请使用这些密钥进行 CI 和其他自动化操作。请参阅API 密钥。
- 如果 MCP 客户端连接的账号并非通过 SSO 登录,就无法使用此组织。请通过 SSO 登录后重新连接。请参阅MCP 连接设置。
开启 #
开启强制使用 SSO 必须由已通过身份提供商登录的所有者操作。你的 SSO 账号是独立账号,不会继承旧账号的所有者角色。开始之前,请先将其设为所有者。
- 选择使用 SSO 继续登录 Lingo.dev。这会将你的 SSO 账号加入组织。
- 如果你的套餐启用了角色功能,SSO 账号加入时将没有角色。请使用现有的所有者账号,在设置 → 团队中将 SSO 账号设为所有者。如果未启用角色功能,该账号加入时就已是所有者。
- 使用 SSO 账号登录后,打开设置 → SSO,开启强制使用 SSO。
在你通过身份提供商登录之前,此开关会保持关闭,以免你在密码登录会话中开启此选项后,将自己锁在组织之外。
关闭 #
所有者可以在设置 → SSO 中关闭强制使用 SSO。关闭后,用户就可以再次通过密码、邮件链接或 Google 访问组织。即使套餐已不再支持 SSO,你仍可以关闭此选项。
保留访问途径
强制使用 SSO 时,只有 SSO 账号才能访问组织及其设置。请保留至少一位通过身份提供商登录的所有者。Lingo.dev 不允许最后一位这样的所有者离开组织或放弃所有者角色。如果身份提供商无法正常工作,请发送邮件至 support@lingo.dev。
通过 SCIM 预配成员 #
SCIM 让身份提供商决定组织的成员资格。将用户分配给 Lingo.dev 应用会向其发出邀请,取消分配则会将其移除。角色通过组设置,用户仍通过 SSO 登录。
设置指南:Okta 和 Microsoft Entra ID。
设置 SCIM 之前 #
- 必须先连接 SSO,这需要 Enterprise 套餐。
- 只有所有者才能在设置 → SSO 中查看 SCIM 密钥,并生成、轮换或撤销密钥。
- SCIM 密钥会以你选择的角色执行操作。该角色必须包含
org:manage_team,且不能是所有者。请参阅角色与权限。 - 只有当密钥所用的角色拥有目标角色的全部权限时,密钥才能通过组分配该角色。
生成 SCIM 密钥 #
- 打开设置 → SSO。SCIM 基础 URL 和 SCIM 密钥位于强制使用 SSO 下方。
- 在 SCIM 密钥旁,选择密钥执行操作时使用的角色。
- 选择生成密钥。
- 复制密钥并妥善保存。Lingo.dev 只会显示一次。然后选择我已保存。
- 复制 SCIM 基础 URL:
https://api.lingo.dev/v2/scim。
身份提供商会将密钥作为 Bearer 令牌发送到基础 URL。该密钥仅用于 SCIM,不会列在其他 API 密钥中。
如果没有可供密钥使用的角色,角色选择器会显示无角色,且生成密钥不可用。请先为所有者以外的角色授予 org:manage_team 权限。
分配人员 #
- 将用户分配给 Lingo.dev 应用后,系统会在设置 → 团队的邀请选项卡中创建一条待接受的邀请。系统不会发送邮件,邀请将在 100 年后过期。
- 用户首次通过 SSO 登录时,会以邀请中指定的角色成为成员。
- 如果用户已经是成员,SCIM 会将其关联到现有成员身份,而不再创建邀请。
- SCIM 仅接受已连接域名下的邮箱地址。对于其他邮箱地址,身份提供商会显示错误。
- 未通过 SCIM 同步的用户仍可在首次通过 SSO 登录时加入。请参阅成员如何登录。
通过组设置角色 #
- 推送一个与 Lingo.dev 角色同名的组,例如
Translator,名称不区分大小写。组成员会获得该角色;将用户从组中移除时,其角色也会被清除。 - 组不会将任何人设为所有者,也不会更改所有者的角色。请在设置 → 团队中管理所有者。
- 如果组名与任何角色都不匹配,推送会被拒绝,身份提供商会显示错误。请先在 Lingo.dev 中创建该角色。
- 每位用户只有一个角色。如果用户属于多个已推送的组,则以最后推送的组为准。
- 如果在 Lingo.dev 中重命名角色,之后推送的组必须使用新名称。已推送的组仍会继续分配该角色。
- 如果身份提供商删除了 Lingo.dev 中已推送的组,组成员会失去该角色,但角色本身会保留。
移除人员 #
在身份提供商中取消分配或停用用户会:
- 移除其成员资格;
- 撤销其在组织中的个人 API 密钥;
- 撤销其加入组织的待接受邀请;
- 只要组织仍有 SCIM 密钥,就阻止该用户通过 SSO 再次加入。
用户现有的 Lingo.dev 会话不会结束,但将无法再访问组织。如果再次通过 SSO 登录,他们会看到:“你的身份提供商已移除你对组织的访问权限。如果这是误操作,请联系 IT 管理员恢复权限。”
所有者也可以通过这种方式移除。但如果要移除的是最后一位所有者,身份提供商会显示错误。
分配或重新激活用户会创建一条新的待接受邀请,且不分配角色。当身份提供商推送用户所在的组时,用户会重新获得角色。
轮换或撤销密钥 #
在 SCIM 密钥设置中,选择轮换或撤销都需要确认。
- 轮换会以你选择的角色创建新密钥,并立即撤销旧密钥。在你将新密钥粘贴到身份提供商之前,预配会失败。关闭前,请先复制新密钥。
- 撤销会立即阻止身份提供商添加、更新和移除成员。组织中的现有成员会保留。此前被身份提供商移除的用户可以通过 SSO 登录再次加入。
如果轮换时未能撤销旧密钥,设置中会显示“上一个 SCIM 密钥仍然有效。”选择撤销可仅撤销上一个密钥,新密钥仍然有效。
审计日志会将通过 SCIM 进行的更改记录为由 SCIM 密钥执行。
身份提供商中的错误 #
| 错误 | 处理方法 |
|---|---|
| /Groups 中没有名为(组)的角色。请在 Lingo.dev 中创建同名角色,或仅推送以角色命名的组。 | 创建与组同名的角色,或停止推送该组。 |
| /Groups 中出现所有者角色。所有者在 Lingo.dev 中管理;请推送以其他角色命名的组。 | 组无法分配所有者角色。请在设置 → 团队中设置所有者。 |
| /Users 中的邮箱(地址)不属于单点登录域名。请预配(域名)下的邮箱地址。 | 仅分配邮箱属于已连接域名的用户,或在设置 → SSO 中添加该域名。 |
| 组织(ID)未连接身份提供商。请重新连接单点登录,以恢复 SCIM 预配。 | SSO 已断开连接。请重新连接。 |
| 组织(ID)的套餐不支持单点登录。请升级套餐,以恢复 SCIM 预配。 | 请在账单中查看你的套餐。 |
401 Unauthorized | 密钥已轮换或撤销。请将当前的 SCIM 密钥粘贴到身份提供商中,或生成新密钥。 |
SCIM 限制 #
- Lingo.dev 不显示 SCIM 密钥的上次使用时间。
- SSO 断开连接或您的套餐不包含 SSO 时,SCIM 会停止运行。成员保持不变。
- Google Workspace 不为自定义 SAML 应用提供 SCIM。
断开连接 #
只有所有者可以断开连接。
- 打开设置 → SSO。
- 在断开身份提供商连接下,选择断开连接。
- 选择断开连接,确认操作。
组织将停用 SSO,也不再要求使用 SSO。成员可重新使用密码、邮件链接或 Google 登录。状态会显示断开连接日期及相应日期。
成员资格保持不变。您的域名仍为该组织保留,方便您日后重新连接:使用同一身份提供商,选择连接即可。如需使用其他身份提供商,请联系 support@lingo.dev 寻求帮助。
SSO 断开连接期间,通过 SSO 创建的账户将失去对组织的访问权限,已打开的会话也不例外。使用 SSO 继续会提示该域名尚未设置单点登录;使用同一邮箱通过密码、邮件链接或 Google 登录,则会进入另一个独立账户。这些 SSO 账户仍保留成员资格,在您重新连接同一身份提供商后,便会恢复访问权限。重新连接之前,任何人都无法通过 SSO 加入组织。若要在此期间继续工作,用户需要使用各自的密码、邮件链接或 Google 账户登录,且对应账户须有自己的成员资格。如果您自己也是通过 SSO 登录的,同样会失去访问权限。因此,断开连接前,请务必让另一位所有者使用密码、邮件链接或 Google 登录。
如果您的套餐不再包含 SSO #
您的连接仍会显示在设置 → SSO中,并附有提示。所有者仍可关闭强制使用 SSO并断开连接。若要连接、更改连接或开启强制使用 SSO,则需要重新订阅 Enterprise 套餐。
在您做出更改之前,SSO 登录和强制使用 SSO会继续照常运行。
审计日志 #
SSO 的更改会显示在审计日志中,并记录操作人:
| 操作 | 显示为 | 发生时间 |
|---|---|---|
sso.connected | 已连接单点登录 | 首次连接,或断开连接后重新连接 |
sso.updated | 已更新单点登录 | 在已连接的身份提供商设置中选择保存,例如更新元数据 URL 或添加更多域名 |
sso.enforcement_enabled | 已强制使用单点登录 | 开启强制使用 SSO |
sso.enforcement_disabled | 已停止强制使用单点登录 | 关闭强制使用 SSO |
sso.disconnected | 已断开单点登录连接 | 身份提供商断开连接 |
当用户首次通过 SSO 登录并加入组织时,会显示为“已加入组织”。
故障排查 #
登录提示 #
| 提示 | 处理方法 |
|---|---|
| 请输入您的工作邮箱。单点登录会根据邮箱域名启动。 | 请输入完整的邮箱地址,例如 you@example.com。 |
| 您的邮箱域名不在组织用于单点登录的域名范围内。请使用公司域名下的工作邮箱登录。 | 身份提供商为您登录时使用的邮箱不属于组织已连接的域名,例如个人邮箱或未列出的子域名邮箱。请使用工作账户登录身份提供商,或请所有者添加该域名。 |
| example.com 尚未设置单点登录。请使用密码、链接或 Google 登录。 | 没有已连接的组织使用该域名。请检查拼写,或询问管理员已连接了哪些域名。 |
| 无法检查 example.com 的单点登录。请稍后重试。 | Lingo.dev 无法查询该域名。请重试。 |
| 单点登录耗时过长。请重试。 | 登录耗时超过了约 5 分钟,例如身份提供商要求您设置多重身份验证时。请重试,下次尝试即可成功。 |
| 身份提供商未发送邮箱地址。请让 IT 管理员为 Lingo.dev 应用添加邮箱属性或声明。 | SAML 响应中没有邮箱地址。请参阅 Okta 或 Microsoft Entra ID 指南。 |
| 单点登录未完成。请重试,或让 IT 管理员检查身份提供商中的 Lingo.dev 应用。 | 这通常是因为身份提供商应用中的实体 ID或 ACS URL 不正确。请与上面的值核对。 |
| 您已登录,但我们无法将您添加到组织。请重试,或咨询管理员。 | 您的 SSO 登录已成功,但未能加入组织。请再次使用 SSO 登录。在 CLI 或 MCP 客户端中,此提示会显示在连接页面;重新加载页面即可重试。如果仍然失败,请让所有者检查设置 → SSO是否显示连接起始日期。 |
| 此组织要求使用单点登录。请通过身份提供商登录,然后重试。 | 您使用其他登录方式打开了一个已开启强制使用 SSO的组织。请选择使用 SSO 继续。如果您当前登录的邮箱不是工作邮箱,请选择使用其他工作邮箱。 |
身份提供商的错误(例如 Microsoft 的 AADSTS 代码)会显示在其自身的登录页面上。相关身份提供商指南介绍了常见错误。
设置提示 #
| 提示 | 处理方法 |
|---|---|
| 只有所有者可以更改单点登录。请让此组织的所有者操作。 | 您可以查看 SSO 设置,但只有所有者可以更改。请联系所有者。 |
| example.com 不是您的邮箱域名。 | 请仅添加您自己的邮箱域名或其子域名,或请邮箱地址属于该域名的管理员操作。 |
| gmail.com 是公共邮箱服务提供商。请使用公司拥有的域名。 | 免费邮箱和一次性邮箱的域名无法使用 SSO。请添加公司拥有的域名。 |
| lingo.dev 是保留域名。请使用公司拥有的域名。 | 请添加公司拥有的域名。 |
| example.com 已在通过另一组织的身份提供商登录。 | 如需转移,请发送邮件至 support@lingo.dev。 |
| 身份提供商的元数据被拒绝:(原因)。请检查元数据 URL。 | 请从身份提供商应用中重新复制元数据 URL。该 URL 必须是可公开访问的 https:// URL。 |
| 此元数据所属的身份提供商与当前连接的身份提供商不同。 | 如需切换身份提供商,请联系 support@lingo.dev 寻求帮助。 |
| 此身份提供商已连接到另一个组织。 | 如需转移,请发送邮件至 support@lingo.dev。 |
| 请先通过身份提供商登录,再开启此功能。 | 请选择使用 SSO 继续进行登录,然后开启强制使用 SSO。 |
| 强制使用 SSO 需要 Enterprise 套餐。 | 请在账单中查看您的套餐。 |
已知限制 #
- 只有邮箱属于已连接域名的账户才能加入组织,且域名必须完全匹配。身份提供商仍可能允许其他人登录,例如使用个人邮箱的访客,或使用您未添加的子域名邮箱的用户。Lingo.dev 会让他们退出登录,并显示原因。请在身份提供商中仅将应用分配给合适的人员,并添加成员登录时使用的每个子域名。
- 用户此前通过密码、邮件链接或 Google 登录的账户角色不会沿用。
- 在身份提供商中移除某人,不会结束其已打开的 Lingo.dev 会话。Lingo.dev 不会在会话期间再次向身份提供商核查。使用 SCIM 时,移除操作也会终止其成员资格,因此该会话将无法再访问组织。不使用 SCIM 时,会话会继续有效,直到用户退出登录,因此还需在设置 → 团队中将其移除。
- 如果您在 Lingo.dev 中移除了成员,但身份提供商仍允许其登录,那么无论是否使用 SCIM,该成员都会在下次通过 SSO 登录时重新加入。使用 SCIM 时,请在身份提供商中移除该成员;这也会移除其成员资格,并防止其再次加入。不使用 SCIM 时,请先在身份提供商中移除该成员,再在设置 → 团队中移除。
- 只有在仪表板磁贴打开仪表板登录链接时,您才会登录。Okta 仪表板或 Microsoft My Apps 中 SAML 应用自带的磁贴会将您带到 Lingo.dev 首页,但您仍处于未登录状态。请参阅通过仪表板磁贴登录。
- 您无法自行移除域名或切换身份提供商。请发送邮件至 support@lingo.dev。