使用 Microsoft Entra ID 设置 SSO
在 Microsoft Entra ID 中为 Lingo.dev 创建企业应用程序、分配用户、将其连接到您的组织,并通过 SCIM 预配成员。
本指南介绍如何通过 SAML 2.0 将 Microsoft Entra ID 连接到 Lingo.dev。您在 Entra 中至少需要具备云应用程序管理员角色,并且必须是使用 Enterprise 套餐的 Lingo.dev 组织的所有者。如需了解 SSO 在 Lingo.dev 中的工作原理,请参阅单点登录。
请在 Lingo.dev 中保持设置 → SSO 页面处于打开状态。您需要将其中的两个值复制到 Entra 中。
创建企业应用程序 #
- 登录 Microsoft Entra 管理中心。
- 前往 Entra ID → 企业应用程序 → 所有应用程序,然后选择新建应用程序。
- 选择创建你自己的应用程序。
- 输入
Lingo.dev作为名称,选择集成未在库中找到的任何其他应用程序(非库),然后选择创建。
配置 SAML #
- 在新建的应用程序中,打开单点登录并选择 SAML。
- 在基本 SAML 配置中,选择编辑。
- 在标识符(实体 ID) 下,选择添加标识符,然后粘贴
https://auth.lingo.dev/auth/v1/sso/saml/metadata(即 Lingo.dev 中的实体 ID)。 - 在回复 URL(断言使用者服务 URL) 下,选择添加回复 URL,然后粘贴
https://auth.lingo.dev/auth/v1/sso/saml/acs(即 Lingo.dev 中的 ACS URL)。 - 登录 URL、中继状态和注销 URL 暂时留空,然后选择保存。完成连接后,再按照从 Microsoft 我的应用登录中的说明设置登录 URL。
保留默认的属性和声明即可。在 Entra 管理中心创建的应用会通过 emailaddress 声明发送用户的电子邮件地址(取自 user.mail),并发送电子邮件格式的名称 ID。请确保每位登录用户在 Entra 中都已设置电子邮件地址。
如果应用在创建时未包含默认声明(例如通过 Microsoft Graph API 创建),则不会发送电子邮件地址,登录时会失败并提示“您的身份提供商未发送电子邮件地址。”此时,请在属性和声明中添加电子邮件声明,并将源属性设为 user.mail。
复制元数据 URL #
在 SAML 证书中,复制应用联合元数据 URL。
分配用户和组 #
- 在应用程序中,打开用户和组,然后选择添加用户/组。
- 在用户和组下,选择未选择任何项,选取所需的用户或组,然后选择选择。
- 选择分配。
- 打开属性,将是否需要分配?设为是,然后选择保存。
将是否需要分配?设为是后,只有已分配的用户才能通过 Entra 登录 Lingo.dev。如果设为否,租户中的所有用户(包括来宾账户)都能访问该应用。不过,Lingo.dev 仍只允许已连接域名下的账户加入,其他账户会被自动退出登录。通过 Microsoft Graph API 创建的应用默认设为否。分配组需要 Microsoft Entra ID P1 或 P2;如果使用免费版,请逐个分配用户。
在 Lingo.dev 中完成连接 #
- 打开设置 → SSO。
- 将应用联合元数据 URL 粘贴到身份提供商元数据 URL 中。
- 在电子邮件域名中输入公司的电子邮件域名,多个域名以逗号分隔。
- 选择连接。
如果域名被拒绝,请参阅域名规则。
测试登录 #
- 打开浏览器隐私窗口,前往 Lingo.dev 登录页面。
- 选择使用 SSO 继续,输入已分配用户的电子邮件地址,然后选择登录。
- 使用 Microsoft 账户登录。
登录后,您将以组织成员身份返回 Lingo.dev。请核对组织页面上显示的电子邮件地址:它对应的是 Microsoft 实际登录的账户,不一定是您输入的地址。如果浏览器已登录 Microsoft(例如以设置该应用的管理员身份登录),Microsoft 会直接沿用该账户,而不会要求输入密码。因此,测试时务必使用隐私窗口。
请从 Lingo.dev 发起测试,而不要使用 Entra 中的测试按钮。在设置登录 URL 之前,点击 Microsoft 我的应用中的 Lingo.dev 磁贴并不会让您登录:您只会进入 Lingo.dev 主页,且仍处于未登录状态。
如果租户启用了安全默认值,Microsoft 会要求每位用户在首次登录时注册身份验证器应用。这一过程可能超出 Lingo.dev 的等待时间(约 5 分钟),导致首次尝试失败,并提示“单点登录耗时过长,未能完成。请重试。”重新尝试即可成功。
测试成功后,您就可以强制使用 SSO 了。在此之前,请先按照启用中的说明,将您自己的 SSO 账户设为所有者。
从 Microsoft 我的应用登录 #
设置登录 URL,让用户可以直接通过我的应用中的 Lingo.dev 磁贴登录。
- 在 Lingo.dev 中,打开设置 → SSO 并复制控制台登录链接,其格式类似于
https://lingo.dev/auth/sso?domain=example.com。 - 在 Entra 中,打开 Lingo.dev 应用程序并选择单点登录。
- 在基本 SAML 配置中,选择编辑。
- 将链接粘贴到登录 URL 中,然后选择保存。
现在,点击我的应用中的 Lingo.dev 磁贴即可打开该链接。Lingo.dev 会将用户跳转到 Microsoft,验证后再返回 Lingo.dev 并完成登录,全程无需输入电子邮件地址。
使用 SCIM 预配成员 #
Entra 可以通过 SCIM 管理 Lingo.dev 成员,并借助组来设置其角色。请先按照本指南完成 SSO 设置。如需了解 SCIM 在 Lingo.dev 中的工作原理,请参阅使用 SCIM 预配成员。
- 在 Lingo.dev 中,生成 SCIM 密钥。
- 在 Entra 中,打开 Lingo.dev 企业应用程序并选择预配。
- 将预配模式设为自动。
- 在管理员凭据下,将 Lingo.dev 中的 SCIM 基础 URL(即
https://api.lingo.dev/v2/scim)粘贴到租户 URL 中,并将 SCIM 密钥粘贴到机密令牌中。 - 选择测试连接,然后选择保存。
- 保留默认的属性映射。Lingo.dev 会从
userPrincipalName获取userName,并从mail获取工作电子邮件地址。 - 在设置下,将范围设为仅同步分配的用户和组。
- 选择开始预配。
邀请会发送到用户的 mail 地址,因此您分配的每位用户都必须拥有一个属于已连接域名的此类地址。userPrincipalName 与 mail 不一致也没有关系。
您分配的每位用户都会在 Lingo.dev 中收到一份待接受的邀请,并在首次通过 SSO 登录时正式成为成员。
Entra 会按周期执行预配,每次间隔约 40 分钟,因此更改和移除操作会在下一个周期同步到 Lingo.dev。如需立即同步某位用户,请使用按需预配。
取消分配用户时,Entra 发送的是停用请求而非删除请求,Lingo.dev 随后会移除该用户的成员资格。请参阅移除人员。
使用 Entra 组设置角色 #
- 确保 Entra 组的名称与某个 Lingo.dev 角色的名称相同,例如
Translator。 - 在用户和组中,将该组分配给应用程序。
Entra 会将组与同名角色进行匹配,并预配组内成员,这些成员将获得该角色。从组中移除的人员会失去该角色。如果某位用户仅通过该组获得应用分配,那么将其从组中移除后,该用户也会被移出 Lingo.dev。
故障排查 #
| 问题 | 解决方法 |
|---|---|
Microsoft 显示 AADSTS700016:“在目录中找不到标识符为‘…’的应用程序”。 | 标识符(实体 ID) 与 https://auth.lingo.dev/auth/v1/sso/saml/metadata 不完全一致。请在基本 SAML 配置中更正。 |
Microsoft 显示 AADSTS50011:“回复 URL 与为应用程序配置的回复 URL 不匹配”。 | 将回复 URL(断言使用者服务 URL) 设为 https://auth.lingo.dev/auth/v1/sso/saml/acs,并确保完全一致。 |
Microsoft 显示 AADSTS50105:该用户未分配到此应用程序。 | 在用户和组中分配该用户或其所属的组。 |
| 未分配的用户成功登录,或者 Lingo.dev 显示的电子邮件地址并非您输入的地址。 | 是否需要分配?被设为了否,或者浏览器已用另一个账户登录 Microsoft。请在属性中将是否需要分配?设为是,并在隐私窗口中进行测试。 |
| Lingo.dev 提示您的电子邮件地址不属于组织用于单点登录的域名。 | Microsoft 登录的账户不属于已连接的域名,通常是来宾账户或创建租户的管理员账户。请改用工作账户登录,或在设置 → SSO 中添加该账户的域名。 |
| Lingo.dev 显示“您的身份提供商未发送电子邮件地址”。 | 应用未发送电子邮件声明,或者该用户在 Entra 中没有电子邮件地址。请在属性和声明中添加电子邮件声明(user.mail),并为用户设置电子邮件地址。 |
| Lingo.dev 显示“单点登录耗时过长,未能完成。请重试。” | Microsoft 登录耗时超过约 5 分钟,通常是因为用户正在注册身份验证器应用。请从 Lingo.dev 重新尝试,下次即可成功。 |
| Lingo.dev 显示“您已登录,但我们无法将您添加到组织。” | 请再次使用 SSO 登录。如果问题依旧,请联系所有者确认设置 → SSO 中是否显示连接时间。 |
| Lingo.dev 显示“单点登录未完成”。 | 将标识符(实体 ID) 和回复 URL 与 Lingo.dev 中的值逐一核对,然后重试。 |
测试连接或预配失败,并显示 401 Unauthorized。 | SCIM 密钥已被轮换或撤销。请将当前密钥粘贴到机密令牌中,或在 Lingo.dev 中生成新密钥。 |
| 已分配的用户未出现在设置 → 团队的邀请选项卡中。 | 请等待下一个预配周期,或使用按需预配。同时检查该用户的 mail 是否属于已连接的域名。 |
如遇其他提示信息,请参阅故障排查。