单点登录
每个租户可以接入一个支持 OpenID Connect 的身份提供商(IdP),例如 Microsoft Entra ID、Okta 或 Keycloak。接入后,该租户的员工用公司账号登录,不再需要单独的 A2Flow 密码。首次登录会创建 A2Flow 账户,而 IdP 的组决定这个人属于哪些用户组,也就决定了他拥有哪些角色。
启用单点登录后,密码登录依然可用。超级管理员账户不属于任何租户,始终使用密码登录。
工作方式
开始之前
- 你需要在该租户中拥有管理员角色。
- 运维人员必须已在部署时设置部署的基础 URL,请参阅服务器设置。未设置时,管理员设置会显示警告来代替重定向 URI,单点登录也无法使用。
- A2Flow 必须能通过公网地址访问你的 IdP。位于私有网络中的 IdP 只有在运维人员允许其主机后才能使用,请参阅配置参考中的单点登录。
要在没有自己 IdP 的情况下试用单点登录,可以启动 Docker Compose 配置中附带的 Keycloak,请参阅使用 Keycloak 试用单点登录。
设置步骤
- 在 IdP 中为 A2Flow 注册一个新应用,类型为带客户端密钥的 Web 应用。记下它的颁发者 URL、客户端 ID 和客户端密钥。
- 在 A2Flow 中,打开管理侧边栏的管理员设置,找到单点登录部分。点击重定向 URI旁的复制,并把该地址登记为 IdP 中该应用的重定向 URI。如果用户通过租户专属地址打开 A2Flow,也要登记重定向 URI(租户地址)。
- 在 IdP 中,让应用的 ID 令牌带上每个人所属组的列表(组声明)。忘记这一步会导致角色被移除,请参阅注意事项。
- 对照下表填写该部分,并勾选启用单点登录。
- 保存。保存时会检查颁发者 URL 是否为允许的地址(
https,或运维人员已允许的主机);如果勾选了启用单点登录,还会检查颁发者 URL、客户端 ID 和客户端密钥是否已填写。不会联系 IdP,所以真正的测试是下一步。 - 对每个需要跟随 IdP 组的用户组,打开用户组,打开该组并填写 IdP 组,请参阅组与角色。
- 试一试:打开登录界面,输入租户名称并点击使用 SSO 登录。
| 字段 | 说明 |
|---|---|
| 启用单点登录 | 开关。开启它需要颁发者 URL、客户端 ID 和客户端密钥。 |
| 颁发者 URL | IdP 的 OpenID Connect 颁发者,例如 https://idp.example.com。 |
| 客户端 ID | 应用在 IdP 中的客户端 ID。 |
| 客户端密钥 | 只写:不会再次显示。保存后,该字段显示“已保存 — 留空则保留”。 |
| 组声明 | ID 令牌中列出一个人所属组的声明名称。除非你的 IdP 使用别的名称,否则为 groups。 |
| 信任此 IdP 的电子邮件地址 | 默认关闭。即使 IdP 没有把地址标记为已验证,也允许 A2Flow 按电子邮件地址关联已有账户。Microsoft Entra ID 需要开启它。 |
| 重定向 URI | 只读。需要登记到 IdP 的地址,所有租户使用同一个。 |
| 重定向 URI(租户地址) | 只读。从租户专属地址开始的登录会返回到这里(参见在租户地址登录)。如果用户通过该地址打开 A2Flow,也要登记它。部署地址是 IP 地址时不显示。 |
登录
在登录界面的租户中输入租户名称,点击使用 SSO 登录。租户为空时按钮不可用。你会被转到 IdP,在那里登录后回到 A2Flow,并处于已登录状态。使用用户名和密码登录的方式与以前相同。
退出 A2Flow 不会退出 IdP,所以再次点击使用 SSO 登录时,可能会直接登录进去。
在租户地址登录
每个租户还可以通过专属地址打开。租户地址是在平常的地址前加上租户名称,例如 acme.a2flow.example.com,需要运维人员为其准备好 DNS 和证书。此时登录界面没有租户输入框。
| 租户设置 | 会发生什么 |
|---|---|
| 已启用单点登录 | 不经过登录界面,直接转到 IdP。 |
| 未启用单点登录 | 界面只要求输入用户名和密码。 |
退出登录后,A2Flow 会显示一个确认已退出的页面,点击重新登录可回到登录界面。启用了单点登录时,这会转到 IdP,如果 IdP 上的登录仍然有效,会直接登录进去。
单点登录失败后,不会自动转到 IdP。界面会显示使用 SSO 登录,点击使用密码登录会显示用户名和密码输入框,供设有密码的账户使用。你也可以在平常的地址的租户中输入租户名称,用密码登录。
如果想不转到 IdP 而直接用密码登录(例如没有 IdP 身份的账户),请在登录界面的地址后加上 ?local 打开,例如 https://acme.a2flow.example.com/login?local。界面打开时就会直接显示用户名和密码输入框。
登录错误信息
登录失败时,你会回到登录界面,并看到下列信息之一。
| 信息 | 含义与处理 |
|---|---|
| 此租户无法使用单点登录。 | 租户名称有误、租户已被停用,或其单点登录尚未设置或未开启。A2Flow 特意不说明是哪一种,这样就无法借此信息得知有哪些租户。请检查名称,仍不行就询问租户管理员。 |
| 单点登录失败,请重试。 | 与 IdP 的交互没有完成,或 IdP 没有提供电子邮件地址(或提供的地址无法使用),或租户中有两个账户使用了你的电子邮件地址,或使用你电子邮件地址的账户已关联到另一个 IdP 身份,或 IdP 的电子邮件地址不被信任而 A2Flow 中已有使用该地址的账户。最后一种情况下,请让租户管理员开启信任此 IdP 的电子邮件地址,或修改两个账户之一的电子邮件地址。其他情况请重试;如果仍然失败,请让租户管理员检查设置以及在 IdP 中注册的应用。 |
| 你的账号已被停用。 | 你的 A2Flow 账户或整个租户已被停用,或账户已被删除。管理员可以通过已启用重新启用该账户。 |
| 你的身份提供商账号不允许登录 A2Flow。 | 你还没有 A2Flow 账户,并且不属于任何已与用户组对应的 IdP 组;或者因为你所属的组非常多,IdP 省略了你的组列表。请让 IdP 管理员把你加入某个已对应的组。 |
如何把人与账户对应起来
每次登录时,A2Flow 按以下顺序查找账户:
- 使用已关联到该 IdP 身份的账户。
- 关联电子邮件地址相同的已有账户,只关联一次。地址比较时不区分大小写,并且只有在 IdP 把它标记为已验证,或信任此 IdP 的电子邮件地址已开启时才会接受。必须恰好有一个尚未关联的账户匹配;如果有两个或更多,登录失败。
- 否则创建新账户,但只针对至少属于一个已与用户组对应的 IdP 组的人。其他人会被拒绝。 租户中已有账户使用某个电子邮件地址时,不会再为它创建新账户;IdP 的电子邮件地址无法使用时也不会创建,登录都会失败。
新账户的用户名取自 IdP 的 preferred username,没有的话取电子邮件地址 @ 之前的部分。字母、数字、.、_ 和 - 以外的字符会被去掉,剩下的太少时用户名为 user,名称已被占用时会加上 -2、-3 等。名和姓来自 IdP。账户没有直接角色,也没有密码:角色来自它所属的组,管理员之后可以设置一个密码作为备用。
已有账户的姓名和电子邮件地址绝不会被 IdP 的值覆盖。
组与角色
在每个用户组上,IdP 组填写 IdP 的组声明中为该组列出的值。Microsoft Entra ID 发送的是组的对象 ID,而不是名称,所以请填写该 ID。匹配是精确的,并区分大小写。
每次 SSO 登录时,对每个设有 IdP 组的用户组:
- 声明中包含该值时,这个人加入该组;
- 不包含时,这个人离开该组。
没有 IdP 组的用户组,以及直接授予账户的角色,绝不会被改动。在 IdP 中所做的组变更,会在这个人下一次 SSO 登录时生效,而不是立即生效。
设有 IdP 组的组,其成员由 IdP 管理,不能手动编辑。在该组的页面上,成员列表是只读的,并显示“由 IdP 管理”,也不能在用户的用户组中添加或移除这样的组。如果你在已有成员的组上填写 IdP 组,这些成员会保留到各自下一次 SSO 登录为止。
注意事项
| 情况 | 结果 |
|---|---|
| IdP 没有发送组声明,或组声明的名称不匹配 | 每个登录的人都会被移出所有已对应的组,并失去这些组授予的角色。启用单点登录之前,请先在 IdP 中确认该声明。 |
| Microsoft Entra ID | 发送的是组的对象 ID,而不是名称。对于所属组非常多的人,它会省略该列表。此时 A2Flow 会保留这个人当前的成员关系,但无法为其创建新账户。 |
| 你更改了颁发者 URL 或客户端 ID | 租户中的所有账户都会与其 IdP 身份解除关联,因为换一个应用,IdP 就会签发不同的身份。人们会在下次登录时按电子邮件地址重新关联,这要求地址可信(IdP 标记为已验证,或已开启信任此 IdP 的电子邮件地址)。否则登录会失败,因为原账户仍然使用该地址。 |
| 某人在 IdP 中被删除 | 他无法再通过 SSO 登录,但 A2Flow 不会停用其账户。如需同时阻止密码登录,请取消勾选该账户的已启用。 |
| 账户带有 SSO 标记 | 它曾通过单点登录登录过。该标记显示在用户列表和账户的详情页中。 |
| 用户通过租户专属地址打开 A2Flow | 在那里开始的单点登录会经由 重定向 URI(租户地址) 返回该地址。在把这个地址登记到 IdP 之前,IdP 会拒绝登录。 |