用 SSO 让团队登录

你将构建什么

学完本教程后，你将拥有：

Control Center 服务器与身份提供方之间的一条 SAML 连接（我们以 Okta 为例），
一名在首次登录时被自动预配的用户，以及
一条由你审慎选择的工作区成员资格策略。

你需要一台由你管理的服务器（即服务器所有者——该安装的运营者），以及一个你可以配置的 IdP 应用。请预留 20 分钟。

第 1 步：打开单点登录设置

此界面上的所有设置都作用于整个服务器：一个 IdP 会认证每个工作区里的人，因此只有服务器所有者可以编辑。

第 2 步：粘贴 IdP 元数据

在 Okta 中，打开应用的 Sign On 标签页，复制元数据 XML（或将其下载下来并粘贴文件内容）。回到 Control Center，把它粘贴到 IdP 元数据 XML 中，然后按测试连接。

提示条会报告 IdP 的登录端点——这证明元数据已解析、证书已读取，并且服务器能据此构造登录请求（该测试会演练除浏览器往返之外的所有环节）。如果失败，说明该 XML 不是完整的 EntityDescriptor（Okta 的 SAML 标签页称之为 “Metadata URL”；请打开该 URL 并复制它提供的内容）。OpenID Connect 上的同一按钮则改为检查你签发者的发现文档。若要同时发现即将过期的证书，并了解 IdP 是否能识别 Control Center，请使用第 6 步中的检查器。

第 3 步：在 IdP 处注册 Control Center

按复制 SP 元数据，把它交给负责配置 Okta 一侧的人（或读出他们索要的两个值）：

ACS URL：https://<your-server>/saml/acs
实体 ID：https://<your-server>/saml

这些 URL 派生自用户浏览器所访问的源。如果服务器运行在隧道或反向代理之后，请确保该源保持稳定（设置 → 服务器 → 连接与状态 → 共享此服务器会显示公共 URL）——或者在 SP 实体 ID 字段中显式固定实体 ID。

第 4 步：选择一次登录授予什么

两条策略决定首次登录会做什么：

首次登录时将用户加入每个工作区——在 SSO 等同于信任的单团队部署中保持开启。当多个团队或客户共享该服务器时，请将其关闭：这样每位新来者都需要明确的工作区邀请，这是更安全的默认设置。
首次登录时预配未知用户——默认开启；关闭后，账户尚不存在的人会被拒绝。

可选地，映射一个承载组名称的属性（Okta 的通常是 groups），并用映射表把组转换为角色——例如 {"platform-leads": "admin"}。SSO 永远无法授予所有者角色。

第 5 步：启用并走一次登录

打开使用 SAML 登录，按保存连接，然后在隐私浏览窗口中打开 https://<your-server>/saml/login。在 Okta 登录后，你会回到 Web 客户端——已登录，账户已创建，其成员资格按你所选的策略授予。

一旦你输入服务器地址，Web 连接界面上就会出现同一个入口（使用 SAML 登录）——表单会根据服务器提供的方式自适应（OpenID Connect 会显示使用 OpenID Connect 登录）。该按钮会在新标签页中打开登录；往返完成后，等待中的标签页会自动接管该会话。桌面端的服务器设置界面也是如此：输入服务器 URL 后会出现一个使用 SAML 登录按钮，它打开你的浏览器，往返完成后应用即完成登录。

第 6 步：从本页检查

在全面推行 SSO 之前，或某次登录失败时，可以在这里检查各个环节。检查器完全在你的浏览器中运行：它读取你在本标签页中粘贴的元数据，并应用与服务器相同的规则。如果提供了服务器地址，它还会询问该服务器是否已启用 SAML 登录。

它能发现应用中的测试连接看不到的问题：临近过期的签名证书、坚持要求签名请求的 IdP，以及借助测试登录来判断 IdP 是否根本不认识 Control Center。

Runs in your browserYour metadata is read in this tab and never uploaded. Add a server address and your browser also asks that server which sign-in methods it offers.

后续步骤

也让你的 IdP 掌控生命周期：用 SCIM 预配和取消预配用户。
你的 IdP 说的是 OpenID Connect 而不是 SAML？连接 OpenID Connect 提供方。
想知道浏览器往返究竟验证了什么？单点登录如何运作。