<!-- Space: qifu -->
<!-- Parent: 后端技术&知识&规范 -->
<!-- Parent: 技术方案 -->
<!-- Parent: 基建 -->
<!-- Parent: 03-接入指南 -->
<!-- Title: 20250104-JenkinsSSO接入指南 -->

<!-- Macro: :anchor\((.*)\):
     Template: ac:anchor
     Anchor: ${1} -->
<!-- Macro: \!\[.*\]\((.+)\)\<\!\-\- width=(.*) \-\-\>
     Template: ac:image
     Url: ${1}
     Width: ${2} -->
<!-- Macro: \<\!\-\- :toc: \-\-\>
     Template: ac:toc
     Printable: 'false'
     MinLevel: 2 
     MaxLevel: 4 -->
<!-- Include: 杂项/声明文件.md -->

<!-- :toc: -->

# Jenkins SAML 插件整合 Keycloak 配置指南

## SAML 插件安装
![](https://picture.texous.cn/blog/20250103151018411.png)

## Jenkins SAML配置
### Security > Security Realm
#### 检索 Jenkins 服务提供商元数据
- 选择 `SAML2.0`
- `IdP Metadata URL` 配置 Keycloak `http://keycloak.qifu.com/realms/keyfil/protocol/saml/descriptor`
- `Refresh Period` 配置为 `1440` (24h, 建议值)
- 单击 `Validate IdP Metadata` 以确保可以获取元数据
- 点击 `Apply`
- 查找 `Service Provider Metadata` 链接并将其另存为 XML 文件，例如 `jenkins-sp-metadata.xml`
- **不要关闭页面**

#### 将新客户端导入 Keycloak 领域
- 在 `客户端（clients）` 页面上选择 `导入客户端（Import client）`
- 选择刚刚保存的 `jenkins-sp-metadata.xml` 作为您的 `Resource file`
- （可选）提供有意义的 Name 和 Description
- **不要修改客户端ID，不要修改客户端ID，不要修改客户端ID**
- 点击保存
- 找到 `Name ID format` 字段并更改为 `username` 或 `persistent`
- 切换到 `客户端范围` 标签
- 打开客户端 dedicated 范围
- 添加 `预定义映射`
- 选择 `X500 email` 、 `X500 givenName` ， `X500 surname` 然后单击 `添加`
- 记录里面的 `SAML Attribute Name`

#### 回到 Jenkins
- 配置 `Display Name Attribute` 为 `urn:oid:2.5.4.42`
- 配置 `Email Attribute` 为 `urn:oid:1.2.840.113549.1.9.1`
- 配置 `Group Attribute` 为 `Role`
- 以上配置来自 Keycloak 最后一步记录的 `SAML Attribute Name` 值
- 点击 Save


### 建议
- 初次配置时可以将 Authorization 配置为 `Anyone can do anything`
- 主要是当 saml 配置错误的时候还可以修改，不需要改配置
- 等验证完成后再修改回去
- ![](https://picture.texous.cn/blog/20250103162834235.png)

## 参考

- [Jenkins SAML Keycloak](https://github.com/jenkinsci/saml-plugin/blob/main/doc/CONFIGURE_KEYCLOAK.md)