Keycloak 单点登录示例¶

操作场景¶

Keycloak 是一个开源的、面向现代应用和分布式服务的身份认证和访问控制的解决方案，Keycloak 单点登录支持 OpenID Connect、OAuth 2.0、SAML 2.0 三种协议，观测云基于 SAML 2.0 协议，实现 Keycloak 账户单点登录到观测云平台访问对应工作空间资源，无需另外创建企业/团队的观测云账号。

本文使用搭建的 Keycloak 服务器，演示如何使用 SAML 2.0 协议实现 Keycloak 用户 SSO 登录到观测云管理控制台。

关于使用 OpenID Connect 协议实现 Keycloak 用户 SSO 登录到观测云管理控制台，可参考文档 Keycloak单点登录（部署版）。

前置条件¶

已搭建 Keycloak 服务器，并能登录到 Keycloak 服务器进行配置。若无 Keycloak 环境，可参考以下步骤搭建。

sudo yum update         #更新

sudo yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel      #安装JDK

wget https://downloads.jboss.org/keycloak/11.0.2/keycloak-11.0.2.zip   #下载Keycloak

yum install unzip       #安装解压缩包

unzip keycloak-11.0.2.zip       #解压下载的Keycloak

cd keycloak-11.0.2/bin         #进入 bin 目录

./add-user-keycloak.sh -r master -u admin -p admin     #创建服务器管理员登录账号和密码

nohup bin/standalone.sh -b 0.0.0.0 &     #返回 bin 目录，并在后台挂在 Keycloak 启动服务

Keycloak环境搭建完成后，在浏览器输入https://IP地址:8443/auth，点击“Administration Console”，打开 Keycloak 管理控制台。

概念先解¶

下面是 KeyCloak 配置过程中的基本概念解释：

字段	描述
Realm	领域，类似工作空间，用于管理用户、凭证、角色和用户组，领域之间相互隔离。
Clients	客户端是可以请求 Keycloak 对用户进行认证的应用或者服务。
Users	能够登录到系统的用户账号，需要配置登录邮箱以及 Credentials。
Credentials	验证用户身份的凭证，可用于设置用户账号的登录密码。
Authentication	识别和验证用户的过程。
Authorization	授予用户访问权限的过程。
Roles	用于识别用户的身份类型，如管理员、普通用户等。
User role mapping	用户与角色之间的映射关系，一个用户可关联多个角色。
Groups	管理用户组，支持将角色映射到组。

操作步骤¶

1、创建 Keycloak realm¶

Attention

Keycloak 本身有一个主域（Master），我们需要创建一个新的领域（类似工作空间）。

1）在 Keycloak 管理控制台，点击 Master > Add realm。

2）在 Add realm 页面，在 Name 处输入领域名称，如“gcy”，点击 Create，即可创建一个新的领域。

2、创建 Client 并配置 SAML¶

Attention

本步骤将创建 Keycloak 客户端并配置 SAML ，建立 Keycloak 和观测云之间的信任关系使之相互信任。

1）在新创建的“gcy”领域下，点击 Client，在右侧点击 Create 。

2）在 Add Client 按照以下内容填写完成后，点击 Save。

Client ID（实体 ID）：https://auth.guance.com/saml/metadata.xml；
Client Protocol：选择SAML；
Client SAML Endpoint（断言地址），临时使用：https://auth.guance.com/saml/assertion。

Attention

此次配置仅为获取下一步的元数据文档使用，需要在观测云中启用SSO单点登录后，获取到正确的实体ID和断言地址后重新替换。

Client 创建后，在Settings可以看到上一步填写的实体ID、协议和断言地址。设置如下参数后保存。

Sign Assertions：ON（用于防止 IdP 传输的数据被篡改，保证从 IdP 传输到 SP 的数据安全。）

IDP Initiated SSO URL Name：可任填，如“gcy”，填完以后会生成 SSO 单点登录地址，见下图；
Base URL：填入上一个参数生成的 SSO 单点登录地址，如/auth/realms/gcy/protocol/saml/clients/gcy，这个主要用于在 Keycloak Clients 生成访问链接直接单点登录到观测云。

3）在Clients的Mappers，点击 Create，创建邮箱映射，此部分内容为必填项，如果不填，无法实现 SSO 单点登录。

在 Create Protocol Mapper 页面，输入以下内容后，并保存。

Name：可任填，如“mail mapper”；
Mapper Type：选择“User Property”；
Property：按照身份提供商的支持的规则填入 Email；
SAML Attribute Name：必需填入 Email。

Attention

观测云定义了一个映射字段，必须填入 Email 用于关联身份提供商的用户邮箱（即身份提供商将登录用户的邮箱映射到Email）。

3、获取 KeyCloak 元数据文档¶

Attention

本步骤可获取在观测云创建身份提供商的元数据文档。

1）在 Clients 的 Installation，选择 Mod Auth Mellon files，点击 Download 下载元数据文档。

2）在下载的文件夹中，选择 idp-metadata.xml。

3）由于 Keycloak 的云数据文档是域级别的，需要在元数据文档 idp-metadata.xml 中的访问地址增加客户端的参数/clients/<IDP Initiated SSO URL Name>，此文档中由于设置了IDP Initiated SSO URL Name：gcy，故在xml文件中填入/clients/gcy，见下图。添加完成后保存xml文件。