Keycloak 单点登录

Last reviewed 2024-04-29 UTC

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

目标

  • 配置 Keycloak 服务器，以便 Cloud Identity 或 Google Workspace 能够将其用作身份提供商 (IdP)。
  • 配置 Cloud Identity 或 Google Workspace 账号，以便账号使用 Keycloak 进行单点登录。

准备工作

  1. 如果您没有 Cloud Identity 账号，请注册账号。
  2. 确保您的 Cloud Identity 账号具有超级用户权限。
  3. 如果您的 Keycloak 服务器用于管理多个大区，请确定要用于联合服务的大区。
  4. 确保您对所选大区具有管理员访问权限。

创建 SAML 配置文件

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

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

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

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

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

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

  3. 在 SAML 单点登录配置文件页面上，输入以下设置：

    • 名称：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 对应的行。如果有多个行，请使用带有使用：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. 在管理控制台的使用第三方身份提供商的单点登录服务页面上，点击管理 SSO 配置文件分配 > 管理。

    转到“管理单点登录配置文件分配”

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

  3. 在右侧窗格中，选择其他单点登录配置文件。

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

  5. 点击保存。

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

测试单点登录

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

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

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

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

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

  2. 打开新的浏览器窗口，然后访问 Google Cloud Console。

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

    Google 登录页面。

    系统会将您重定向至 Keycloak。

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

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

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

  6. 您将被重定向到 Google Cloud 控制台，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 徽标

如需配置特定于网域的服务网址以重定向到 Keycloak，请执行以下操作：

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

    转到网域专用服务网址

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

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

  4. 点击保存。

可选：配置登录验证方式

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

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

  1. 在管理控制台中，转到安全性 > 身份验证 > 登录验证。
  2. 在左侧窗格中，选择要为其停用登录验证的组织部门。如需为所有用户停用登录验证，请选择根级组织部门。
  3. 在针对使用其他 SSO 配置文件登录的用户的设置下，选择不要求用户通过 Google 进行其他验证。
  4. 点击保存。

后续步骤