基于Keycloak的SSO平台——Jenkins接入并支持组(group)信息同步

背景

在支持Keycloak第三方认证，同时需要从keycloak中获取到用户（员工）的部门（group）信息，以便于Jenkins针对不同的部门（group）进行权限控制。
因此前提是要飞书把用户的部门信息同步到Keycloak上。我们通过订阅飞书的用户、部门相关事件，开发了一个adapter程序，在接收到飞书事件后，调用一堆飞书API和Keycloak API实现了飞书和Keycloak的部门信息同步，从而使得飞书中用户与部门的增删改事件可以（实时）同步到Keycloak中。

其中Keycloak与飞书的集成可以参考：https://github.com/tedgxt/keycloak-service-social-lark

Jenkins配置前必看

Configure Global Security中Authorization配置为Anyone can do anything。防止切换到oidc登陆时，若不成功无法登陆Jenkins。设置了此项后即使未登录Jenkins也能修改配置（生产环境操作时注意安全性）。
后台备份Jenkins的config.xml文件，以便于配置过程异常时的恢复。

Keycloak配置

创建Jenkins使用的client，此处命名为jenkins-test，类型选择oidc。jenkins-test就是后面Jenkins中要配置的Client ID。
client详情中, 设置Access Type为confidential，并设置Valid Redirect URIs为允许跳转的Jenkins地址。记录Credentials标签页中的Secret，后面在Jenkins配置Client Secret时使用。
配置使得Keycloak可以提供group信息。有两种配置方式，按下面的说明根据实际场景选择其中一种进行配置：

点击client jenkins-test，进入设置页，选择Mappers，右上角点击create。添加group相关映射，Mapper Type选择Group Membership，Token Claim Name配置为group-membership，其中Token Claim Name的值就是jwt token中group信息的key值，后面Jenkins会通过该key获取到group信息。该方法是针对单个client。配置如下图：

image.png
点击Client Scopes->profile->Mappers，Token Claim Name配置为group-membership，Mapper Type设置为Group Membership。注意该方法会导致所有的client的profile信息都包含group信息。
配置如下图

image.png

配置了group相关映射后，调用Keycloak的接口可以获取基于用户的Jwt Token，通过解析Jwt Token可以获取到group-membership信息：

   // 省略了token payload信息
  "scope": "email profile",
  "email_verified": false,
  "name": "xxxx",
  "nickname": "xxxx",
  "preferred_username": "xiatao.guan@xxxxxx",
  "given_name": "xxxx",
  "family_name": "xxxxx",
  "email": "xiatao.guan@xxxxxx",
  "group-membership": [
    "/Dev/HZ Dev/Ops & QA& LBware/QA"

后续Jenkins通过配置，会从token的group-membership中获取用户的group信息。

Jenkins配置

安装OIDC插件

当前Jenkins实际有提供Keycloak插件用于直接对接Keycloak。有配置成功过的同学可以留言交流一下。
当前我们使用OIDC插件来进行配置。

需要配置信息如下：

配置项	值	描述
Client id	jenkins-test	Keycloak中添加的jenkins client的Client ID
Client secret	xxxxx	Keycloak中添加的jenkins client的Secret
Token Server url	xxxxx	获取token的地址
Authorization server url	xxxxx	授权地址
UserInfo server url	xxxxx	获取用户信息的地址
Scopes	openid email phone group-membership等	一定要包含group-membership，否则无法获取到group信息
User name field name	email	使用email作为jenkins用户名
Full name field name	email	使用email作为jenkins用户全名
Email field name	email	email
Groups field name	group-membership	Keycloak中配置的group的映射名

image.png

保存后退出当前用户，重新登陆Jenkins会跳转到Keycloak的登陆页面。我们在Keycloak中集成了飞书，通过飞书扫码登录后即跳转到Jenkins主页。
进入用户详情页，若当前用户有管理员权限，可以看到Groups信息，如下图:

image.png

若只是普通用户，在用户详情页看不到Groups信息，可以访问 http://127.0.0.1:8280/whoAmI/ 获取到当前登陆用户的Groups信息，如图：

image.png

后面就可以通过配置Jenkins的授权策略，来实现基于group的权限管理啦。

Trobule Shotting

在生产环境Jenkins接入keycloak，在Keycloak/飞书登陆后，Jenkins跳转后页面报401错误/securityRealm/finishLogin 401。检查对比了Keycloak和Jenkins线上与线下环境相关的配置，发现配置都是相同的。
经过分析HTTP请求，发现线上环境的Jenkins对外暴露的是域名https://jenkins.xxxxx.com/，而认证后跳转到的401地址是http://10.xx.xx.xx:8080/securityRealm/finishLogin。
http://10.xx.xx.xx:8080是Jenkins的ip访问地址，并且通过该IP访问方式，Keycloak/飞书可以成功登陆并跳转到Jenkins页面。
检查Jenkins的配置，发现Jenkins URL被配置成了http://10.xx.xx.xx:8080，导致通过域名方式访问Jenkins并认证后，跳转到了http://10.xx.xx.xx:8080，此处应该是存在session问题，导致认证失败报401错误。于是把Jenkins URL改为域名https://jenkins.xxxxx.com/，生效后通过域名登陆成功。