操作指南｜JumpServer与Keycloak集成对接

本文重点介绍两种常见的单点登录协议，即OIDC（OpenID Connect）协议和SAML 2.0（Security Assertion Markup Language）协议，以及如何在JumpServer开源堡垒机上完成与Keycloak的集成对接。

此前，我们专门介绍过JumpServer与Okta集成对接的方法，可参见《操作指南丨JumpServer与Okta集成对接》一文。

一、概要

■ 单点登录

单点登录（Single Sign On，简称为SSO）是一种身份验证方案，允许用户使用单一的认证凭证访问到多个独立的软件系统中的任意一个，减少了用户重复认证的步骤，并且统一了不同软件间的用户认证管理。

常见的单点登录认证协议包括: OIDC、OAuth 2.0、SAML 2.0、CAS等。

■ Keycloak

Keycloak是一个针对现代应用程序和服务的开源身份和访问管理解决方案。Keycloak提供用户联合、强身份认证、用户管理及细粒度权限管理等功能，旨在帮助用户能够在最小的成本下向应用程序和服务中添加身份验证等功能。另外，Keycloak支持单点登录，因此服务可以通过OIDC、OAuth 2.0等协议对接Keycloak。

■ OIDC

OIDC（OpenID Connect）在OAuth 2.0上构建了一个身份层，是一个基于OAuth 2.0协议的身份认证标准协议。OIDC使用OAuth 2.0的授权服务器来为第三方客户端提供用户的身份认证，并把对应的身份认证信息传递给客户端，且可以适用于各种类型的客户端（例如服务端应用、移动APP、JavaScript应用），且完全兼容OAuth 2.0协议。

■ SAML

SAML（Security Assertion Markup Language）是一种用于安全性断言的标记语言，目前的最新版本是2.0，是Web浏览器用来通过安全令牌启用单点登录（SSO）的标准协议。

■ OIDC协议与SAML 2.0协议之间的相同点与不同点：

二、对接前的准备工作

1. Keycloak的官网地址为：https://www.keycloak.org/；

2. Keycloak的部署可参照其官网的用户手册选择相应的方式进行部署：
   https://www.keycloak.org/guides；

3. 本文档选用的是Docker部署方式，Keycloak版本为19.0.2。

三、SAML 2.0协议对接

■ 对接步骤：

1. 根据图示顺序打开JumpServer中关于SAML 2.0认证的设置界面；
   

2. 根据下方命令，将生成的server.key及server.crt分别放入到JumpServer认证设置页面中的“SP密钥”及“SP证书”中，然后点击“查看”链接 ，将显示内容保存至本地文件中（我们这里保存并命名为jumpserver_metadata.xml），以便后续使用；

$ openssl genrsa -out server.key 2048  # 这个生成的是 私钥
$ openssl req -new -x509 -days 3650 -key server.key -out server.crt -subj "/C=CN/ST=mykey/L=mykey/O=mykey/OU=mykey/CN=domain1/CN=domain2/CN=domain3"  # 这个是证书

3. 进入到部署好的Keycloak服务控制台，创建一个新的Realm，并自定义名称，这里我们命名为“JumpServer-SAML2”；
   
   

4. 按照图示，新建一个Client；
   

5. 根据页面提示，将必须填写的信息填入到对应的选项即可。Client type选择“SAML”，Client ID填入：http[s]
   /host:ip/core/auth/saml2/login/，域名更换成自己JumpServer下的域名或者IP，点击下方“Save”按钮保存；
   

6. 创建完Client后，在Access settings栏修改配置，域名更换为自己JumpServer下的域名或者IP，点击下方“Save”按钮保存；
   

7. 在“Keys”选项卡中，将Client signature required调整为“Off”状态；
   

8. 点击“Client scopes”选项卡中的第一行“Assigned client scope”链接；
   

9. 点击“Configure a new mapper”按钮，进行用户属性映射配置，此配置将决定Keycloak中用户的哪些属性和JumpServer的属性相对应起来；
   

10. 选择“User Attribute”选项；
    

11. 创建用户映射，并按照下图所示填写相关信息；
    
    

12. 按照图示步骤，创建用户；
    
    
    

13. 根据图示顺序，获取Keycloak端的Metadata配置信息文件内容；
    

14. 切换至JumpServer页面，打开SAML2认证，将新弹出的会话窗口页面的浏览器地址栏中的地址复制到JumpServer的IDP metadata URL中，点击“提交”按钮，即可完成配置。
    
    

四、OIDC-OpenID协议对接

■ 对接步骤：

1. 进入到部署好的Keycloak服务控制台，创建一个新的Realm，并自定义名称，这里我们命名为“JumpServer-OIDC”；
   
   

2. 按照图示，新建一个Client；
   

3. 根据页面提示，将必须填写的信息填入到对应的选项即可，Client type选择 “OpenID Connect”，Client ID自定义即可，这里选择将JumpServer的域名填入，点击下方“Next”按钮；
   

4. 按照图示进行配置，点击“Save”按钮即可；
   

5. 创建完Client后，在此Access settings栏修改配置，域名更换为自己JumpServer下的域名或者IP，点击下方“Save”按钮保存；
   

6. 根据图示，将所选信息保存，并设置填写到JumpServer中，点击提交；
   
   
   

7. 按照图示步骤，创建新用户，即可完成配置；