Synology SSO Server为GitLab设置SAML教程：SSO登录配置全流程（DSM 7.x适配）

在企业或团队使用Synology NAS与GitLab进行代码管理时，频繁切换账户登录（DSM账户、GitLab账户）不仅降低效率，还增加密码泄露风险。通过Synology SSO Server为GitLab配置SAML单点登录（SSO），可实现“一次登录DSM SSO，即可无缝访问GitLab”，既简化操作流程，又通过集中身份管理提升安全性。但多数用户因不熟悉SAML协议（IdP/SP角色）、Synology SSO属性映射规则，或GitLab SAML配置细节，导致出现“登录无响应”“用户信息同步失败”等问题。本文基于Synology官方技术文档，从“前提准备→IdP配置（SSO Server）→SP配置（GitLab）→测试验证→故障解决”五大维度，手把手完成GitLab与Synology SSO的SAML集成，覆盖DSM 7.x全版本，兼顾自建GitLab与Synology GitLab套件场景。

一、前提准备：4大核心条件，奠定SAML集成基础

SAML SSO配置对环境、权限、证书有严格要求，80%的故障源于基础条件不满足，需优先核查，确保后续步骤无卡点。

1. 环境与版本适配（必须达标，否则功能缺失）

| 组件                | 版本要求                          | 说明                                  |

|---------------------|-----------------------------------|---------------------------------------|

| Synology DSM        | DSM 7.0及以上版本                 | 旧版本（如DSM 6.2）SSO Server无完整SAML功能，需升级 |

| Synology SSO Server | 2.0.0及以上版本                   | 从“套件中心→所有套件”搜索安装，确保为最新版 |

| GitLab              | 13.0及以上版本（自建/套件均支持） | Synology GitLab套件（1.2.0+）或自建GitLab社区版/企业版 |

| 网络环境            | 同一局域网或可互通（SSO与GitLab） | 外部访问需配置端口转发，确保元数据可正常传输 |

- 版本检查方法： 

- DSM版本：登录DSM→点击右上角“问号”→“关于DSM”； 

- SSO Server版本：套件中心→“已安装”→找到“SSO Server”查看版本； 

- GitLab版本：自建GitLab登录后→“Admin Area→Overview→About”，或Synology GitLab套件→“套件中心→已安装”查看。

2. 权限准备：需管理员账户（2类关键权限）

| 操作对象                | 所需权限                          | 获取方式                                  |

|-------------------------|-----------------------------------|-------------------------------------------|

| Synology SSO Server     | DSM超级管理员权限（如admin账户）  | 由NAS管理员分配，需具备“套件管理”“用户管理”权限 |

| GitLab                  | GitLab Admin（管理员账户）        | 自建GitLab默认“root”账户，Synology GitLab套件首次登录账户为DSM管理员 |

3. 证书准备：确保SAML通信加密（推荐CA证书）

SAML协议依赖证书验证身份，避免数据被篡改，需提前准备：

- 推荐方案：使用第三方CA签发的SSL证书（如Let’s Encrypt），需与Synology SSO Server的访问域名绑定（如“sso.yournas.com”）； 

- 临时方案：使用Synology自签名证书（仅用于测试，生产环境不推荐），需在GitLab服务器信任该证书； 

- 证书获取路径： 

1. CA证书：DSM→“控制面板→安全→证书→新增→从Let’s Encrypt获取证书”； 

2. 自签名证书：同上路径，选择“创建自签名证书”。

4. 元数据提前了解（SAML集成核心）

SAML集成需交换“身份提供商（IdP）元数据”与“服务提供商（SP）元数据”：

- IdP元数据：由Synology SSO Server生成，包含IdP地址、证书、属性映射规则，需导入GitLab； 

- SP元数据：由GitLab生成，包含GitLab的SAML回调地址、实体ID，需导入Synology SSO Server（或手动配置）； 

- 核心作用：替代手动输入大量参数，减少配置错误，确保双方通信协议一致。

二、核心步骤一：Synology SSO Server配置SAML身份提供商（IdP）

这是SAML集成的“身份源头”配置，需完成IdP创建、属性映射、元数据导出，确保GitLab能识别Synology SSO的用户身份。

步骤1：安装并打开SSO Server套件

1. 登录Synology DSM→打开“套件中心”→在“所有套件”搜索框输入“SSO Server”； 

2. 点击“安装”，等待1-2分钟安装完成（需确保NAS联网，下载套件安装包）； 

3. 安装完成后，在DSM桌面找到“SSO Server”图标，双击打开套件。

步骤2：创建SAML身份提供商（IdP）

1. 在SSO Server左侧导航栏，点击“身份提供商（IdP） ”→“创建IdP”； 

2. 配置IdP基础信息（关键参数，错误会导致后续集成失败）： 

- IdP名称：自定义（如“GitLab-SSO-IdP”，便于识别）； 

- 协议版本：默认选择“SAML 2.0”（GitLab仅支持SAML 2.0）； 

- 证书：从下拉菜单选择提前准备的SSL证书（CA证书或自签名证书）； 

- 默认语言：选择“中文（简体）”或“English”，不影响功能； 

3. 点击“下一步”，进入“属性映射”配置（核心！确保GitLab能获取用户关键信息）。

步骤3：配置SAML属性映射（GitLab必填字段）

GitLab需通过SAML获取“用户名、邮箱、姓名”等字段，需在SSO Server中映射Synology用户属性：

1. 在“属性映射”页面，点击“新增”，按以下表格添加3个必填属性：

| GitLab所需属性（SP属性） | Synology SSO Server对应属性（IdP属性） | 配置说明                                  |

|--------------------------|---------------------------------------|-------------------------------------------|

| NameID                   | mail（用户邮箱）或uid（DSM用户名）     | 唯一标识用户，推荐用“mail”（避免用户名重复） |

| email                    | mail                                  | GitLab用户登录后绑定的邮箱，需与DSM用户邮箱一致 |

| username                 | uid                                   | GitLab显示的用户名，对应DSM登录名          |

| name（可选）             | displayName                           | 用户全名，显示在GitLab个人资料中          |

2. 添加示例（以“email”属性为例）： 

- 点击“新增”→“SP属性名”输入“email”→“IdP属性名”选择“mail”→“默认值”留空→点击“确定”； 

3. 所有属性添加完成后，点击“下一步”→“完成”，IdP创建成功。

步骤4：导出IdP元数据（后续导入GitLab）

1. 在“身份提供商（IdP）”列表中，找到刚创建的“GitLab-SSO-IdP”，点击右侧“操作”→“导出元数据”； 

2. 选择“XML格式”（GitLab仅支持XML元数据），点击“下载”，将元数据文件（如“idp-metadata.xml”）保存到本地电脑； 

- 关键提示：元数据包含IdP地址、证书信息，请勿泄露给未授权人员。

三、核心步骤二：GitLab配置SAML服务提供商（SP）

这是SAML集成的“服务接收”配置，需导入Synology IdP元数据、设置回调地址、启用SSO登录，确保GitLab能对接Synology SSO的身份验证。

场景1：自建GitLab（社区版/企业版）配置

1. 登录GitLab管理员账户： 

打开GitLab网页端，使用“root”或具备Admin权限的账户登录，进入“Admin Area”（右上角齿轮图标）。

2. 进入SAML SSO配置页面： 

在Admin Area左侧导航栏，点击“Settings”→“General”→下拉至“Single Sign-On (SAML) ”模块，点击“Expand”展开配置项。

3. 导入Synology IdP元数据： 

- 勾选“Enable SAML authentication”（启用SAML认证）； 

- 点击“Import IdP metadata”→“Choose file”，选择本地保存的“idp-metadata.xml”→点击“Upload file”； 

- 系统会自动填充“IdP entity ID”“IdP SSO URL”“IdP certificate”三个关键参数（无需手动输入，避免错误）。

4. 配置GitLab SP关键参数： 

- Issuer：输入GitLab的实体ID（自定义，需唯一，如“https://gitlab.yourdomain.com”）； 

- Callback URL：输入GitLab的SAML回调地址（固定格式，如“https://gitlab.yourdomain.com/users/auth/saml/callback”）； 

- Name identifier format：选择“emailAddress”（与Synology IdP的NameID属性“mail”对应）； 

- Attribute statement configuration：按以下配置映射用户属性（与SSO Server属性对应）： 

- Email：输入“email”（对应SSO Server的“mail”属性）； 

- Username：输入“username”（对应SSO Server的“uid”属性）； 

- Name（可选）：输入“name”（对应SSO Server的“displayName”属性）。

5. 保存配置： 

下拉页面至底部，点击“Save changes”，GitLab SAML配置生效。

场景2：Synology GitLab套件配置（DSM内置GitLab）

1. 打开Synology GitLab套件： 

登录DSM→“套件中心→已安装”→找到“GitLab”→点击“打开”，进入GitLab网页端。

2. 进入SAML配置页面： 

使用DSM管理员账户登录GitLab→点击右上角“管理员”→“设置”→“通用”→“单点登录 (SAML) ”→“展开”。

3. 配置与自建GitLab一致： 

步骤与“场景1”的3-5步完全相同（导入IdP元数据、配置回调地址、属性映射），唯一差异： 

- Callback URL格式为“https://NAS域名/gitlab/users/auth/saml/callback”（如“https://mynas.synology.me/gitlab/users/auth/saml/callback”）。

四、步骤三：测试SAML SSO登录（验证集成是否成功）

配置完成后必须测试登录流程，避免用户实际使用时出现故障，测试需分“管理员测试”“普通用户测试”两步。

1. 管理员测试（优先验证配置正确性）

1. 退出当前GitLab登录状态，返回GitLab登录页面； 

2. 此时页面会新增“Sign in with SAML”按钮（SAML登录入口），点击该按钮； 

3. 自动跳转至Synology SSO Server登录页面，输入DSM管理员账户（如admin）和密码； 

4. 登录成功后，自动跳转回GitLab，若能正常进入GitLab首页，且右上角显示DSM用户名/邮箱，说明管理员登录测试通过。

2. 普通用户测试（验证权限同步）

1. 在Synology DSM中创建1个普通用户（如“dev-user1”），并分配“GitLab使用权限”（控制面板→用户与群组→编辑用户→应用权限→GitLab→勾选“使用”）； 

2. 退出GitLab管理员账户，使用“dev-user1”通过“SAML登录”（步骤同管理员测试）； 

3. 登录后检查： 

- 能否正常访问GitLab项目（如查看自己有权限的代码仓库）； 

- 进入“个人资料→编辑个人资料”，确认“邮箱”“用户名”与DSM用户信息一致。

五、常见问题解答：解决SAML集成的5类高频故障

1. Q：GitLab点击“SAML登录”后，跳转至SSO Server提示“无效的请求”，怎么办？

A：多为GitLab回调地址错误或IdP元数据过期，解决步骤： 

1. 检查GitLab的“Callback URL”：确保与SSO Server中IdP允许的回调地址一致（Synology SSO默认允许所有回调，若手动限制，需在IdP“设置→允许的回调URL”中添加GitLab回调地址）； 

2. 重新导出Synology IdP元数据，在GitLab中重新导入（元数据可能因证书更新失效）； 

3. 清除浏览器缓存（按“Ctrl+Shift+Del”），重新尝试登录。

2. Q：SSO登录成功，但GitLab提示“无法获取用户邮箱”，原因是什么？

A：属性映射错误，未正确传递“email”属性，解决方法： 

1. 进入Synology SSO Server→“身份提供商（IdP）”→编辑目标IdP→“属性映射”； 

2. 确认已添加“SP属性名=email，IdP属性名=mail”的映射（检查拼写，区分大小写，“Email”与“email”不同）； 

3. 进入GitLab SAML配置，确认“Email”字段填写“email”（与SSO属性名完全一致），保存后重新测试。

3. Q：自建GitLab导入IdP元数据时，提示“证书无效”，如何处理？

A：GitLab不信任Synology SSO的证书，解决步骤： 

1. 若使用自签名证书：在GitLab服务器上安装该证书（以Linux为例，将证书复制到“/etc/gitlab/trusted-certs/”，执行“gitlab-ctl reconfigure”重启GitLab）； 

2. 若使用CA证书：确认证书未过期，且“IdP certificate”字段已正确填充（导入元数据后自动填充，若为空，手动复制证书内容，去除“-----BEGIN CERTIFICATE-----”和“-----END CERTIFICATE-----”外的空格）。

4. Q：普通用户SAML登录后，GitLab提示“无访问权限”，怎么办？

A：DSM用户未获取GitLab使用权限，解决步骤： 

1. 登录Synology DSM→“控制面板→用户与群组”→选中普通用户→点击“编辑”； 

2. 切换至“应用权限”标签页→找到“GitLab”→勾选“使用”权限（若需管理权限，勾选“管理”）； 

3. 保存后，用户重新SAML登录GitLab，即可正常访问。

5. Q：Synology SSO Server中找不到“身份提供商（IdP）”选项，是版本问题吗？

A：是的，SSO Server版本过低，解决方法： 

1. 进入DSM“套件中心→已安装”→找到“SSO Server”→点击“更新”，升级至2.0.0及以上版本； 

2. 若无法更新（提示“已是最新版”），先卸载SSO Server，再重新从套件中心安装（卸载前无需备份，IdP配置会保留）； 

3. 重新打开SSO Server，左侧导航栏会显示“身份提供商（IdP）”选项。

六、总结与维护建议：确保SAML SSO长期稳定

Synology SSO Server为GitLab配置SAML的核心是“IdP与SP元数据同步+属性映射精准”——IdP配置需确保用户关键属性（邮箱、用户名）正确映射，SP配置需保证回调地址、证书无误，测试环节需覆盖管理员与普通用户，避免权限遗漏。

后续维护要点：

1. 证书定期更新：CA证书过期前1个月，在Synology SSO Server中更新证书，并重新导出元数据导入GitLab； 

2. 属性变更同步：若DSM用户属性（如邮箱）修改，需在SSO Server IdP的“属性映射”中确认字段未变，避免同步失败； 

3. 日志排查：登录失败时，查看Synology SSO Server日志（“SSO Server→日志→身份验证日志”）和GitLab日志（“Admin Area→Monitoring→Logs”），定位错误原因。

若您在操作中遇到“Synology GitLab套件版本不支持SAML”“外部GitLab无法访问Synology SSO”等问题，可参考Synology官方文档（https://kb.synology.cn/zh-cn/DSM/tutorial/set_up_saml_for_gitlab_in_sso_server）获取型号适配细节，或告诉我您的GitLab类型（自建/套件）与DSM版本，我帮您定制解决方案。

需要我为您整理一份Synology SSO-GitLab SAML配置checklist吗？包含前提确认清单、IdP/SP配置要点、属性映射表及故障排查步骤，方便您实操时逐点核对，避免遗漏关键环节。