同Keycloak对接实例（SAML2.0）

1. 简介

1.1 案例简介

通过配置 Keycloak 的相关实例，实现简道云的单点登录业务。

1.2 使用场景

当企业同时拥有多套管理系统和简道云平台，通过单点登录的方式，可以实现登录相关管理系统后，免登录进入简道云中，便于多个系统平台之间的切换，提高企业管理效率。

1.3 预期效果

访问简道云企业 URL时，点击单点登录，通过输入 Keycloak 中设置的用户名及密码后，成功登录到了简道云中。

2. 设置步骤

2.1 在Keycloak中创建相关实例

2.1.1 登录到Keycloak控制台

打开Keycloak，点击左侧「Administration Console」，输入账号密码后（无账号的需要先注册），登录到 Keycloak 控制台中。

2.1.2 新增realm实例

1）在 Keycloak 控制台中，点击 Master 右侧的下拉箭头，在弹出的面板中点击「Add realm」，并修改 realm 的名字为 Test，修改完成后点击「Create」。如下所示：

2）realm 实例创建完成后，在「 realm 实例 >> Keys 」处，选择 Type 类型为「RSA」的算法，点击该算法最右侧的「Certificate」，在弹出的面板中，复制并保存对应的秘钥。

注：请务必复制并保存秘钥，便于后面步骤的配置与使用。

2.1.3 新增client实例

1）切换左侧导航栏至「Clients」，点击页面右侧的「Create」按钮，创建新的 Client 实例：

在「Client ID」处，设置 ID 名称，如设置其为 SSO；
在「Clients Protocol」处，选择类型为「saml」。

全部设置完成后点击「Save」按钮进行保存。

2）在「SSO >> Settings」处，确认打开「Enabled」、「Include AuthnStatement」、「Sign Docunments」这 3 部分的开关。

3）同时，对其他配置项进行如下所示操作：

Signature Algorithm：下拉框内选择「RSA_SHA256」；
SAML Signature Key Name：下拉框内选择「KEY_ID」；
Canonicalization Method：下拉框内选择「EXCLUSIVE」；
Name ID Format：下拉框内选择「username」；
IDP Initiated SSO URL Name：根据企业需求，设置名称，如设置其名称为 jdy。

其他配置项保持默认即可。

4）以上配置项确认设置完成后，复制并保存 SSO URL 地址，复制完成后点击「Save」进行保存。如下所示：

注：请务必复制并保存 URL 地址，便于后面步骤的配置与使用。

2.1.4 新增mapper配置

1）在「SSO >> Mappers」处，点击右侧「Create」按钮，新增 mapper 配置。

2）对于新增的 mapper ，进行如下所示的配置：

Name：设置其名称为「username」；
Mapper Type：下拉框内选择「User Property」；
Property：设置其为「username」；
SAML Attribute Name：设置其为「username」；
SAML Attribute NameFormat：下拉框内选择为「Basic」。

设置完成后，点击「Save」按钮，保存以上设置。

注：该步骤中，各项配置须与图示保持一致，不可随意更改。

2.1.5 新增用户

1）切换左侧导航栏至「Users」处，点击右侧「Add user」按钮，并在新增用户面板上，设置 Username。设置完成后点击「Save」进行保存。

注：

1）确保新增用户的 username，在简道云系统中存在相同 username 的成员。

2）Keycloak 中仅能识别小写字母，其他如大写字母、符号等无法识别；故确保用户的 username 是由小写字母组成的。

2）在「新增的用户名 >> Credentials」处，设置用户密码，如下所示：

2.2 在简道云中配置单点登录

2.2.1 开启单点登录

1）新开一个浏览器页面，登录简道云账号，进入「企业管理 >> 管理工具 >> 企业设置」页面中。

2）在「企业安全 >> 单点登录」处，打开单点登录的开关，并点击「配置」按钮。

2.2.2 配置单点登录

单点登录配置项如下所示，部分配置信息需复制 Keycloak 中 Client 实例的配置信息。

单点登录配置方式：SAML 2.0
SAML 2.0 Endpoint（HTTP）：复制 Keycloak 中「Clients >> SSO >> Settings >> IDP Initiated SSO URL Name 」处的内容，即本文【2.1.3 新增client实例】中的 SSO URL 地址。
IdP公钥：复制 Keycloak 中「 Realm Settings >> Keys >> Certificate 」处的内容，即本文【2.1.2 新增realm实例】中要求复制的秘钥内容。
SAML 加密算法：下拉框中选择「SHA-256 」。
Issuer URL：复制 Keycloak 中「Clients >> SSO >> Settings >> IDP Initiated SSO URL Name 」处的内容，即本文【2.1.3 新增client实例】中的 SSO URL 地址，并去掉 test 之后的地址后缀。
SLO Endpoint (HTTP)：保持默认即可。

2.2.3 生成单点登录信息

完成单点登录配置后，会生成如下单点登录相关信息，复制并保存「认证返回地址」。

注：需要根据生成的信息去完成 Keycloak 中的相关配置，故可以暂时不关闭此页面。

2.3 在Keycloak中回调URL

返回到「Keycloak >> Clients >> SSO >> Settings 」配置页面，按照如下所示进行配置，配置内容需要复制简道云中单点登录信息。

Valid Redirect URls：复制简道云中的认证返回地址；
Master SAML Processing URL：复制简道云中的认证返回地址。

配置完成后点击「Save」进行保存。

2.4 效果演示

效果演示参见本文【1.3 预期效果】。

3. 注意事项

在「Clients >> SSO >> Mappers」设置中，若 Mappers username 是由域账户自动生成的，此时在新增的 Users 处，添加新的 Attributes 并设置其值为企业微信 ID，设置完成后也可进行单点登录。