使用 Okta 设置 SSO
在 Okta 中为 Lingo.dev 创建 SAML 应用、分配人员并连接到你的组织,再通过 SCIM 预配成员。
本指南介绍如何通过 SAML 2.0 将 Okta 连接到 Lingo.dev。你需要一个能创建应用集成的 Okta 管理员账户,同时必须是使用 Enterprise 套餐的 Lingo.dev 组织的所有者。有关 Lingo.dev 中 SSO 的工作方式,请参阅单点登录。
请保持 Lingo.dev 的设置 → SSO 页面打开。你需要将其中的两个值复制到 Okta。
创建应用集成 #
- 登录 Okta 管理控制台。
- 前往应用 → 应用(较新的管理控制台中为应用和资源 → 应用),然后选择创建应用集成。
- 选择 SAML 2.0,然后选择下一步。
- 在应用名称中输入
Lingo.dev,然后选择下一步。
配置 SAML #
填写以下字段,其余字段保持默认值:
| Okta 字段 | 值 |
|---|---|
| 单点登录 URL | https://auth.lingo.dev/auth/v1/sso/saml/acs(Lingo.dev 中的 ACS URL) |
| 将此值用于接收方 URL 和目标 URL | 已选中 |
| 受众 URI(SP 实体 ID) | https://auth.lingo.dev/auth/v1/sso/saml/metadata(Lingo.dev 中的实体 ID) |
| 默认 RelayState | 留空 |
| 名称 ID 格式 | EmailAddress |
| 应用用户名 | 电子邮件 |
在属性声明下添加一个属性:
| 名称 | 名称格式 | 值 |
|---|---|---|
email | 未指定 | user.email |
将名称 ID 格式设为 EmailAddress 并添加此 email 属性后,Okta 就会发送 Lingo.dev 所需的电子邮件地址。
较新的 Okta 组织在创建应用时不再显示属性声明。这种情况下,请在选择完成后再添加属性:打开应用的登录选项卡,在属性声明部分选择添加表达式。在名称中输入 email,在表达式中输入 user.profile.email,然后选择保存。
选择下一步。在反馈步骤中,选择我是 Okta 客户,正在添加内部应用,然后选择完成。
复制元数据 URL #
在应用的登录选项卡中,从元数据详情部分复制元数据 URL。其格式类似于 https://your-company.okta.com/app/exk.../sso/saml/metadata。
分配人员 #
- 打开应用的分配选项卡。
- 选择分配,然后选择分配给人员或分配给组。
- 选择每个人员或组旁边的分配,然后选择完成。
只有分配到该应用的人员才能通过 Okta 登录 Lingo.dev。
在 Lingo.dev 中连接 #
- 打开设置 → SSO。
- 将 Okta 元数据 URL 粘贴到身份提供商元数据 URL 中。
- 在电子邮件域名中输入公司的电子邮件域名,多个域名用逗号分隔。
- 选择连接。
如果域名被拒绝,请参阅域名规则。
测试登录 #
- 打开浏览器的无痕窗口,前往 Lingo.dev 登录页面。
- 选择使用 SSO 继续,输入一位已分配人员的电子邮件地址,然后选择登录。
- 登录 Okta。
你会以组织成员的身份返回 Lingo.dev。请检查组织页面上显示的电子邮件地址:它对应的是 Okta 实际用于登录的账户,不一定是你输入的地址。如果浏览器中已有 Okta 会话,例如设置该应用的管理员账户的会话,Okta 就会继续使用该账户登录。如果该管理员未分配到此应用,就会收到“用户未分配到此应用”的提示。因此,测试时需要使用无痕窗口。
请从 Lingo.dev 开始测试。点击 Okta 仪表板上 SAML 应用自身的磁贴并不会完成登录:你会进入 Lingo.dev 首页,但仍处于未登录状态。要从仪表板登录,请按照从 Okta 仪表板登录中的说明添加书签。
测试成功后,你可以强制使用 SSO。请先按照启用中的说明,将你自己的 SSO 账户设为所有者。
从 Okta 仪表板登录 #
要为成员提供可用于登录的 Lingo.dev 磁贴,请添加一个书签应用,让它打开仪表板登录链接。然后隐藏 SAML 应用自身的图标,让成员只看到书签。
- 在 Lingo.dev 中,打开设置 → SSO,复制仪表板登录链接。其格式类似于
https://lingo.dev/auth/sso?domain=example.com。 - 在 Okta 管理控制台中,前往应用 → 应用(较新的管理控制台中为应用和资源 → 应用),然后选择浏览应用目录。
- 搜索并选择书签应用,然后选择添加集成。
- 在常规设置中,将名称设为
Lingo.dev,并将链接粘贴到 URL 字段。不要选中不向用户显示应用图标。选择完成。 - 在书签的分配选项卡中,分配与 SAML 应用相同的人员或组。
- 打开 Lingo.dev SAML 应用。在常规选项卡的应用设置中,选择编辑。
- 在应用可见性下,选中不向用户显示应用图标和不在 Okta 移动应用中显示应用图标。选择保存。
请继续将这些人员分配到 SAML 应用。该应用仍负责完成登录,只是图标被隐藏了。
现在,成员只会看到一个 Lingo.dev 磁贴。点击后会打开 Lingo.dev,再跳转到 Okta,随后返回 Lingo.dev 并完成登录,全程无需输入电子邮件地址。
使用 SCIM 预配成员 #
Okta 可以通过 SCIM 管理 Lingo.dev 成员,并通过组设置成员的角色。请先按照本指南设置 SSO。有关 Lingo.dev 中 SCIM 的工作方式,请参阅使用 SCIM 预配成员。
- 在 Lingo.dev 中,生成 SCIM 密钥。
- 在 Okta 管理控制台中,打开 Lingo.dev SAML 应用。在常规选项卡的应用设置中,选择编辑。
- 将预配设为 SCIM,然后选择保存。应用中会出现预配选项卡。
- 在预配选项卡中,打开集成,然后选择编辑。
填写以下字段:
| Okta 字段 | 值 |
|---|---|
| SCIM 连接器基础 URL | https://api.lingo.dev/v2/scim(Lingo.dev 中的 SCIM 基础 URL) |
| 用户唯一标识符字段 | userName |
| 支持的预配操作 | 推送新用户、推送个人资料更新和推送组。不要选中导入操作。Okta 不会从 Lingo.dev 导入用户或组。 |
| 身份验证模式 | HTTP 标头。将 SCIM 密钥粘贴到 Bearer 令牌字段。 |
选择测试连接器配置。测试通过后,关闭测试窗口并选择保存。
在预配选项卡中,打开到应用,然后选择编辑。启用创建用户、更新用户属性和停用用户,然后选择保存。
保存创建用户设置后,Okta 才会向 Lingo.dev 发送人员信息。之后,你分配的每个人都会在 Lingo.dev 中收到一份待接受的邀请,并在首次通过 SSO 登录时成为成员。
当你在 Okta 中取消分配或停用某人时,Okta 也会在 Lingo.dev 中停用该人员,并移除其成员资格。请参阅移除人员。
使用 Okta 组设置角色 #
- 确保 Okta 组的名称与 Lingo.dev 中某个角色的名称相同,例如
Translator。 - 在应用的推送组选项卡中,选择推送组,然后选择按名称查找组。
- 找到该组,然后选择保存。
用于推送的组必须与用于分配应用的组不同。Okta 不支持同一个组同时用于这两种用途。Okta 只会推送已分配到应用的成员,因此,请直接或通过另一个组,将推送组中的每个人分配到应用。
Okta 会将组关联到同名角色。组成员会获得该角色,从组中移除的人员则会失去该角色。如果没有与组同名的角色,推送时会显示“找不到此名称的角色”错误。请先在 Lingo.dev 中创建该角色,然后重新推送组。
如果你停止推送某个组,且 Okta 询问是否在应用中删除该组,选择删除会移除该组成员的角色。角色本身仍会保留在 Lingo.dev 中。
故障排除 #
| 问题 | 解决方法 |
|---|---|
| 登录 Okta 后,Lingo.dev 显示“单点登录未完成”。 | 检查受众 URI(SP 实体 ID) 和单点登录 URL。它们必须与 Lingo.dev 中的实体 ID 和 ACS URL 完全一致,且末尾不能有斜杠。 |
| Lingo.dev 显示“你的身份提供商未发送电子邮件地址”。 | 将名称 ID 格式设为 EmailAddress,将应用用户名设为电子邮件,并添加 email 属性声明:在设置向导中使用 user.email,或在登录选项卡中使用 user.profile.email。 |
| Okta 提示你未被分配到该应用。 | 在分配选项卡中,将该人员或其所属的组分配到应用。如果你输入了已分配人员的电子邮件地址,但 Okta 显示的是你的管理员账户,说明浏览器保留了你的 Okta 会话。请退出 Okta,或使用无痕窗口。 |
| Lingo.dev 显示“单点登录耗时过长,请重试。” | Okta 登录耗时超过了约 5 分钟,例如首次设置多重身份验证时。请从 Lingo.dev 重新尝试,下一次尝试会成功。 |
| Lingo.dev 显示“你已登录,但我们无法将你添加到组织中。” | 再次使用 SSO 登录。如果仍然失败,请让所有者检查设置 → SSO 中是否显示连接开始时间。 |
| Lingo.dev 提示你的域名“尚未设置单点登录”。 | 在设置 → SSO 中添加该域名,或检查你输入的电子邮件地址。 |
测试连接器配置或预配失败,并显示 401 Unauthorized。 | SCIM 密钥已轮换或撤销。请将当前密钥粘贴到集成中,或在 Lingo.dev 中生成新密钥。 |
| 在 Okta 中分配的人员未出现在设置 → 团队的邀请选项卡中。 | 检查到应用中是否已启用创建用户。对于在保存此设置之前分配的人员,请打开 Okta 的预配任务列表,重试他们的预配任务。 |
如遇其他提示,请参阅故障排除。