在企业研发场景中，Jenkins 作为核心 CI/CD 工具，与 Synology DSM（存储代码包、构建产物）常需协同使用，但 “分别登录” 模式存在明显痛点：开发人员需记忆 “Jenkins 账号密码” 与 “Synology SSO 账号密码” 两套凭证，登录操作繁琐且易遗忘；IT 管理员需在 Jenkins 与 Synology 中分别维护研发团队权限（如员工离职时需两处禁用账号），管理成本高且易出现权限残留。通过 Synology SSO Server（单点登录服务器）为 Jenkins 配置 SAML（安全断言标记语言）单点登录，可实现 “一次验证，无缝访问 Synology DSM 与 Jenkins”—— 开发人员只需在 Synology SSO 完成身份验证，即可自动登录 Jenkins，无需重复输入密码。但多数 IT 管理员不清楚 “如何将 Synology SSO 作为 IdP 对接 Jenkins”“Jenkins 需安装哪些插件”“用户映射如何配置”，甚至因插件版本不兼容、元数据格式错误导致配置失败。本文基于 Synology 官方技术文档，从 “场景价值→基础认知→前置准备→分步实操→问题排查”5 个维度，提供企业级 Jenkins SAML 单点登录落地指南，确保配置一次成功。

一、先明确：为什么要为 Jenkins 配置 Synology SSO SAML？3 大核心价值

在动手配置前，需先明确 “Jenkins 与 Synology SSO 集成” 的企业级需求，这是后续规范操作的核心依据：

1. 简化研发登录流程，提升效率

开发人员日常需频繁访问 Jenkins（触发构建、查看日志）与 Synology DSM（获取代码包、存储构建产物），SAML 单点登录可将登录流程从 “两次验证” 简化为 “一次验证”：
  • 传统流程：打开 Jenkins→输入 Jenkins 账号密码→登录；打开 DSM→输入 Synology 账号密码→登录（需记忆两套凭证）；
  • SAML 流程：打开 Jenkins→自动跳转至 Synology SSO→输入 SSO 账号密码→登录 Jenkins（后续访问 DSM 无需重复验证），步骤减少 50%，尤其适合高频使用 Jenkins 的研发团队。

2. 统一权限管理，降低 IT 成本

IT 管理员无需在 Jenkins 与 Synology 中分别创建、维护研发账号，只需在 Synology SSO Server 中管理一套账号体系：
  • 员工入职：在 Synology SSO 创建账号并加入 “研发组”，自动同步至 Jenkins（无需手动在 Jenkins 添加用户）；
  • 员工离职：在 Synology SSO 禁用账号，Jenkins 权限同步失效（避免 “Jenkins 账号残留导致未授权构建” 风险），IT 管理工作量降低 80%。

3. 强化安全防护，符合研发合规

Synology SSO Server 支持 “多因素认证（2FA）”（如安全密钥、Synology Authenticator 验证码），为 Jenkins 登录增加 “第二道防线”，同时满足研发安全合规要求：
  • 禁止非信任 IP 登录：在 Synology SSO 中设置 “仅企业内网 / 研发 VPN IP 可登录”，防止开发人员在外网非安全环境访问 Jenkins；
  • 登录日志审计：通过 Synology SSO 记录 Jenkins 登录行为（时间、IP、设备），便于追溯 “未授权构建” 等安全事件。

二、基础认知：SAML 协议的 “IdP 与 SP” 分工（核心逻辑不踩坑）

配置前需明确 SAML 协议中两个核心角色的分工，避免因概念混淆导致配置偏差 ——Synology SSO Server 与 Jenkins 的角色定位的准确性，是单点登录成功的前提：
角色
承担者
核心职责
关键输出 / 输入
IdP（身份提供商）
Synology SSO Server
负责 “身份验证”：验证开发人员的 SSO 账号密码（含 2FA），生成合法的 “SAML 断言”（含用户身份、所属组信息）
输出：IdP 元数据（含 SAML 端点、签名证书）、SAML 断言
SP（服务提供商）
Jenkins
负责 “资源访问控制”：不直接验证密码，接收 IdP 发送的 SAML 断言，验证合法性后允许开发人员访问 Jenkins 构建资源
输入：IdP 元数据；输出：SP 元数据（含 ACS URL）
SAML 单点登录核心流程：
  1. 开发人员访问 Jenkins（SP）→Jenkins 检测到未登录，自动跳转至 Synology SSO Server（IdP）；
  1. 开发人员在 IdP 输入 SSO 账号密码 + 完成 2FA 验证；
  1. IdP 生成 SAML 断言（加密用户信息），发送至 Jenkins 的 ACS URL（断言消费者服务地址）；
  1. Jenkins 验证 SAML 断言的合法性（通过 IdP 证书），确认无误后自动登录，跳转至 Jenkins 控制台。

三、前置准备：配置前必做的 4 件事（条件不满足必失败）

Jenkins SAML 单点登录对 “软件版本、插件、权限、网络” 有严格要求，未满足以下条件会直接导致配置中断，需逐一核对（Jenkins 需为 2.300 及以上版本，旧版本不支持 SAML 插件最新功能）：
准备项目
具体要求
检查 / 操作方法
1. 软件与插件准备
① Synology SSO Server：需安装 “Synology SSO Server” 套件（DSM 7.0 及以上，推荐 7.2 最新版，如 Build 69057）；② Jenkins：版本≥2.300（旧版本插件兼容性差），需安装 “SAML 2.0” 插件（官方名称：SSO for Jenkins - SAML 2.0）；③ IdP 设备：1 台 Synology NAS（如 DS224+、DS923+，内存≥4GB，确保 SAML 服务稳定运行）
1. 检查 Jenkins 版本：登录 Jenkins→点击左下角 “Manage Jenkins→About Jenkins”，确认版本≥2.300；2. 安装 SAML 插件：Jenkins→Manage Jenkins→Plugins→Available Plugins，搜索 “SSO for Jenkins - SAML 2.0”，勾选后点击 “Install without restart”；3. 确认 SSO Server 版本：Synology NAS→套件中心→已安装→Synology SSO Server，确认版本≥2.0
2. 账号权限准备
① Synology SSO：需 “administrators 组” 账号（如 admin），用于配置 IdP 服务、添加 SP 信任；② Jenkins：需管理员账号（如 admin），用于安装插件、配置 SAML SP 参数；③ 测试账号：在 Synology SSO 创建 1 个 “研发组” 测试账号（如 “dev1”），用于后续登录验证
1. 确认 Jenkins 管理员权限：登录 Jenkins 后，若能看到 “Manage Jenkins” 菜单，说明具备管理员权限；2. 创建测试账号：Synology NAS→控制面板→用户与群组→用户→创建 “dev1”，加入 “研发组”（提前创建 “研发组”）
3. 网络与 URL 准备
① 网络连通性：Jenkins 服务器与 Synology SSO Server 需在同一局域网（或通过 VPN 跨网段连通），互相能 ping 通；② Jenkins URL 配置：需在 Jenkins 中设置 “Jenkins URL”（固定访问地址，如http://192.168.1.200:8080），SAML ACS URL 依赖此地址生成
1. 测试网络：在 Jenkins 服务器终端输入ping Synology SSO Server IP（如 ping 192.168.1.100），确保通网；2. 配置 Jenkins URL：Jenkins→Manage Jenkins→Configure System→Jenkins Location，在 “Jenkins URL” 输入固定地址（如http://192.168.1.200:8080），点击 “Save”
4. 元数据认知准备
需理解 “IdP 元数据” 与 “SP 元数据” 的作用：① IdP 元数据：由 Synology SSO 生成，含 SAML 登录端点、签名证书，需导入 Jenkins；② SP 元数据：由 Jenkins 生成，含 ACS URL，可导入 Synology SSO（简化 IdP 配置）
1. 提前创建元数据存储路径：在 Synology NAS 创建 “SSO_Metadata” 共享文件夹，用于存放导出的 IdP 元数据；2. 确认 Jenkins ACS URL 格式：ACS URL 为 “Jenkins URL + /saml/acs”（如http://192.168.1.200:8080/saml/acs），后续配置需用到

四、核心步骤 1：配置 Synology SSO Server 作为 SAML IdP（身份提供商）

首先需在 Synology SSO Server 中启用 SAML 服务、添加 Jenkins 的 SP 信任条目、导出 IdP 元数据，步骤如下（以 DSM 7.2 为例，DSM 7.0/7.1 操作逻辑一致）：

步骤 1：启用 Synology SSO 的 SAML 服务

  1. 登录 Synology NAS（IdP 设备，IP 如 192.168.1.100），打开「Synology SSO Server」套件；
  1. 点击左侧菜单栏「SAML→身份提供商（IdP）」，进入 IdP 配置页面；
  1. 点击「启用 SAML 身份提供商」，系统自动生成关键配置（无需手动修改，确保安全性）：
    • 签名证书：用于加密 SAML 断言（防止传输中被篡改），系统默认生成，企业也可点击「导入证书」上传自定义 CA 证书（需.pem 格式）；
  1. 点击「保存」，页面顶部显示 “IdP 服务已启用”，说明 SAML 服务启动成功。

步骤 2：添加 Jenkins 的 SP（服务提供商）信任条目

需在 IdP 中添加 Jenkins 的 SP 信息，确保 IdP 仅向授权的 Jenkins 发送 SAML 断言：
  1. 在「SAML→身份提供商（IdP）」页面，点击「添加服务提供者（SP）」；
  1. 进入 “基本信息” 配置页，输入 Jenkins 的 SP 关键参数（ACS URL 与 SP 实体 ID 需与 Jenkins 配置一致）：
    • SP 名称：自定义名称（如 “Jenkins_研发 CI”，便于 IT 识别）；
    • 单点登录服务 URL：默认与 ACS URL 一致，无需修改；
  1. 点击「下一步」，进入 “属性映射” 页面（核心：将 Synology SSO 的用户属性传递给 Jenkins，用于用户匹配）：
    • 点击「添加属性」，设置 “IdP 属性” 为 “email”（Synology SSO 中用户的电子邮件字段），“SP 属性” 为 “NameID”；
    • 勾选 “作为 NameID 发送”（关键必选：Jenkins 仅通过 NameID 识别用户，不勾选会导致登录时 “用户不匹配”）；
    • （可选）添加 “组属性映射”：若需同步用户组（如 “研发组”），点击「添加属性」，设置 “IdP 属性” 为 “group”，“SP 属性” 为 “JenkinsGroup”，便于 Jenkins 基于组分配权限；
  1. 点击「下一步」，进入 “权限设置” 页面，限制可登录 Jenkins 的用户范围（企业推荐精细化控制）：
    • 勾选 “指定用户组”，在下拉框中选择 “研发组”（仅该组用户可通过 SSO 登录 Jenkins）；
    • 取消勾选 “允许所有用户”（避免非研发人员登录 Jenkins，保障构建安全）；
  1. 点击「完成」，Jenkins 的 SP 信任条目添加成功，IdP 已认可 Jenkins 为授权服务提供商。

步骤 3：导出 IdP 元数据（用于 Jenkins 配置）

IdP 元数据含 Jenkins 所需的 SAML 端点与证书，需导出并保存至可访问路径：
  1. 在「SAML→身份提供商（IdP）」页面，点击「导出元数据」；
  1. 选择保存路径（如之前创建的 “SSO_Metadata” 共享文件夹），文件命名为 “Synology_SSO_IdP_Metadata.xml”，点击「确定」；
  1. 验证元数据完整性：用记事本打开文件，确认包含 标签（无乱码、无标签缺失），若缺失需重新导出（可能是导出时网络中断导致）。

五、核心步骤 2：配置 Jenkins 作为 SAML SP（服务提供商）

Jenkins 需导入 IdP 元数据、配置 SAML 登录规则，确保能接收并验证 IdP 发送的 SAML 断言，步骤如下（以 Jenkins 2.401 为例）：

步骤 1：进入 Jenkins SAML 配置页面

  1. 登录 Jenkins 管理员账号，点击左侧菜单栏「Manage Jenkins→Configure Global Security」；
  1. 在 “Security Realm”（安全域）下拉框中，选择 “SAML 2.0”（安装 SAML 插件后才会显示，若未显示需重启 Jenkins）；
  1. 点击 “SAML 2.0” 下方的「Configure」按钮，进入 SAML 详细配置页面。

步骤 2：导入 Synology SSO 的 IdP 元数据

  1. 在 “IdP Metadata”（IdP 元数据）配置区，选择 “Upload metadata file”（推荐，避免手动输入错误）；
  1. 点击「Choose File」，选择从 Synology SSO 导出的 “Synology_SSO_IdP_Metadata.xml” 文件，点击「Upload」；
  1. 系统自动解析元数据，填充以下关键参数（无需手动输入，若解析失败需检查元数据文件完整性）：
    • IdP Entity ID：自动填充为 Synology SSO 的 IdP 实体 ID；
    • IdP Certificate：自动导入 Synology SSO 的签名证书（用于验证 SAML 断言）；
  1. 若解析失败（如提示 “Invalid metadata”）：选择 “Enter metadata URL”，输入 Synology SSO 的 IdP 元数据 URL（如 “https://192.168.1.100:5001/sso/saml/idp/metadata”），点击「Validate」完成导入。

步骤 3：配置 Jenkins SAML 关键参数

  1. 在 “SP Configuration”（SP 配置）区，确认 “Service Provider Entity ID” 与 “Assertion Consumer Service URL”：
    • Assertion Consumer Service URL：默认填充为 Jenkins 的 ACS URL（如 “http://192.168.1.200:8080/saml/acs”），需与 Synology SSO 中配置的 ACS URL 完全一致（含端口、路径）；
  1. 在 “User ID Mapping”（用户 ID 映射）区，设置 Jenkins 如何通过 SAML 断言识别用户：
    • 选择 “NameID”（与 Synology SSO 的属性映射一致，因之前设置 NameID 为 email，此处 Jenkins 会用 SAML 断言中的 email 作为用户 ID）；
    • （可选）若需用用户名映射：在 Synology SSO 属性映射中设置 NameID 为 “username”，此处同步选择 “NameID”；
  1. 在 “Authorization”（授权）区，设置 Jenkins 权限（企业推荐基于用户组授权）：
    • 选择 “Matrix-based security”（矩阵式安全）；
    • 点击「Add user or group」，输入 “研发组”（Synology SSO 中同步的用户组名称），勾选 “Overall→Read”“Job→Build” 等研发必需权限；
  1. 点击页面底部「Save」，Jenkins SAML 配置完成，自动跳转至登录页面（此时默认登录方式已变为 SAML）。

六、关键验证：测试 Jenkins SAML 单点登录是否生效

配置完成后，用 “研发组” 测试账号（如 “dev1”）验证登录流程，确保单点登录正常：

步骤 1：发起 Jenkins 登录

  1. 打开浏览器，访问 Jenkins URL（如http://192.168.1.200:8080）；
  1. 页面自动跳转至 Synology SSO Server 登录页面（显示 “通过 Synology SSO 登录 Jenkins” 提示），无手动选择登录方式，说明 SAML 跳转正常。

步骤 2：Synology SSO 身份验证

  1. 在 Synology SSO 登录页，输入测试账号 “dev1” 的 SSO 密码；
  1. （若启用 2FA）完成多因素认证（如输入 Synology Authenticator 生成的 6 位验证码，或插入安全密钥）；
  1. 验证通过后，页面无需手动操作，自动跳转回 Jenkins。

步骤 3：确认 Jenkins 登录成功

  1. 跳转回 Jenkins 后，直接进入 “Jenkins 控制台”，右上角显示当前登录用户为 “dev1”（与 SSO 账号一致）；
  1. 验证权限：尝试创建测试任务（Job）并触发构建，确认能正常操作（无 “权限不足” 提示）；
  1. 退出测试：点击 Jenkins 右上角 “dev1→Sign Out”，再次访问 Jenkins，仍自动跳转至 SSO 登录，说明单点登录流程完整。

七、常见问题解答：Jenkins SAML 配置的 4 大高频问题（官方解决方案）

Q1：Jenkins 中找不到 “SAML 2.0” 安全域选项，怎么办？

  • 原因：1. 未安装 “SAML 2.0” 插件，或插件安装失败；2. Jenkins 版本过低（<2.300），不支持最新插件；3. 插件安装后未重启 Jenkins，未加载插件功能；
  • 解决步骤：
    1. 检查插件安装：Jenkins→Manage Jenkins→Plugins→Installed Plugins，搜索 “SSO for Jenkins - SAML 2.0”，确认状态为 “Installed”；若未安装，重新在 “Available Plugins” 中搜索（确保插件来源为 “Jenkins Update Center”，避免第三方来源插件不兼容）；
    1. 升级 Jenkins 版本：若版本 <2.300，点击 Manage Jenkins→Manage Plugins→Available Plugins，安装 “Jenkins LTS Upgrade Assistant” 插件，按指引升级至 2.300 + 版本；
    1. 重启 Jenkins：点击 Manage Jenkins→Restart Jenkins→“Yes”，重启后重新进入 “Configure Global Security”，即可看到 “SAML 2.0” 选项。

Q2：导入 Synology SSO 元数据时，Jenkins 提示 “Invalid certificate in metadata”，如何处理？

  • 原因：1. 元数据文件中的证书格式错误（如导出时文件损坏，缺失-----BEGIN CERTIFICATE-----标签）；2. 导入的是自定义证书，但证书未通过 Jenkins 信任验证；
  • 解决：
    1. 重新导出 IdP 元数据：在 Synology SSO Server 中删除 Jenkins 的 SP 信任条目，重新添加后导出元数据，用记事本打开确认证书标签完整；
    1. 使用系统默认证书：若之前导入了自定义证书，在 Synology SSO 的「SAML→IdP」页面点击「重新生成证书」，生成系统默认证书，重新导出元数据并导入 Jenkins；
    1. 手动导入证书：若仍失败，在 Jenkins SAML 配置中选择 “Enter IdP certificate manually”，从元数据文件中复制标签内的证书内容（去除换行符），粘贴后点击「Validate」。

Q3：SSO 验证成功后，Jenkins 提示 “User ‘dev1@company.com’ is missing the Overall/Read permission”，怎么解决？

  • 原因：Jenkins 未给 SAML 登录的用户（或用户组）分配 “Overall/Read” 基础权限，导致登录后无访问权限；
  • 解决步骤：
    1. 用 Jenkins 本地管理员账号登录（若无法登录，在 Jenkins 服务器修改config.xml文件，临时将安全域改回 “Jenkins’ own user database”）；
    1. 进入 Manage Jenkins→Configure Global Security→Authorization→Matrix-based security；
    1. 点击「Add user or group」，输入 SAML 登录的用户名（如 “dev1@company.com”，即 SAML 断言中的 NameID）或用户组（如 “研发组”）；
    1. 为该用户 / 组勾选 “Overall→Read” 权限，若需构建权限，额外勾选 “Job→Build”“Job→Workspace”，点击「Save」；
    1. 退出管理员账号，用 SSO 重新登录，权限生效。

Q4：开发人员登录 Jenkins 时，跳转至 Synology SSO 后提示 “无 SSO 登录权限”，但用户已在 “研发组”，怎么办？

  • 原因：1. Synology SSO 的 Jenkins SP 信任条目权限设置错误，未勾选 “研发组”；2. 用户虽在 “研发组”，但组未同步至 SAML 断言；
  • 解决：
    1. 检查 Synology SSO 权限设置：进入 Synology SSO→SAML→IdP→SP 列表→Jenkins→编辑→权限设置，确认 “研发组” 已勾选，且未勾选 “禁止该组登录”；
    1. 确认组属性映射：在 Jenkins SAML 配置的 “Attribute Mapping” 中，添加 “Group Attribute”，设置 “Attribute Name” 为 “JenkinsGroup”（与 Synology SSO 中配置的 SP 属性一致），点击「Save」；
    1. 重新登录：开发人员退出 Synology SSO，清除浏览器缓存后重新登录，组权限同步生效。

八、总结：Jenkins SAML 配置的 3 个关键注意事项

  1. 插件与版本匹配是前提：Jenkins 版本需≥2.300，SAML 插件需为 “SSO for Jenkins - SAML 2.0”（官方插件），避免使用第三方非兼容插件；
  1. 元数据完整性与一致性是核心：Synology SSO 与 Jenkins 的 SP 实体 ID、ACS URL 必须完全一致（含协议 http/https、端口、路径），元数据导出后需验证标签完整性，避免因格式错误导致配置失败；
  1. 权限管控精细化是保障：企业需在 Synology SSO 中按 “研发组”“测试组” 细分权限，在 Jenkins 中基于 SAML 同步的用户组分配构建权限，避免未授权人员访问核心 CI/CD 资源。
若配置中遇到未覆盖的问题（如跨域 SAML 登录、Jenkins 集群 SAML 配置），可登录 Synology 支持中心（https://www.synology.com/zh-cn/support）或 Jenkins 官方社区，提交 “Synology SSO Jenkins SAML 配置” 工单，提供元数据文件、错误截图、软件版本信息，官方技术人员会在 1-2 个工作日内提供针对性解决方案，确保研发团队的 Jenkins 单点登录稳定运行。
Synology SSO Server 配置 Jenkins SAML 单点登录教程：分步操作 + 常见问题

新闻中心

联系我们

技术支持

  • ·

    Synology 无法访问共享文...

  • ·

    Synology NAS Win...

  • ·

    如何用 DiXiM Media ...

  • ·

    Synology DSM常规设置...

  • ·

    Active Backup fo...

  • ·

    Synology NAS打开Of...

  • ·

    Synology Migrati...

  • ·

    Synology Office多...

相关文章

地址：北京市海淀区白家疃尚品园             1号楼225

北京群晖时代科技有限公司

联系群晖
微信咨询