最近有个同学在群里问团队内部部署了一套 GitPuk 做代码托管又上了一套 soular 做身份认证两边账号各管各的新同事入职得在两个系统里分别建号离职又要分别注销有没有办法把登录统一起来我当时的回答是别自己造轮子直接用 OIDC 把 GitPuk 接到 soular 上一劳永逸。这篇文章就是我实操之后的完整记录涵盖设计思路、核心原理、配置步骤和踩坑实录。无论你是运维、研发还是刚接触统一登录的小白只要手上有 GitPuk 和 soular 这两套系统照着我这个流程走基本能在一个小时内完成对接。内容偏实战我会把所有关键参数解释清楚尽量做到“看完就能用”。1. 为什么要把 GitPuk 接入 soular——统一登入到底解决了什么问题先别急着改配置想清楚“为什么做”比“怎么做”更重要。只有理解了背后的账后续调参和排错你才能心里有数。1.1 先看 GitPuk 和 soular 是干什么的GitPuk 本质上是一个轻量级的 Git 代码托管平台和 GitHub、GitLab、Gitea 这类产品属于同一品类核心功能包括仓库管理、分支保护、Merge Request、Issue 跟踪等。它胜在部署简单、资源占用低很多中小团队会用它搭建内部的代码托管环境。soular 则是一个统一身份认证服务扮演的是“账号中心”的角色。它支持标准的 OIDCOpenID Connect和 OAuth2.0 协议可以把所有内部系统的登录认证收拢到一个地方。你可以用 soular 管理员工账号、密码策略、多因素认证MFA、会话有效期等然后让 GitPuk、Jenkins、Wiki 等各类系统都“信任”soular 签发的身份凭证。简单说GitPuk 是业务系统负责“干活”soular 是认证中心负责“验明正身”。1.2 不统一的痛点账号、密码、权限、审计没有统一登录之前我最直观的体会有四点。第一是账号管理成本高。假设团队有 30 人公司内部有 5 套系统每套系统都要单独维护一套账号人员入职时要逐个创建离职时要逐个禁用或删除。运维时间都浪费在这种重复劳动上了而且很容易漏掉某个系统的账号形成僵尸账号。第二是密码策略不一致。有的系统要求 8 位密码有的要求 12 位且必须包含特殊字符有的还允许使用弱密码。员工为了省事经常在多个系统里用同一套密码一旦某个系统被拖库其他系统也跟着遭殃。第三是权限模型割裂。代码仓库的权限虽然在 GitPuk 内部可以控制但如果 HR 系统里员工已经转了岗你还需要手动去 GitPuk 里同步调整权限组操作繁琐且容易出错。第四是审计困难。出了安全事故要追溯操作记录时你得在多个系统的日志里来回翻因为每个系统都有自己独立的账号体系很难把同一用户在多个系统的行为串联起来。把 GitPuk 接入 soular 之后账号统一归 soular 管GitPuk 不再维护自己的密码只认 soular 签发的身份令牌。新同事在 soular 里开通一次账号就能直接登录 GitPuk离职时也只需要在 soular 里禁用账号所有关联系统自动全部失效。1.3 用 OIDC 而不是自建账号体系的理由可能有人会问GitPuk 自己不是也有账号注册功能吗直接在 GitPuk 上创建几个账号不就行了这话没毛病但如果团队规模超过十几人、或者系统数量超过两三个的时候本地账号体系的弊端就会暴露。最大的问题在于“身份事实来源”不统一。GitPuk 自己建账号账号信息就存在 GitPuk 里它无法获知这个人在组织里是否已经离职、是否已经换部门。而 soular 作为独立的身份认证服务可以和 HR 系统、飞书/钉钉通讯录等做联动一个人离职后soular 里的账号状态会很快变更GitPuk 通过 OIDC 协议在登录时实时校验状态可以立刻阻止无效账号访问。另一个选择的理由是标准协议带来的通用性。OIDC 是互联网广泛使用的身份认证标准几乎所有的现代化应用都支持接入 OIDC Provider。你今天花半天时间把 GitPuk 接入 soular明天要用 GitLab 或者 Jenkins只需重复同样的流程边际成本非常低。2. 集成前必须搞懂的 OIDC 核心概念集成过程中你会看到一堆术语比如 Client ID、Client Secret、Redirect URI、Issuer、Scope 等。刚开始接触这些概念时觉得抽象其实用一个生活类比就能完全理解。拿“住酒店”来打比方。soular 是酒店前台认证中心GitPuk 是酒店的健身房业务系统。你进健身房时不需要在健身房重新登记身份只需要出示前台发放的房卡身份令牌。房卡上有你的姓名、房号、入住日期健身房检查一下房卡有效就允许你进入。这里的“房卡”就是 OIDC 里的 ID Token“健身房”信任“前台”发放的房卡这就是“统一认证”的本质。2.1 授权码模式的完整流程GitPuk 接入 soular 时推荐使用 OIDC 的授权码模式Authorization Code Flow这是目前安全性最高的 Web 应用认证模式核心流程一共七步第一步是用户访问 GitPukGitPuk 发现用户未登录就重定向到 soular 的授权接口URL 中带有 client_id、redirect_uri、response_typecode、scopeopenid profile email 等参数。第二步是用户在 soular 的登录页输入账号密码。这一步只发生在 soular 上GitPuk 完全不接触用户的密码。第三步是 soular 验证账号成功后浏览器带着一个授权码authorization code跳转回 GitPuk 指定的回调地址。第四步是 GitPuk 拿着这个授权码直接向 soular 的令牌接口发起请求同时带上自己的 client_id 和 client_secret用于证明自己是合法的客户端。第五步是 soular 校验授权码有效后向 GitPuk 返回 Access Token 和 ID Token。ID Token 中包含用户的基础信息比如用户名、邮箱、唯一标识。第六步是 GitPuk 解析 ID Token取出用户信息在本地创建或匹配对应的用户记录。第七步是 GitPuk 给用户创建本地会话后续请求不再需要跟 soular 交互。理解这个流程之后你会发现一个关键点GitPuk 永远拿不到用户的密码用户也永远不需要向 GitPuk 提交密码。这从机制上消除了 GitPuk 侧密码泄露的风险。2.2 几个关键术语说明配置过程中不可避免要填一堆参数这里把我的理解写清楚Issuersoular 的标识符通常是一个 URL例如https://sso.example.com/realms/master。它表示“我是谁我从哪里签发令牌”。GitPuk 拿到这个地址后会自动找到 soular 的元数据文档。Client IDGitPuk 在 soular 中注册后生成的唯一标识相当于 GitPuk 的“身份证号”。这个值可以在配置中明文出现不是机密信息。Client SecretGitPuk 在 soular 中注册后生成的密钥相当于 GitPuk 的“密码”。这个值必须保密如果泄露任何人都可以冒充 GitPuk 来换取用户令牌。Redirect URI授权完成后 soular 把用户送回 GitPuk 的回调地址。这个地址必须在 soular 中预先登记否则 soular 会拒绝跳转。这是防止开放重定向攻击的关键配置。Scope请求的权限范围。openid是必选项表示这是一个 OIDC 认证请求profile表示请求返回用户的基本资料email表示请求返回用户的邮箱地址。还有一个需要理解的隐藏机制是 Discovery 文档。soular 通常会在Issuer对应的路径下暴露一个/well-known/openid-configuration接口里面列出授权端点、令牌端点、用户信息端点、公钥信息等。GitPuk 配置好 Issuer 后会自动去拉取这份文档这也是为什么很多配置项你只需要填一个 Issuer 就够了。2.3 Token 与用户的映射关系OIDC 登录成功之后GitPuk 拿到的 ID Token 是一个 JWT 字符串解析之后能看到类似下面的结构{ sub: a1b2c3d4-1234-5678-abcd-123456789abc, preferred_username: zhangsan, email: zhangsanexample.com, email_verified: true, name: 张三, iss: https://sso.example.com/realms/master, aud: gitpuk, exp: 1714372800, iat: 1714369200 }这里最关键的是sub字段。sub是用户在 soular 体系内的唯一标识同一个用户在 soular 中永远对应同一个sub不会因为改昵称、改邮箱而改变。GitPuk 内部应该用sub来匹配用户而不是用邮箱或者用户名。为什么强调这点我见过有人用邮箱做匹配结果用户在 soular 里改了邮箱之后GitPuk 就认为这是一个新用户历史提交记录全部“丢”了——其实记录都还在只是关联不到人头上了非常尴尬。3. 实操从零把 GitPuk 接到 soular前面聊了这么多原理现在正式进入实操阶段。下面所有步骤都是我基于常见部署环境整理出来的如果你用的版本比较新菜单位置可能略有不同但核心参数是一致的。3.1 在 soular 中创建客户端应用先从 soular 管理后台开始。登录 soular 的管理界面找到“客户端”或“Clients”菜单点击创建新客户端。这里需要关注三个配置项。第一个是客户端协议选择openid-connect。有的版本可能写作OIDC意思一样。第二个是客户端 ID建议取名gitpuk方便以后识别。有些环境下客户端 ID 和 Client ID 是同一个概念soular 会直接把它作为后续配置中的 Client ID 使用。第三个是回调地址这个非常关键。你需要提前确认 GitPuk 配置的对外访问地址。假设 GitPuk 的地址是https://git.example.com那么回调地址通常填写https://git.example.com/auth/soular/callback。注意不同版本的 GitPuk 回调路径可能不同大部分情况下你可以在 GitPuk 的文档中找到“External redirect URI”之类的说明。如果填错了登录时会报 redirect_uri_mismatch 错误。创建完客户端之后soular 会生成 Client Secret立刻复制保存。这个密钥只在创建时显示一次很多版本关闭弹窗之后就再也看不到了重新生成比较麻烦。我吃过亏必须提醒你。接下来配置客户端的作用域Client Scopes。默认情况下 soular 会给客户端分配openid、profile、email三个 scope一般不用动。但有些团队希望登录后 GitPuk 能拿到用户所在的部门、岗位等信息就需要专门创建自定义 scope 或者 mapper。这个属于高级配置先不必纠结。3.2 在 GitPuk 中配置 OIDC Provider回到 GitPuk 管理后台找到“系统设置”或“管理面板”中的“认证”相关配置。如果 GitPuk 支持混用多套登录方式建议保留本地账号登录作为备用同时开启 OIDC。关键配置项如下表格所示配置项填写内容说明启用 OIDC勾选开启关闭状态代表本地登录Provider Namesoular显示在登录页上的按钮名称Issuer URLhttps://sso.example.com/realms/mastersoular 的 realm 地址Client IDgitpuk与 soular 中创建的一致Client Secret之前复制的那串密钥建议使用环境变量注入不要写死在配置文件Redirect URIhttps://git.example.com/auth/soular/callback必须和 soular 中登记的一致授权类型authorization_code授权码模式Scopeopenid profile email保持默认即可有些 GitPuk 版本还提供自动发现配置你只需要填 Issuer URL、Client ID、Client Secret 三项它会自动从 soular 的 Discovery 文档里读取其他配置。如果启动之后日志里出现failed to fetch oidc configuration多半是 Issuer URL 填错了或者网络不通。保存配置之后最好先做一次连通性自检。很多 GitPuk 管理后台提供“测试连接”按钮点击后它会尝试请求 soular 的 Discovery 文档、验证 Client 配置是否合法。这一步能帮你提前排除一半以上的低级错误。3.3 用户映射与权限同步配置好连接之后接下来要考虑的是soular 里的用户登录 GitPuk 之后GitPuk 怎么知道这个用户是谁、让他成为普通用户还是管理员GitPuk 通常支持两种用户映射策略。第一种是自动创建用户首次登录的新用户GitPuk 自动根据 ID Token 里的信息在本地建一个账号然后赋予默认角色。第二种是仅限已有用户GitPuk 不自动建号只有管理员提前在 GitPuk 中创建好的用户才能登录成功新用户会被拒绝。我建议在刚开始集成时使用“自动创建用户 默认普通角色”等跑通之后再视情况收紧。因为如果你设置为“仅限已有用户”第一个来测试的人必须先在 GitPuk 里手动建号流程上很别扭排错也不方便。权限同步方面GitPuk 和 soular 的权限模型并不完全一致。soular 管理的是身份和认证GitPuk 管理的是代码库级别的权限比如谁能推送、谁能合并、谁是仓库 Owner。两者之间通常通过用户的唯一标识形成对应关系而不会把角色自动同步到 GitPuk。也就是说soular 只负责“你是谁”GitPuk 自己负责“你能做什么”。这个设计其实是对的。把认证和授权分开职责清晰后续你换掉任何一个系统都不会影响另一个的权限配置。3.4 用管理员账号完成首次登录验证配置全部完成后打开一个无痕浏览器窗口访问 GitPuk 的登录页应该能看到一个新的登录按钮上面写着 soular。点击之后会被重定向到 soular 的登录页输入你在 soular 中已有的账号密码登录成功后会跳回 GitPuk然后 GitPuk 自动完成用户创建与会话建立整个过程大约两秒钟。首次验证时建议重点检查三件事一是确认跳转成功后浏览器地址栏的 URL 是 GitPuk 的地址而不是停留在 soular 的地址上。如果停留在 soular 或弹出一个“无法打开页面”的提示先看回调地址是否一致。二是确认 ID Token 里解析出来的用户名、邮箱都是正确的。可以到 GitPuk 的“用户管理”里查看新创建的用户记录核对基本信息。三是确认重启后配置仍然生效。有些低版本 GitPuk 的 OIDC 配置是缓存的改配置需要重启服务才能生效这一点要特别留意否则你会觉得“配置明明改了却不生效”白折腾半天。4. 踩坑实录与排查指南集成过程中我遇到过的坑不算少每次踩完都觉得“如果早点知道这个就好了”。下面把这些经验按问题类别整理出来直接对标到排查步骤可以少走弯路。4.1 回调地址不一致导致登录后白屏这是出现频率最高的问题没有之一。表现是点击登录 - 跳转到 soular 登录页 - 输入账号密码 - 页面跳回 GitPuk 但直接白屏或者提示 redirect_uri_mismatch。原因是 soular 中登记的 Redirect URI 与 GitPuk 实际使用的回调地址不一致。有三级可能导致不一致soular 里的地址多了或少了反斜杠、大小写不同GitPuk 的对外访问域名有内网和外网两个你配置的是内网域名但从外网访问时重定向地址是外网域名GitPuk 配置了 HTTPS 强制跳转导致回调 URL 的协议从 http 变成 https。排查思路很简单打开浏览器开发者工具找到发起登录的请求把授权 URL 中的 redirect_uri 参数值复制出来跟 soular 里登记的地址逐字符对比。记住是逐字符——不要小看尾部 / 和大小写的问题。4.2 Token 过期导致频繁掉线GitPuk 接入 soular 之后用户的会话由 souldar 签发的 Token 维护。soular 默认的 Access Token 有效期通常比较短比如 5 到 10 分钟而 Refresh Token 有效期可能是 30 分钟或者更长。如果 GitPuk 没有正确刷新令牌用户过几分钟就要重新登录一次体验非常糟糕。我的建议是分两方面排查。一方面在 soular 里调长 Access Token 的有效期比如设置为 15 分钟Refresh Token 设置为 8 到 12 小时长期不活跃的用户才需要重新登录。另一方面确认 GitPuk 的 OIDC 配置中启用了刷新令牌refresh_token骨架配置里有一个“启用 Token 刷新”的开关默认可能是关闭的打开即可。另外要提醒一个小细节Token 刷新依赖 Client Secret如果你改了 GitPuk 里的 Client Secret但 soular 里还是旧的刷新时会报 unauthorized_client用户表现为登录后一段时间突然掉线重新登录又好了反复循环。遇到这种情形先去检查两边密钥是否一致。4.3 用户在灵魂出窍——登出不同步的问题这是一个容易被忽略的场景用户点击 GitPuk 的退出按钮GitPuk 本地会话清掉了但 soular 里的会话还活着。用户再次访问 GitPuk 时由于 soular 还有有效会话会直接静默登录回来用户根本感知不到自己已经“退出”过了。OIDC 协议中对于登出同步有两种常见方案Front-Channel Logout前端通道登出和 Back-Channel Logout后端通道登出。soular 基于 OIDC 实现时退出请求会把用户重定向到end_session_endpoint并带上post_logout_redirect_uri参数表示退出后回到哪里。实际操作时需要确认三个条件GitPuk 是否支持配置登出重定向地址soular 里的客户端是否开启了“前端登出”功能跳转时是否携带了 ID Token 的 ID 作为参数。只要有一个条件不满足就会出现上面那种“假退出”现象。如果你测试发现很难做到完全同步变通方案是把 GitPuk 的会话时间调短一些让它在用户离开后尽快过期至少减少安全窗口。4.4 用户首次登录后没有权限最后一个常见问题用户通过 soular 登录 GitPuk 成功了但看不到任何项目或者无法创建仓库看起来像“什么都没发生”。这种情况几乎总是本地权限设置的问题。soular 只负责认证它不管用户在 GitPuk 内的角色。自动创建的用户默认只是“普通成员”如果你希望特定用户拥有管理员权限需要到 GitPuk 用户管理里手动提升角色。如果你的团队要求比较高希望根据 soular 里的部门或职位自动分配 GitPuk 角色可以考虑使用 soular 的自定义属性claim在 ID Token 中携带角色信息再通过 GitPuk 的映射规则把角色同步过来。这个方案会复杂一些但一旦跑通日常维护成本很低。一个小建议首次集成时不要追求完美先把“能用”跑通角色映射作为二期优化。因为角色映射涉及两边数据模型对齐牵扯面广不是半小时能搞定的事。先跑通认证再逐步完善授权推进起来会平滑很多。5. 上线后的运维建议与经验总结集成完成只是开始日常运维中还有不少细节值得关注。这节是我最后想补充的经验之谈核心原则是把身份认证交给 soular把精力聚焦在 GitPuk 本身的业务上。第一关于密钥管理。Client Secret 不要明文写在 GitPuk 的配置文件里至少用环境变量或者密钥管理服务比如 Vault、KMS来存放。如果配置信息泄露攻击者可以拿着 Client ID 和 Secret 在 soular 上注册自己的回调地址进而配合浏览器端拿到用户的授权码风险不小。第二关于加密证书。如果 soular 部署在用户网络较复杂的区域或者 GitPuk 要从另一台服务器回调 soular建议确认两边的 HTTPS 证书都是受信任的证书而不是内网自签名证书。GitPuk 在拉取 soular 的 Discovery 文档时如果证书校验失败通常会直接报错或跳过导致集成看起来完全失效。测试时临时关闭证书校验可以但生产环境一定要处理好证书信任链。第三关于用户目录的同步。soular 的账号源如果能和公司的人力系统打通那么新员工入职自动有账号、离职自动被禁用。如果你的 soular 是纯手工维护账号的建议至少安排一个定期专项任务确保账号状态与人员状态一致。否则统一登录做得再好账号源本身混乱也白搭。第四关于审计日志。集成后用户登录 GitPuk 的记录发生在 soular 中GitPuk 内的操作记录还在 GitPuk 里。做安全审计时需要把两边日志拉通可以根据时间戳和用户唯一标识sub进行关联。建议在配置 GitPuk 的日志级别时调高认证相关日志的详细程度方便日后追溯。第五关于回滚预案。任何一次变更都可能有意外集成 OIDC 也不应该例外。在改动 GitPuk 认证配置之前把原来的配置项完整截图或备份。如果你同时保留了本地账号登录回滚就是切回本地登录而已非常简单。这也是我强烈建议保留本地登录开关的原因——线上出问题的时候它是你的保命符。我个人在实际操作中的体会是统一登录这件事难的不是配置本身而是对 OIDC 协议的理解和对业务场景的判断。你把它当成一次性的“对接任务”来做容易流于表面你把它当成企业内部身份体系的组成部分来设计后面所有的系统接入都会变得顺理成章。最后再分享一个小技巧在完成 GitPuk 接入 soular 之后把这次配置过程中的所有参数、截图、踩坑记录整理成一份内部文档下次接入 Jenkins、Wiki 或者其他系统时直接复用什么思路只需要把客户端 ID 和回调地址替换掉就行。第一次花半天第二次半小时这就是标准协议带来的复利。 GitPuk 接入 soular：用 OIDC 实现统一登录的完整指南
最近有个同学在群里问团队内部部署了一套 GitPuk 做代码托管又上了一套 soular 做身份认证两边账号各管各的新同事入职得在两个系统里分别建号离职又要分别注销有没有办法把登录统一起来我当时的回答是别自己造轮子直接用 OIDC 把 GitPuk 接到 soular 上一劳永逸。这篇文章就是我实操之后的完整记录涵盖设计思路、核心原理、配置步骤和踩坑实录。无论你是运维、研发还是刚接触统一登录的小白只要手上有 GitPuk 和 soular 这两套系统照着我这个流程走基本能在一个小时内完成对接。内容偏实战我会把所有关键参数解释清楚尽量做到“看完就能用”。1. 为什么要把 GitPuk 接入 soular——统一登入到底解决了什么问题先别急着改配置想清楚“为什么做”比“怎么做”更重要。只有理解了背后的账后续调参和排错你才能心里有数。1.1 先看 GitPuk 和 soular 是干什么的GitPuk 本质上是一个轻量级的 Git 代码托管平台和 GitHub、GitLab、Gitea 这类产品属于同一品类核心功能包括仓库管理、分支保护、Merge Request、Issue 跟踪等。它胜在部署简单、资源占用低很多中小团队会用它搭建内部的代码托管环境。soular 则是一个统一身份认证服务扮演的是“账号中心”的角色。它支持标准的 OIDCOpenID Connect和 OAuth2.0 协议可以把所有内部系统的登录认证收拢到一个地方。你可以用 soular 管理员工账号、密码策略、多因素认证MFA、会话有效期等然后让 GitPuk、Jenkins、Wiki 等各类系统都“信任”soular 签发的身份凭证。简单说GitPuk 是业务系统负责“干活”soular 是认证中心负责“验明正身”。1.2 不统一的痛点账号、密码、权限、审计没有统一登录之前我最直观的体会有四点。第一是账号管理成本高。假设团队有 30 人公司内部有 5 套系统每套系统都要单独维护一套账号人员入职时要逐个创建离职时要逐个禁用或删除。运维时间都浪费在这种重复劳动上了而且很容易漏掉某个系统的账号形成僵尸账号。第二是密码策略不一致。有的系统要求 8 位密码有的要求 12 位且必须包含特殊字符有的还允许使用弱密码。员工为了省事经常在多个系统里用同一套密码一旦某个系统被拖库其他系统也跟着遭殃。第三是权限模型割裂。代码仓库的权限虽然在 GitPuk 内部可以控制但如果 HR 系统里员工已经转了岗你还需要手动去 GitPuk 里同步调整权限组操作繁琐且容易出错。第四是审计困难。出了安全事故要追溯操作记录时你得在多个系统的日志里来回翻因为每个系统都有自己独立的账号体系很难把同一用户在多个系统的行为串联起来。把 GitPuk 接入 soular 之后账号统一归 soular 管GitPuk 不再维护自己的密码只认 soular 签发的身份令牌。新同事在 soular 里开通一次账号就能直接登录 GitPuk离职时也只需要在 soular 里禁用账号所有关联系统自动全部失效。1.3 用 OIDC 而不是自建账号体系的理由可能有人会问GitPuk 自己不是也有账号注册功能吗直接在 GitPuk 上创建几个账号不就行了这话没毛病但如果团队规模超过十几人、或者系统数量超过两三个的时候本地账号体系的弊端就会暴露。最大的问题在于“身份事实来源”不统一。GitPuk 自己建账号账号信息就存在 GitPuk 里它无法获知这个人在组织里是否已经离职、是否已经换部门。而 soular 作为独立的身份认证服务可以和 HR 系统、飞书/钉钉通讯录等做联动一个人离职后soular 里的账号状态会很快变更GitPuk 通过 OIDC 协议在登录时实时校验状态可以立刻阻止无效账号访问。另一个选择的理由是标准协议带来的通用性。OIDC 是互联网广泛使用的身份认证标准几乎所有的现代化应用都支持接入 OIDC Provider。你今天花半天时间把 GitPuk 接入 soular明天要用 GitLab 或者 Jenkins只需重复同样的流程边际成本非常低。2. 集成前必须搞懂的 OIDC 核心概念集成过程中你会看到一堆术语比如 Client ID、Client Secret、Redirect URI、Issuer、Scope 等。刚开始接触这些概念时觉得抽象其实用一个生活类比就能完全理解。拿“住酒店”来打比方。soular 是酒店前台认证中心GitPuk 是酒店的健身房业务系统。你进健身房时不需要在健身房重新登记身份只需要出示前台发放的房卡身份令牌。房卡上有你的姓名、房号、入住日期健身房检查一下房卡有效就允许你进入。这里的“房卡”就是 OIDC 里的 ID Token“健身房”信任“前台”发放的房卡这就是“统一认证”的本质。2.1 授权码模式的完整流程GitPuk 接入 soular 时推荐使用 OIDC 的授权码模式Authorization Code Flow这是目前安全性最高的 Web 应用认证模式核心流程一共七步第一步是用户访问 GitPukGitPuk 发现用户未登录就重定向到 soular 的授权接口URL 中带有 client_id、redirect_uri、response_typecode、scopeopenid profile email 等参数。第二步是用户在 soular 的登录页输入账号密码。这一步只发生在 soular 上GitPuk 完全不接触用户的密码。第三步是 soular 验证账号成功后浏览器带着一个授权码authorization code跳转回 GitPuk 指定的回调地址。第四步是 GitPuk 拿着这个授权码直接向 soular 的令牌接口发起请求同时带上自己的 client_id 和 client_secret用于证明自己是合法的客户端。第五步是 soular 校验授权码有效后向 GitPuk 返回 Access Token 和 ID Token。ID Token 中包含用户的基础信息比如用户名、邮箱、唯一标识。第六步是 GitPuk 解析 ID Token取出用户信息在本地创建或匹配对应的用户记录。第七步是 GitPuk 给用户创建本地会话后续请求不再需要跟 soular 交互。理解这个流程之后你会发现一个关键点GitPuk 永远拿不到用户的密码用户也永远不需要向 GitPuk 提交密码。这从机制上消除了 GitPuk 侧密码泄露的风险。2.2 几个关键术语说明配置过程中不可避免要填一堆参数这里把我的理解写清楚Issuersoular 的标识符通常是一个 URL例如https://sso.example.com/realms/master。它表示“我是谁我从哪里签发令牌”。GitPuk 拿到这个地址后会自动找到 soular 的元数据文档。Client IDGitPuk 在 soular 中注册后生成的唯一标识相当于 GitPuk 的“身份证号”。这个值可以在配置中明文出现不是机密信息。Client SecretGitPuk 在 soular 中注册后生成的密钥相当于 GitPuk 的“密码”。这个值必须保密如果泄露任何人都可以冒充 GitPuk 来换取用户令牌。Redirect URI授权完成后 soular 把用户送回 GitPuk 的回调地址。这个地址必须在 soular 中预先登记否则 soular 会拒绝跳转。这是防止开放重定向攻击的关键配置。Scope请求的权限范围。openid是必选项表示这是一个 OIDC 认证请求profile表示请求返回用户的基本资料email表示请求返回用户的邮箱地址。还有一个需要理解的隐藏机制是 Discovery 文档。soular 通常会在Issuer对应的路径下暴露一个/well-known/openid-configuration接口里面列出授权端点、令牌端点、用户信息端点、公钥信息等。GitPuk 配置好 Issuer 后会自动去拉取这份文档这也是为什么很多配置项你只需要填一个 Issuer 就够了。2.3 Token 与用户的映射关系OIDC 登录成功之后GitPuk 拿到的 ID Token 是一个 JWT 字符串解析之后能看到类似下面的结构{ sub: a1b2c3d4-1234-5678-abcd-123456789abc, preferred_username: zhangsan, email: zhangsanexample.com, email_verified: true, name: 张三, iss: https://sso.example.com/realms/master, aud: gitpuk, exp: 1714372800, iat: 1714369200 }这里最关键的是sub字段。sub是用户在 soular 体系内的唯一标识同一个用户在 soular 中永远对应同一个sub不会因为改昵称、改邮箱而改变。GitPuk 内部应该用sub来匹配用户而不是用邮箱或者用户名。为什么强调这点我见过有人用邮箱做匹配结果用户在 soular 里改了邮箱之后GitPuk 就认为这是一个新用户历史提交记录全部“丢”了——其实记录都还在只是关联不到人头上了非常尴尬。3. 实操从零把 GitPuk 接到 soular前面聊了这么多原理现在正式进入实操阶段。下面所有步骤都是我基于常见部署环境整理出来的如果你用的版本比较新菜单位置可能略有不同但核心参数是一致的。3.1 在 soular 中创建客户端应用先从 soular 管理后台开始。登录 soular 的管理界面找到“客户端”或“Clients”菜单点击创建新客户端。这里需要关注三个配置项。第一个是客户端协议选择openid-connect。有的版本可能写作OIDC意思一样。第二个是客户端 ID建议取名gitpuk方便以后识别。有些环境下客户端 ID 和 Client ID 是同一个概念soular 会直接把它作为后续配置中的 Client ID 使用。第三个是回调地址这个非常关键。你需要提前确认 GitPuk 配置的对外访问地址。假设 GitPuk 的地址是https://git.example.com那么回调地址通常填写https://git.example.com/auth/soular/callback。注意不同版本的 GitPuk 回调路径可能不同大部分情况下你可以在 GitPuk 的文档中找到“External redirect URI”之类的说明。如果填错了登录时会报 redirect_uri_mismatch 错误。创建完客户端之后soular 会生成 Client Secret立刻复制保存。这个密钥只在创建时显示一次很多版本关闭弹窗之后就再也看不到了重新生成比较麻烦。我吃过亏必须提醒你。接下来配置客户端的作用域Client Scopes。默认情况下 soular 会给客户端分配openid、profile、email三个 scope一般不用动。但有些团队希望登录后 GitPuk 能拿到用户所在的部门、岗位等信息就需要专门创建自定义 scope 或者 mapper。这个属于高级配置先不必纠结。3.2 在 GitPuk 中配置 OIDC Provider回到 GitPuk 管理后台找到“系统设置”或“管理面板”中的“认证”相关配置。如果 GitPuk 支持混用多套登录方式建议保留本地账号登录作为备用同时开启 OIDC。关键配置项如下表格所示配置项填写内容说明启用 OIDC勾选开启关闭状态代表本地登录Provider Namesoular显示在登录页上的按钮名称Issuer URLhttps://sso.example.com/realms/mastersoular 的 realm 地址Client IDgitpuk与 soular 中创建的一致Client Secret之前复制的那串密钥建议使用环境变量注入不要写死在配置文件Redirect URIhttps://git.example.com/auth/soular/callback必须和 soular 中登记的一致授权类型authorization_code授权码模式Scopeopenid profile email保持默认即可有些 GitPuk 版本还提供自动发现配置你只需要填 Issuer URL、Client ID、Client Secret 三项它会自动从 soular 的 Discovery 文档里读取其他配置。如果启动之后日志里出现failed to fetch oidc configuration多半是 Issuer URL 填错了或者网络不通。保存配置之后最好先做一次连通性自检。很多 GitPuk 管理后台提供“测试连接”按钮点击后它会尝试请求 soular 的 Discovery 文档、验证 Client 配置是否合法。这一步能帮你提前排除一半以上的低级错误。3.3 用户映射与权限同步配置好连接之后接下来要考虑的是soular 里的用户登录 GitPuk 之后GitPuk 怎么知道这个用户是谁、让他成为普通用户还是管理员GitPuk 通常支持两种用户映射策略。第一种是自动创建用户首次登录的新用户GitPuk 自动根据 ID Token 里的信息在本地建一个账号然后赋予默认角色。第二种是仅限已有用户GitPuk 不自动建号只有管理员提前在 GitPuk 中创建好的用户才能登录成功新用户会被拒绝。我建议在刚开始集成时使用“自动创建用户 默认普通角色”等跑通之后再视情况收紧。因为如果你设置为“仅限已有用户”第一个来测试的人必须先在 GitPuk 里手动建号流程上很别扭排错也不方便。权限同步方面GitPuk 和 soular 的权限模型并不完全一致。soular 管理的是身份和认证GitPuk 管理的是代码库级别的权限比如谁能推送、谁能合并、谁是仓库 Owner。两者之间通常通过用户的唯一标识形成对应关系而不会把角色自动同步到 GitPuk。也就是说soular 只负责“你是谁”GitPuk 自己负责“你能做什么”。这个设计其实是对的。把认证和授权分开职责清晰后续你换掉任何一个系统都不会影响另一个的权限配置。3.4 用管理员账号完成首次登录验证配置全部完成后打开一个无痕浏览器窗口访问 GitPuk 的登录页应该能看到一个新的登录按钮上面写着 soular。点击之后会被重定向到 soular 的登录页输入你在 soular 中已有的账号密码登录成功后会跳回 GitPuk然后 GitPuk 自动完成用户创建与会话建立整个过程大约两秒钟。首次验证时建议重点检查三件事一是确认跳转成功后浏览器地址栏的 URL 是 GitPuk 的地址而不是停留在 soular 的地址上。如果停留在 soular 或弹出一个“无法打开页面”的提示先看回调地址是否一致。二是确认 ID Token 里解析出来的用户名、邮箱都是正确的。可以到 GitPuk 的“用户管理”里查看新创建的用户记录核对基本信息。三是确认重启后配置仍然生效。有些低版本 GitPuk 的 OIDC 配置是缓存的改配置需要重启服务才能生效这一点要特别留意否则你会觉得“配置明明改了却不生效”白折腾半天。4. 踩坑实录与排查指南集成过程中我遇到过的坑不算少每次踩完都觉得“如果早点知道这个就好了”。下面把这些经验按问题类别整理出来直接对标到排查步骤可以少走弯路。4.1 回调地址不一致导致登录后白屏这是出现频率最高的问题没有之一。表现是点击登录 - 跳转到 soular 登录页 - 输入账号密码 - 页面跳回 GitPuk 但直接白屏或者提示 redirect_uri_mismatch。原因是 soular 中登记的 Redirect URI 与 GitPuk 实际使用的回调地址不一致。有三级可能导致不一致soular 里的地址多了或少了反斜杠、大小写不同GitPuk 的对外访问域名有内网和外网两个你配置的是内网域名但从外网访问时重定向地址是外网域名GitPuk 配置了 HTTPS 强制跳转导致回调 URL 的协议从 http 变成 https。排查思路很简单打开浏览器开发者工具找到发起登录的请求把授权 URL 中的 redirect_uri 参数值复制出来跟 soular 里登记的地址逐字符对比。记住是逐字符——不要小看尾部 / 和大小写的问题。4.2 Token 过期导致频繁掉线GitPuk 接入 soular 之后用户的会话由 souldar 签发的 Token 维护。soular 默认的 Access Token 有效期通常比较短比如 5 到 10 分钟而 Refresh Token 有效期可能是 30 分钟或者更长。如果 GitPuk 没有正确刷新令牌用户过几分钟就要重新登录一次体验非常糟糕。我的建议是分两方面排查。一方面在 soular 里调长 Access Token 的有效期比如设置为 15 分钟Refresh Token 设置为 8 到 12 小时长期不活跃的用户才需要重新登录。另一方面确认 GitPuk 的 OIDC 配置中启用了刷新令牌refresh_token骨架配置里有一个“启用 Token 刷新”的开关默认可能是关闭的打开即可。另外要提醒一个小细节Token 刷新依赖 Client Secret如果你改了 GitPuk 里的 Client Secret但 soular 里还是旧的刷新时会报 unauthorized_client用户表现为登录后一段时间突然掉线重新登录又好了反复循环。遇到这种情形先去检查两边密钥是否一致。4.3 用户在灵魂出窍——登出不同步的问题这是一个容易被忽略的场景用户点击 GitPuk 的退出按钮GitPuk 本地会话清掉了但 soular 里的会话还活着。用户再次访问 GitPuk 时由于 soular 还有有效会话会直接静默登录回来用户根本感知不到自己已经“退出”过了。OIDC 协议中对于登出同步有两种常见方案Front-Channel Logout前端通道登出和 Back-Channel Logout后端通道登出。soular 基于 OIDC 实现时退出请求会把用户重定向到end_session_endpoint并带上post_logout_redirect_uri参数表示退出后回到哪里。实际操作时需要确认三个条件GitPuk 是否支持配置登出重定向地址soular 里的客户端是否开启了“前端登出”功能跳转时是否携带了 ID Token 的 ID 作为参数。只要有一个条件不满足就会出现上面那种“假退出”现象。如果你测试发现很难做到完全同步变通方案是把 GitPuk 的会话时间调短一些让它在用户离开后尽快过期至少减少安全窗口。4.4 用户首次登录后没有权限最后一个常见问题用户通过 soular 登录 GitPuk 成功了但看不到任何项目或者无法创建仓库看起来像“什么都没发生”。这种情况几乎总是本地权限设置的问题。soular 只负责认证它不管用户在 GitPuk 内的角色。自动创建的用户默认只是“普通成员”如果你希望特定用户拥有管理员权限需要到 GitPuk 用户管理里手动提升角色。如果你的团队要求比较高希望根据 soular 里的部门或职位自动分配 GitPuk 角色可以考虑使用 soular 的自定义属性claim在 ID Token 中携带角色信息再通过 GitPuk 的映射规则把角色同步过来。这个方案会复杂一些但一旦跑通日常维护成本很低。一个小建议首次集成时不要追求完美先把“能用”跑通角色映射作为二期优化。因为角色映射涉及两边数据模型对齐牵扯面广不是半小时能搞定的事。先跑通认证再逐步完善授权推进起来会平滑很多。5. 上线后的运维建议与经验总结集成完成只是开始日常运维中还有不少细节值得关注。这节是我最后想补充的经验之谈核心原则是把身份认证交给 soular把精力聚焦在 GitPuk 本身的业务上。第一关于密钥管理。Client Secret 不要明文写在 GitPuk 的配置文件里至少用环境变量或者密钥管理服务比如 Vault、KMS来存放。如果配置信息泄露攻击者可以拿着 Client ID 和 Secret 在 soular 上注册自己的回调地址进而配合浏览器端拿到用户的授权码风险不小。第二关于加密证书。如果 soular 部署在用户网络较复杂的区域或者 GitPuk 要从另一台服务器回调 soular建议确认两边的 HTTPS 证书都是受信任的证书而不是内网自签名证书。GitPuk 在拉取 soular 的 Discovery 文档时如果证书校验失败通常会直接报错或跳过导致集成看起来完全失效。测试时临时关闭证书校验可以但生产环境一定要处理好证书信任链。第三关于用户目录的同步。soular 的账号源如果能和公司的人力系统打通那么新员工入职自动有账号、离职自动被禁用。如果你的 soular 是纯手工维护账号的建议至少安排一个定期专项任务确保账号状态与人员状态一致。否则统一登录做得再好账号源本身混乱也白搭。第四关于审计日志。集成后用户登录 GitPuk 的记录发生在 soular 中GitPuk 内的操作记录还在 GitPuk 里。做安全审计时需要把两边日志拉通可以根据时间戳和用户唯一标识sub进行关联。建议在配置 GitPuk 的日志级别时调高认证相关日志的详细程度方便日后追溯。第五关于回滚预案。任何一次变更都可能有意外集成 OIDC 也不应该例外。在改动 GitPuk 认证配置之前把原来的配置项完整截图或备份。如果你同时保留了本地账号登录回滚就是切回本地登录而已非常简单。这也是我强烈建议保留本地登录开关的原因——线上出问题的时候它是你的保命符。我个人在实际操作中的体会是统一登录这件事难的不是配置本身而是对 OIDC 协议的理解和对业务场景的判断。你把它当成一次性的“对接任务”来做容易流于表面你把它当成企业内部身份体系的组成部分来设计后面所有的系统接入都会变得顺理成章。最后再分享一个小技巧在完成 GitPuk 接入 soular 之后把这次配置过程中的所有参数、截图、踩坑记录整理成一份内部文档下次接入 Jenkins、Wiki 或者其他系统时直接复用什么思路只需要把客户端 ID 和回调地址替换掉就行。第一次花半天第二次半小时这就是标准协议带来的复利。