使用你的身份提供者让人员登录

作用

• 每个组织一个连接。 组织管理员在控制台的组织设置中，在单点登录下进行设置。
• 由你的域名决定谁使用它。 登录页面先询问电子邮件。位于你的某个已验证域名的地址会继续前往你的提供者。
• 由你的提供者决定谁可以进入。 没有任何账户持有其地址的人员会在首次登录时被创建，除非你在连接上关闭 Create accounts at first sign-in。新人员在邀请或已预配的群组授予项目之前没有任何项目。
• 你的人员就是成员。 通过你的提供者登录的人员是你的组织的成员。只有你的提供者可以移除他们。
• Require single sign-on 会在你的域名下拒绝密码和通行密钥。

开始之前

• 你是该组织的管理员。
• 组织拥有已验证的域名。在组织设置的已验证的域名下，在添加域名中输入该域名，选择获取 DNS 记录，发布所显示的 TXT 记录，然后选择验证 example.com（用你自己的域名替换）。保留该记录：screenRIG 每天检查它，记录持续缺失 7 天的域名会被移除，其地址的单点登录随之停止。
• 更改连接需要你的通行密钥或密码。单点登录会话也可作为 10 分钟内的近期登录，但仅限于你的提供者说明该人员的认证时间时（OpenID Connect 中的 auth_time，SAML 中的 AuthnInstant）。否则 screenRIG 会在更改之前要求该人员在提供者处重新登录。

你的提供者要求这些值：

每个连接都有自己的重定向 URI，因为连接 ID 是地址的一部分。保存连接后，组织设置中的单点登录设置会在身份提供商所需的值下显示每个重定向 URI 的确切值，并已填入你的连接 ID。

Microsoft Entra ID

Entra 预设通过 OpenID Connect 让一个租户的人员登录。

1. 在 Microsoft Entra admin center 中，打开 App registrations 并选择 New registration。为其命名并选择 Accounts in this organizational directory only。将重定向 URI 留空：第 6 步会添加它。
2. 打开 Certificates & secrets，创建客户端密钥，并立即复制其 Value，而不是其 ID。
3. 打开 Token configuration，选择 Add optional claim，选择类型 ID，并添加 email，同时在其旁边添加 auth_time。没有 auth_time 时，Entra 不会说明该人员的认证时间，敏感操作会让该人员返回 Entra 重新登录（参见人员看到什么）。
4. 在 Overview 上，复制 Application (client) ID 和 Directory (tenant) ID。
5. 在组织设置的单点登录下，选择设置单点登录，然后选择 Microsoft Entra ID。输入名称（人员会在登录页面上看到）、租户 ID、客户端 ID 和客户端密钥，然后选择保存连接。
6. 在身份提供商所需的值下，复制重定向 URI，即带有你的连接 ID 的 https://screenrig.ai/api/sso/oidc/CONNECTION_ID/callback。在 Entra 中，打开 Authentication，添加平台 Web（不是 Single-page application：授权码交换在我们的服务器上运行），并输入该值。
7. 运行测试登录。

screenRIG 通过人员的 Entra 对象 ID 识别人员，绝不通过电子邮件或用户主体名称（Entra 管理员可以编辑它们）：重命名用户后其账户保持不变。来自任何其他租户的令牌会被拒绝。screenRIG 从 email 声明读取地址；对于 Entra 租户，当 email 缺失时回退到 preferred_username，第 3 步中的可选声明会使其成为该人员的邮件地址。Entra 不发送 email_verified，因此 screenRIG 接受该地址，是因为它位于你已验证的域名下。除非企业应用的 Assignment required 为 Yes，否则 Entra 允许租户中的每位用户登录。

Okta 和其他 OpenID Connect 提供者

这适用于 Okta、Auth0、Keycloak 以及发现文档位于 /.well-known/openid-configuration 的任何提供者。

1. 在提供者中，创建一个使用授权码流程的 Web 应用。在 Okta 中，选择 Applications、Create App Integration、OIDC、Web Application。在 screenRIG 为你提供重定向 URI 之前，提供者可能会要求填写重定向 URI：现在先输入任意 https 地址，并在第 4 步中替换它。分配可以登录的人员或群组。
2. 复制客户端 ID、客户端密钥和颁发者，即发现文档中给出的 https 地址。对于 Okta，这是组织 URL，例如 https://example.okta.com，或自定义授权服务器的地址。
3. 在组织设置的单点登录下，选择设置单点登录，然后选择 OpenID Connect。输入名称、颁发者、客户端 ID 和客户端密钥，然后选择保存连接。
4. 在身份提供商所需的值下，复制重定向 URI，即带有你的连接 ID 的 https://screenrig.ai/api/sso/oidc/CONNECTION_ID/callback，并将其作为应用的重定向 URI 输入到提供者处。
5. 运行测试登录。

提供者必须支持带 S256 的 PKCE、form_post 响应模式，以及使用非对称算法签名的 ID 令牌，并且必须允许 openid、email 和 profile 权限范围。其 ID 令牌必须携带 email 声明：只有 Entra 租户会回退到其他声明。email_verified 声明如果发送，必须为 true。提供者能发送 auth_time 声明时请发送：screenRIG 据此得知该人员的认证时间。

SAML 2.0

这适用于 Entra 企业应用、Okta、Google Workspace 以及任何其他 SAML 2.0 提供者。先在提供者中开始，再在 screenRIG 中输入其元数据，screenRIG 会显示提供者所需的值。

screenRIG 要求每个响应满足以下条件：

• 响应恰好携带一个断言，且该断言未加密。
• 断言本身使用 RSA 或 ECDSA 以及 SHA-256 或更强的算法签名。SHA-1 会被拒绝，包裹着未签名断言的已签名响应同样会被拒绝。
• 断言的颁发者是你的提供者的实体 ID，其受众限制指明的是 screenRIG 的实体 ID。
• 登录从 screenRIG 开始。提供者应用门户中的磁贴（IdP 发起的登录）会被拒绝；人员应从 screenRIG 登录页面开始。
• 时钟相差不超过 3 分钟，且每个断言只使用一次。
• NameID 存在，且格式为 persistent、电子邮件地址或 unspecified。transient NameID 或任何其他格式都会被拒绝。NameID 是该人员在 screenRIG 的标识符；对于 Entra，它是对象 ID 属性。
• 电子邮件以属性 email、mail、urn:oid:0.9.2342.19200300.100.1.3、http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 或 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn 的形式到达，或作为电子邮件格式的 NameID。

Entra ID

1. 打开 Enterprise applications、New application、Create your own application，然后选择 Integrate any other application you don't find in the gallery。
2. 打开 Single sign-on 并选择 SAML。在 SAML Certificates 下，下载 Federation Metadata XML，并将 Signing Option 设为 Sign SAML assertion 或 Sign SAML response and assertion。
3. 在组织设置的单点登录下，选择设置单点登录，然后选择 SAML 2.0。输入名称，将元数据 XML 粘贴到元数据文档中，然后选择保存连接。随后身份提供商所需的值会显示实体 ID 和断言使用者服务（ACS）地址。
4. 在 Entra 中，编辑 Basic SAML Configuration：Identifier 是实体 ID，Reply URL 是 ACS 地址。
5. 保留默认声明：它们携带人员的对象 ID 和邮件地址。检查你分配的人员是否都有邮件地址。
6. 在 Users and groups 下分配人员，然后运行测试登录。

已通过 OpenID Connect 登录的人员，在租户改用 SAML 时保留其账户，反过来也一样：两种协议都通过租户和 Entra 对象 ID 识别人员。SAML 响应必须携带对象标识符声明，Entra 的默认声明包含它。没有该声明时，screenRIG 会回退到 NameID，通过 OpenID Connect 关联的账户将不再匹配（subject_mismatch）。

Okta

1. 选择 Applications、Create App Integration、SAML 2.0。Okta 在显示元数据之前会要求填写 Single sign-on URL 和 Audience URI：现在为两者填入任意 https 地址。
2. 将 Name ID format 设为 Persistent，将 Application username 设为 Email，并添加属性语句 email，其值为 user.email。在 Show Advanced Settings 下，保持 Assertion Signature 为 Signed，Signature Algorithm 为 RSA-SHA256，Digest Algorithm 为 SHA256，并保持 Assertion Encryption 关闭。
3. 选择 Finish，打开 Sign On 选项卡，并复制 Identity Provider metadata。
4. 在组织设置的单点登录下，选择设置单点登录，然后选择 SAML 2.0。输入名称，将元数据粘贴到元数据文档中，然后选择保存连接。从身份提供商所需的值中复制实体 ID 和断言使用者服务（ACS）地址。
5. 在 Okta 中，编辑 SAML Settings：Single sign-on URL 是 ACS 地址，Audience URI 是实体 ID。
6. 分配人员，然后运行测试登录。

Google Workspace

1. 在 Admin console 中，依次打开 Apps、Web and mobile apps、Add app，然后选择 Add custom SAML app。为其命名。
2. 下载 Google Identity Provider 元数据并继续。
3. 在组织设置的单点登录下，选择设置单点登录，然后选择 SAML 2.0。输入名称，将元数据粘贴到元数据文档中，然后选择保存连接。从身份提供商所需的值中复制实体 ID 和断言使用者服务（ACS）地址。
4. 在 Google 中，输入 ACS 地址和实体 ID。将 Name ID format 设为 PERSISTENT，将 Name ID 设为 Basic Information, Primary email。保持 Signed response 不勾选：这样 Google 会对断言签名，而 screenRIG 要求断言已签名。
5. 将 Google Directory 属性 Primary email 映射到应用属性 email。
6. 打开应用的 User access，为需要登录的人员开启它，然后运行测试登录。

轮换证书

一个连接最多信任四个签名证书，因此轮换没有空档。将新证书粘贴在旧证书旁边（或粘贴列出两者的提供者新元数据）并保存，将提供者切换到新证书，然后移除旧证书。

测试登录

在组织设置中按测试登录。你在提供者处登录并返回控制台，控制台会显示提供者发送的地址，以及它是否发送了稳定的标识符。测试不会让任何人登录。测试失败会显示与其中一个错误代码对应的消息。该地址必须位于已验证域名。

通过连接当前的提供者、租户、实体 ID 和协议完成一次成功的测试或真实登录，才允许你强制使用单点登录。

要求单点登录

测试成功后，在组织设置中选择要求使用单点登录，选定紧急访问管理员并确认。对你的已验证域名下的所有人：

• 登录页面只提供你的提供者。密码或通行密钥会被拒绝，并返回 sso_required。密码和通行密钥保留在账户上，不被使用，关闭该要求后会再次生效。
• 已验证地址位于你的域名下的现有账户，在首次单点登录时会登录到同一个账户，无论它持有哪些登录方式，并保留其项目。此后你的组织管理该账户：其电子邮件在每次登录时跟随你的提供者，人员本人无法更改。
• 紧急访问管理员。 最多选择两名持有通行密钥的组织管理员。他们保留通行密钥登录，供提供者宕机时使用，每次此类登录都会被记录。之后可通过更改紧急访问管理员更改所选人员。
• 该要求开启期间，连接的颁发者、租户 ID、实体 ID 和协议不能更改，连接也不能移除。证书和客户端密钥可以轮换。

关闭需要 72 小时。 选择 Turn off requirement：在此之前该要求保持有效，每位管理员都会收到电子邮件，任何管理员都可以选择 Cancel removal。

人员看到什么

• 登录页面先询问电子邮件，然后继续前往你的提供者。结果仅取决于域名，因此不会显示某人是否有账户。
• 会话自在 screenRIG 登录起持续 24 小时，使用不会延长它。12 小时后，控制台会在下一个页面静默续期；会话结束后，也以同样的方式重新登录。静默发起不发送登录提示，因此提供者会返回其持有会话的那个账户；如果那是另一个人，续期会失败并返回 subject_mismatch。提供者会话仍有效的人员无需输入任何内容；否则需要重新登录。
• 需要通行密钥或密码的操作（例如更改连接），也接受在 10 分钟内算作近期登录的单点登录会话。只有当你的提供者说明该人员的认证时间时才会计入：以提供者自身的时间为准（OpenID Connect 中的 auth_time，SAML 中的 AuthnInstant），而不是在 screenRIG 登录的时间。当提供者没有给出时间，或给出的时间早于 10 分钟前时，screenRIG 会要求该人员在提供者处重新登录：控制台会让该人员通过提供者重新认证，并返回其原来所在的位置。
• 你的提供者禁用的人员会在 24 小时内失去访问权限；使用用户预配时则立即失去。人员批准的智能体和 OAuth 授权会继续有效，直到该人员被停用（通过用户预配或由 screenRIG 员工停用）：要求单点登录以及在你的提供者处禁用该人员都不会终止它们。

关联现有账户

位于你的已验证域名、已有带密码或通行密钥的 screenRIG 账户的人员，首次单点登录不会登录到该账户（account_exists），除非你强制使用单点登录。他们照常登录，在 https://screenrig.ai/dashboard/me 打开个人资料与登录，选择关联单点登录，并在提供者处登录。此后单点登录会打开同一个账户，该账户保留自己的登录方式。个人资料与登录会向你的域名下每位尚未关联的已登录人员提供该关联。

故障排查

登录失败会返回登录页面，错误代码位于地址中（#sso_error=CODE）。测试失败会在连接上显示与其代码对应的消息。

相关

• 用户预配：从你的提供者创建、更新和移除人员，并让群组获得项目的访问权限。
• 身份验证：智能体如何登录，以及访问如何获得批准。
• API 参考：连接、策略和登录路由。