同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,设置完成后也可进行单点登录。