Keycloak 单点登录

本指南介绍如何利用 SAML 联合服务在 Keycloak 和您的 Cloud Identity 或 Google Workspace 账号之间设置单点登录 (SSO)。本文假定您已安装并正在使用 Keycloak。

创建 SAML 配置文件

如需使用 Keycloak 配置单点登录，您首先需要在 Cloud Identity 或 Google Workspace 账号中创建 SAML 配置文件。SAML 配置文件包含与 Keycloak 服务器相关的设置，包括其网址和签名证书。

您稍后可将 SAML 配置文件分配给特定群组或组织部门。

如需在 Cloud Identity 或 Google Workspace 账号中创建新的 SAML 配置文件，请执行以下操作：

  1. 在管理控制台中，依次点击安全性 > 身份验证 > 第三方身份提供商的单点登录服务。

    转到“使用第三方身份提供商进行单点登录”

  2. 依次点击第三方单点登录配置文件 > 添加 SAML 配置文件。

  3. 在 SAML SSO 配置文件页面上，输入以下设置：

    • 名称：Keycloak

    • IDP 实体 ID：

      KeyCloak 17 或更高版本

      https://KEYCLOAK/realms/REALM

      KeyCloak 16 或更早版本

      https://KEYCLOAK/auth/realms/REALM

    • 登录页面网址：

      KeyCloak 17 或更高版本

      https://KEYCLOAK/realms/REALM/protocol/saml

      KeyCloak 16 或更早版本

      https://KEYCLOAK/auth/realms/REALM/protocol/saml

    • 退出账号页面网址：

      KeyCloak 17 或更高版本

      https://KEYCLOAK/realms/REALM/protocol/openid-connect/logout

      KeyCloak 16 或更早版本

      https://KEYCLOAK/auth/realms/REALM/protocol/openid-connect/logout?redirect_uri=https://KEYCLOAK/auth/realms/REALM/account/

    • 更改密码网址：

      KeyCloak 17 或更高版本

      https://KEYCLOAK/realms/REALM/account

      KeyCloak 16 或更早版本

      https://KEYCLOAK/auth/realms/REALM/account

    在所有网址中，替换以下内容：

    • KEYCLOAK：Keycloak 服务器的完全限定域名
    • REALM：所选大区的名称

    暂时不要上传验证证书。

  4. 点击保存。

    随即显示的 SAML 单点登录配置文件页面包含两个网址：

    • 实体 ID
    • ACS 网址

    在下一部分中配置 Keycloak 时，您需要使用这些网址。

配置 Keycloak

您可以通过创建客户端来配置 Keycloak 服务器。

创建客户端

在 Keycloak 中创建新的 SAML 客户端：

  1. 登录 Keycloak 并打开管理控制台。
  2. 选择您要用于联合服务的大区。
  3. 在菜单中，选择客户端。
  4. 点击创建客户端。

  5. 为客户端配置以下设置：

    KeyCloak 19 或更高版本

    • 客户端类型：SAML
    • 客户端 ID：单点登录配置文件中的实体网址。
    • 名称：Google Cloud

    KeyCloak 18 或更早版本

    • 客户端 ID：单点登录配置文件中的实体网址。
    • 客户端协议：saml
    • 客户端 SAML 端点：留空

  6. 点击保存。

  7. 配置以下设置，指定客户端的详细信息：

    KeyCloak 19 或更高版本

    在设置标签页中：

    • 有效的重定向 URI：单点登录配置文件中的 ACS 网址
    • 名称 ID 格式：电子邮件
    • 强制名称 ID 格式：开
    • 为文档签名：关
    • 签名断言：开

    在密钥标签页上：

    • 需要客户签名：关

    KeyCloak 18 或更早版本

    • 名称：诸如 Google Cloud 之类的名称
    • 签名断言：开
    • 需要客户签名：关
    • 强制名称 ID 格式：开
    • 名称 ID 格式：电子邮件
    • 有效的重定向 URI：单点登录配置文件中的 ACS 网址

    对于其他所有设置，保留默认值。

  8. 点击保存。

导出签名证书

Keycloak 对用户进行身份验证后，会向 Cloud Identity 或 Google Workspace 传递 SAML 断言。为了使 Cloud Identity 和 Google Workspace 能够验证该断言的完整性和真实性，Keycloak 使用特殊的令牌签名密钥为断言签名，并提供使 Cloud Identity 或 Google Workspace 能够检查签名的证书。

现在，您需要从 Keycloak 导出签名证书：

  1. 在菜单中，选择大区设置。
  2. 选择密钥标签页。

  3. 找到算法：RS256 对应的行。如果有多行，请使用 Use: SIG 的那一行。然后选择证书。

    这会显示一个包含 base64 编码证书的对话框。

  4. 将 base64 编码的证书值复制到剪贴板。

您必须先添加页眉和页脚，将其转换为 PEM 格式，然后才能使用签名证书。

  1. 打开文本编辑器，例如记事本或 vim。

  2. 粘贴以下页眉，后跟换行符：

    -----BEGIN CERTIFICATE-----

  3. 粘贴剪贴板中的 base64 编码的证书。

  4. 请添加换行符并粘贴以下页脚：

    -----END CERTIFICATE-----

    更改后，该文件类似于以下内容：

    -----BEGIN CERTIFICATE-----
MIICmzCCAYMCBgF7v8/V1TANBgkq...
-----END CERTIFICATE-----

  5. 将文件保存到计算机上的临时位置。

完成 SAML 配置文件

您可以使用签名证书完成 SAML 配置文件的配置：

  1. 返回管理控制台，然后依次前往安全性 > 身份验证 > 使用第三方身份提供商进行单点登录。

    转到“使用第三方身份提供商进行单点登录”

  2. 打开您之前创建的 Keycloak SAML 配置文件。

  3. 点击 IDP 详细信息部分以修改设置。

  4. 点击上传证书，然后选择您先前下载的令牌签名证书。

  5. 点击保存。

您的 SAML 配置文件已完成，但您仍需要分配它。

分配 SAML 配置文件

选择应应用新 SAML 配置文件的用户：

  1. 在管理控制台中的使用第三方身份提供商的单点登录服务页面上，依次点击管理单点登录配置文件分配 > 管理。

    前往“管理单点登录配置文件分配”页面

  2. 在左侧窗格中，选择您要应用单点登录配置文件的群组或组织部门。如要将配置文件应用于所有用户，请选择根组织部门。

  3. 在右侧窗格中，选择其他 SSO 配置文件。

  4. 在菜单中，选择您之前创建的 Keycloak - SAML SSO 配置文件。

  5. 点击保存。

重复上述步骤，将 SAML 配置文件分配给其他群组或组织部门。

测试单点登录

您已完成单点登录配置。现在，您可以检查单点登录是否按预期运行。

  1. 选择满足下列条件的 Keycloak 用户：

    • 该用户具有一个电子邮件地址。
    • 该电子邮件地址对应于 Cloud Identity 或 Google Workspace 账号中现有用户的主电子邮件地址。

    • Cloud Identity 用户没有超级用户权限。

      具有超级管理员权限的用户账号必须始终使用 Google 凭据登录，因此这些账号不适合测试单点登录。

  2. 打开新的浏览器窗口，然后前往 Google Cloud 控制台。

  3. 在 Google 登录页面上，输入用户账号的电子邮件地址，然后点击下一步。

    Google 登录页面。

    系统会将您重定向至 Keycloak。

  4. 输入您的 Keycloak 凭据，然后点击 登录。

    身份验证成功后，Keycloak 会将您重定向回Google Cloud 控制台。由于此用户是首次登录，因此系统会询问您是否接受 Google 服务条款和隐私权政策。

  5. 如果您同意这些条款，请点击接受。

  6. 您将被重定向到 Google Cloud 控制台，控制台会要求您确认偏好设置并接受 Google Cloud 服务条款。如果您同意这些条款，请点击是，然后点击同意并继续。

  7. 点击头像图标，然后点击退出登录。

    系统会将您重定向至 Keycloak。

如果您在登录时遇到问题，请记住，拥有超级用户权限的用户账号可以绕过单点登录，因此您仍然可以使用管理控制台来验证或更改设置。

可选：为网域专用服务网址配置重定向

当您从内部门户或文档链接到 Google Cloud 控制台时，可以使用特定于网域的服务网址来改善用户体验。

与 https://console.cloud.google.com/ 等常规服务网址不同，网域专用服务网址包含您的主网域的名称。未经过身份验证的用户如果点击指向网域专用服务网址的链接，会立即重定向到 Keycloak，而不是先看到 Google 登录页面。

网域专用服务网址的示例包括：

Google 服务 网址 徽标
Google Cloud 控制台 https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://console.cloud.google.com/ Google Cloud 徽标
Google 文档 https://docs.google.com/a/DOMAIN Google 文档徽标
Google 表格 https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://sheets.google.com/ Google 表格徽标
Google 协作平台 https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://slides.google.com/ Google 协作平台徽标
Google 云端硬盘 https://drive.google.com/a/DOMAIN Google 云端硬盘徽标
Gmail https://mail.google.com/a/DOMAIN Gmail 徽标
Google 群组 https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://groups.google.com/ Google 群组徽标
Google Keep https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://keep.google.com/ Google Keep 徽标
Looker Studio https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://lookerstudio.google.com/ Looker Studio 徽标
YouTube https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://www.youtube.com/ YouTube 徽标

如需配置网域专用服务网址，使其重定向到 Keycloak，请执行以下操作：

  1. 在管理控制台的使用第三方身份提供商的单点登录服务页面上，依次点击网域专用服务网址 > 修改。

    前往“网域专用服务网址”页面

  2. 将自动将用户重定向至以下单点登录配置文件中的第三方 IdP 设置为已启用。

  3. 将单点登录配置文件设置为 Keycloak。

  4. 点击保存。

可选：配置登录验证

当用户从未知设备登录时，或者当用户的登录尝试因其他原因看起来可疑时，Google 登录可能会要求用户进行额外的验证。这些登录验证有助于提高安全性，建议您保持启用登录验证。

如果您发现登录验证太麻烦，则可以执行以下操作来停用登录验证：

  1. 在管理控制台中，依次前往安全性 > 身份验证 > 登录验证。
  2. 在左侧窗格中，选择您要停用登录验证的组织部门。如需为所有用户停用登录验证，请选择根组织部门。
  3. 在使用其他单点登录配置文件进行登录的用户的设置下，选择不让 Google 要求用户进行额外的身份验证。
  4. 点击保存。