单点登录 (SSO) 问题排查

当服务提供商 (SP) 为 Google 时，如果您将单点登录 (SSO) 与 Google Workspace 集成或搭配使用时看到一些常见错误消息，可以参考本文提供的解决步骤。

配置与启用

“未将此网域配置为使用单点登录。”

此错误通常表示您使用的 Google Workspace 版本不支持单点登录 (SSO)，例如 G Suite 免费版（旧版）。所有当前的 Workspace 版本都支持通过第三方身份提供方 (IdP) 实现单点登录 (SSO)。

如果您使用的是支持 SSO 的 Google Workspace 版本，请尝试以下其他解决方案：

  • 验证 IdP 的 SSO 配置是否使用了正确的 Google Workspace 域名。
  • 如果您是在设置单点登录配置文件后遇到此错误，可能是因为您的 IdP 已配置为将 SAML 断言发送到旧版单点登录配置文件端点。如果您的 IdP 硬编码了旧版 SSO 端点，请执行以下操作：
    1. 设置旧版单点登录。
    2. 请让您的 IdP 供应商更新其 Google 集成。

“由于域名配置错误，因此无法访问此账号。请稍后重试。”

此错误表明，您没有在 Google 管理控制台中正确设置单点登录。请按以下步骤修正错误：

  1. 在管理控制台中，依次点击安全性 然后设置采用第三方身份提供商的单点登录 (SSO)，然后勾选设置采用第三方身份提供商的单点登录复选框。
  2. 在相应字段中输入您组织的登录页、退出页和更改密码页的网址。
  3. 选择并上传有效的验证证书文件。
  4. 点击保存，稍候几分钟待更改生效，然后再次测试集成。

使用禁止的前缀配置的 Google 租户

在 iOS 应用中，当 SSO 登录页面网址开头为“google.”（或一些变体）时，Google iOS 应用会被重定向到 Safari。这会导致 SSO 过程失败。以下是所有禁用的前缀列表：

  • googl.
  • google.
  • www.googl.
  • www.google.

您需要更改任何带有上述前缀的 SSO 登录页面网址。

解析 SAML 响应

“所需的响应参数 SAMLResponse 缺失”

此错误消息表明您的身份提供商没有为 Google 提供某种有效的 SAML 响应。这很可能是身份提供者的配置问题造成的。

  • 查看您的身份提供商日志，确保其没有受到任何限制，可以正确返回 SAML 响应。
  • 确保您的身份提供商没有向 Google Workspace 发送加密的 SAML 响应。Google Workspace 只接受未加密的 SAML 响应。请格外注意，Microsoft 的 Active Directory Federation Services 2.0 在默认配置下通常会发送加密的 SAML 响应。

“所需的响应参数 RelayState 缺失”

SAML 2.0 规范要求身份提供商通过资源提供商（例如 Google Workspace）检索和发回 RelayState 网址参数。Google Workspace 会在 SAML 请求中将此值提供给身份提供商，而每次登录时提供的确切内容可能都有所不同。为了成功完成身份验证，SAML 响应必须返回确切的 RelayState。根据 SAML 标准规范，您的身份提供商在登录流程中不应修改 RelayState。

  • 在尝试登录时获取 HTTP 标头以进一步诊断此问题。从 HTTP 标头中提取 SAML 请求和响应的 RelayState，并确保请求和响应的 RelayState 值相匹配。
  • 大多数商业化或开源单点登录身份提供商在默认情况下均可顺利传输 RelayState。为了最大限度地提高安全性和可靠性，我们建议您使用现有解决方案之一，我们无法支持您自定义的单点登录软件。

SAML 响应的内容

“您的登录请求中所包含的 [destination|audience|recipient] 信息无效，因此无法访问该服务。请登录并重试。”

该错误表明 SAML 断言中的 destination、audience 或 recipient 元素包含无效信息或没有任何内容。SAML 断言中必须包含所有元素。查看单点登录断言要求中的以下表格，了解各个元素的说明和示例：

“您的登录请求中未包含收件人信息，因此无法访问该服务。请登录并重试。”

该错误通常表明来自您的身份提供商的 SAML 响应缺少可读取的 Recipient 值（或 Recipient 值有误）。Recipient 值是 SAML 响应的重要组成部分。

  1. 在尝试登录时获取 HTTP 标头以进一步诊断此问题。
  2. 从 HTTP 标头中提取 SAML 请求和响应。
  3. 确保 SAML 响应中存在 Recipient 值，且与 SAML 请求中的该值相匹配。

注意：此错误消息可能也会显示为“此服务无法访问，因为您的登录请求包含无效的 recipient 信息。请登录并重试。”

“由于无法验证登录凭据，因此无法访问此账号。”

该错误表明您用于签署身份验证流程的证书存在问题。这通常表明用于签署 SAML 响应的私钥与 Google Workspace 记录的公钥证书不匹配。

如果您的 SAML 响应未包含有效的 Google 账号用户名，也会出现此错误。Google Workspace 会解析 SAML 响应以查找名为 NameID 的 XML 元素，该元素应会包含 Google Workspace 用户名或完整的 Google Workspace 电子邮件地址。

  • 请确保您已将有效的证书上传到 Google Workspace，如有必要，请替换相应的证书。在 Google 管理控制台中，依次前往安全性 然后设置采用第三方身份提供商的单点登录 (SSO)，然后点击替换证书。
  • 如果您在 NameID 元素中使用完整的电子邮件地址（如果您在多网域 Google 应用环境中使用 SSO，则必须这样做），请确保 NameID 元素的 Format 属性指定要使用完整的电子邮件地址，如以下示例所示：Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress".
  • 确保使用有效的用户名或电子邮件地址填充 NameID 元素。为了确认这一点，请提取发送到 Google Workspace 的 SAML 响应，然后检查 NameID 元素的值。
  • NameID 区分大小写：请确保 SAML 响应所填充的 NameID 与 Google Workspace 用户名或电子邮件地址的大小写保持一致。
  • 如果您的身份提供商将 SAML 断言加密，请停用加密功能。
  • 确保 SAML 响应不包含任何非标准 ASCII 字符。该问题最常出现在 AttributeStatement 的 DisplayName、GivenName 和 Surname 属性中，例如：
    • <Attribute Name="http://schemas.microsoft.com/identity/claims/displayname">
      <AttributeValue>Blüte, Eva</AttributeValue> </Attribute>
    • <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
      <AttributeValue>Blüte</AttributeValue> </Attribute>

如需详细了解如何设置 NameID 元素的格式，请参阅 SSO 断言要求。

“由于您的登录凭证已过期，因此无法访问此服务。请登录并重试。”

出于安全考虑，单点登录流程必须在特定时间范围内完成，否则身份验证将失败。如果您的身份提供者的时钟不正确，绝大多数或所有登录尝试可能都会超出允许的时间范围，身份验证将失败，导致系统发出以上错误消息。

  • 请检查身份提供商服务器的时钟。此错误通常是因为身份提供者的时钟不正确，它为 SAML 响应添加了错误的时间戳。
  • 请将身份提供商服务器的时钟与可靠的互联网时间服务器重新同步。如果在生产环境中突然出现此问题，通常是因为上次同步失败，导致服务器时间出现错误。重复进行时间同步操作（尽可能选择与较可靠的时间服务器同步）就可以迅速解决该问题。
  • 如果您重新发送之前登录尝试的 SAML，也可能会出现此问题。通过检查您的 SAML 请求和响应（在尝试登录过程中捕获的 HTTP 标头日志中获得），您可以对此问题进行进一步调试。

“由于登录凭据尚未生效，因此无法访问此服务。请登录并重试。”

出于安全考虑，单点登录流程必须在特定时间范围内完成，否则身份验证将失败。如果您的身份提供者的时钟不正确，绝大多数或所有登录尝试可能都会超出允许的时间范围，身份验证将失败，导致系统发出以上错误消息。

  • 请检查身份提供商服务器的时钟。此错误通常是因为身份提供者的时钟不正确，它为 SAML 响应添加了错误的时间戳。
  • 请将身份提供商服务器的时钟与可靠的互联网时间服务器重新同步。如果在生产环境中突然出现此问题，通常是因为上次同步失败，导致服务器时间出现错误。重复进行时间同步操作（尽可能选择与较可靠的时间服务器同步）就可以迅速解决该问题。