先从实际场景说起。团队内部代码托管平台用的是自建的 GitPuk一开始只是给十几个研发用账号手工开通密码各自保管一切看起来都还凑合。等业务扩张到几十人、上百人同时接入了 CI、文档系统、制品库、监控平台之后问题就压过来了每个系统一套账号管理员每天在处理“密码重置”“离职账号清理”“权限回收”这些杂事研发同学也要反复记多套口令。后来我们决定引入 soular 作为统一认证中心让 GitPuk 与 soular 对接走 OAuth2/OIDC 协议实现统一登入也就是一套企业账号密码登录一次就能进入所有系统。这篇文章就把这次从选型、部署到踩坑的完整过程写出来内容包括最基础的 GitPuk 环境搭建、soular 侧配置、两者打通的实际步骤以及权限映射、会话过期、灰度切换这些一线实操经验适合正在做自建 Git 服务、又准备接企业 SSO 的同行参考。1. 为什么必须做统一登录没有 SSO 时的真实痛点1.1 账号体系分散带来的成本是不可见的很多团队在做大之前并不会把“账号管理”当成一个正经技术问题。GitPuk 自己维护一套用户表Jenkins 又用一套Confluence 还要再注册一遍。表面上每个系统都支持本地账号开通也很快但如果把时间拉长到一年成本相当吓人。我统计过一个不到八十人的研发部门每周平均发生 6 到 8 次密码重置每次处理加上沟通至少二十分钟一个月就是好几个小时。更麻烦的是离职场景人走了之后管理员要一个系统一个系统手动禁用账号漏掉任何一个都可能留下安全隐患。这类问题不是 GitPuk 本身造成的而是缺少一个统一的身份源。1.2 统一登录到底解决什么问题引入 soular 之后GitPuk 不再自己判断密码是否正确而是把认证请求转发给 soular。用户登录 GitPuk实际上是在 soular 上完成身份校验校验通过后由 soular 签发一个临时凭证GitPuk 再用这个凭证换取用户信息并建立会话。这样做有几个直接收益第一账号生命周期可以被集中管理新员工入职只要在 soular 里开通一次所有系统都能访问第二用户不需要为 GitPuk 单独记一套密码也就不会因为忘记密码反复打扰管理员第三审计日志收敛到 soular 一个节点谁在什么时间登录过哪些系统查起来一目了然。这就是“统一登入”最核心的价值不是省掉一次登录动作而是把身份管理从各个业务系统里抽离出来变成一个基础设施。1.3 多种集成方案之间为什么选择 OAuth2/OIDC市面上常见的统一登录方案大致有几类基于 LDAP 做账号认证、基于 SAML 做浏览器级单点登录、基于 OAuth2/OIDC 做授权与身份传递。LDAP 适合单纯的账号密码校验但它没法很好地承载“用户点击 GitPuk 页面跳转到统一登录页再跳回来”这种 Web SSO 体验SAML 在传统企业软件里很常见但配置重、消息格式复杂面对 GitPuk 这类现代 Web 应用时反而显得累赘。OAuth2 加上 OIDC 扩展是目前 Web 应用接入第三方登录事实上的标准GitPuk 天然支持soular 也把它作为主要对外协议之一所以两边衔接最顺。具体的做法是GitPuk 作为一个 OAuth2 Clientsoular 作为 Authorization Server用户访问 GitPuk 时被引导到 soular 授权页面登录成功后 soular 返回授权码GitPuk 再拿授权码去换取 ID Token 和 Access Token最后根据 Token 里的用户标识建立本地会话。2. 把基础环境搞清楚GitPuk 部署与 soular 的部署边界2.1 部署前必须明确的三个边界在动配置之前建议先画清楚三个边界。第一个是域名边界soular 和 GitPuk 不能共用同一个顶级域名下的同一台反向代理规则通常会让 sso.example.com 指向 soular让 git.example.com 指向 GitPuk二者之间通过 HTTPS 通信。第二个是数据边界soular 只管账号身份和认证凭证GitPuk 自己的项目、仓库、Issue、Merge Request 数据仍然保存在自己的数据库里两边不做数据表层面的直连。第三个是会话边界用户在 soular 登录成功后拿到的是 soular 的会话 Cookie在 GitPuk 登录成功后拿到的是 GitPuk 的会话 Cookie这两个会话彼此独立由 GitPuk 通过解析 Token 来确认当前用户身份而不是直接读取 soular 的 Cookie。这是我最早容易搞混的地方当时想着省事让 GitPuk 直接校验 soular 的 Cookie实际做出来不仅不安全还会跨域失效。2.2 GitPuk 侧的基础部署示例GitPuk 的具体安装方式取决于你们拿到的是源码、容器镜像还是安装包但部署骨架大同小异。这里给一个基于容器方式的编排示例重点是先把 GitPuk 独立跑通version: 3.8 services: gitpuk: image: registry.internal.example.com/gitpuk:2.4.0 container_name: gitpuk restart: always ports: - 3000:3000 environment: GITPUK_SERVER_DOMAIN: git.example.com GITPUK_DATABASE_TYPE: postgres GITPUK_DATABASE_HOST: db GITPUK_DATABASE_NAME: gitpuk GITPUK_DATABASE_USER: gitpuk GITPUK_DATABASE_PASSWORD: change-me GITPUK_AUTH_TYPE: oauth2 volumes: - gitpuk_data:/data depends_on: - db db: image: postgres:15 container_name: gitpuk-db restart: always environment: POSTGRES_DB: gitpuk POSTGRES_USER: gitpuk POSTGRES_PASSWORD: change-me volumes: - gitpuk_db_data:/var/lib/postgresql/data volumes: gitpuk_data: gitpuk_db_data:这个编排文件只能作为本地验证环境使用真正上生产时要做的第一件事就是替换掉默认密码并把 Postgres 单独部署不要和 GitPuk 挤在一台机器里。另一个容易被忽略的点是GITPUK_SERVER_DOMAIN必须和最终对外访问的域名一致因为 OAuth2 回调 URL 是基于这个域名生成的。如果这里写错了后面所有跳转都可能指向错误地址。部署完成后先用默认管理员账号登录创建一个业务测试用户确认 GitPuk 自身的注册、登录、建仓流程没问题再往下做集成。2.3 soular 的接入前提与证书要求soular 侧的部署通常不需要 GitPuk 参与它本身就是一个独立服务团队里如果有现成的统一认证中心跳过部署这步直接开对接即可。接入前需要确认几个前提soular 的对外地址必须是 HTTPS并且证书链要完整因为 GitPuk 在向 soular 发起 Token 请求时如果遇到自签名证书很多 HTTP 客户端默认会拒绝连接。并不是说自签名证书完全不能用而是需要在 GitPuk 所在的 JVM 或系统 CA 库里额外导入证书配置成本比较高不如直接让 Nginx 上挂一个正规证书。其次soular 需要开启 OIDC 相关的 Endpoint至少保证/.well-known/openid-configuration能通过浏览器访问到这个地址返回的 JSON 里包含授权地址、Token 地址、用户信息地址等元数据GitPuk 正是通过它来自动发现配置的。2.4 反向代理与回调地址的坑一旦把 GitPuk 和 soular 都放到 Nginx 后面就要特别注意“外部回调地址”和“内部转发地址”的区别。用户在浏览器里访问https://git.example.comNginx 把请求转发给容器的http://localhost:3000。当 GitPuk 生成 OAuth2 回调链接时它使用的是自己配置文件中的ROOT_URL或SERVER_DOMAIN而不是浏览器当前地址。所以务必将 GitPuk 的服务域名配置成对外地址同时让 Nginx 保留Host头。常见的配置错误是容器内访问路径是http://gitpuk:3000导致回调地址变成了内网地址用户在 soular 登录成功后跳回一个无法访问的内网 IP。我自己排查过一起这样的问题最终就是发现 Nginx 里少了proxy_set_header Host $host;加上之后问题立刻消失。3. soular 统一认证中心在集成中扮演的角色3.1 从“账号密码校验”升级到“身份令牌交换”soular 在集成方案里并不只是一个简单的密码校验服务它承担的是身份提供方Identity Provider角色。GitPuk 本身知道自己有哪些项目、用户有什么权限但它不再回答“你是谁”这个问题只负责回答“这个人已经由 soular 验证过我可以信任”。这个信任关系建立在令牌交换上用户访问 GitPukGitPuk 把人引导到 soular 登录页soular 验证成功后返回一个一次性授权码GitPuk 拿着授权码回到 soular 的 Token Endpoint 换取 ID Token。整个过程中GitPuk 自始至终没有得到用户的密码它只拿到了 soular 签名过的用户身份信息。这样做的好处是即使 GitPuk 被攻破攻击者拿到的也只是会话令牌而不是所有人的密码明文。3.2 OIDC 中的几个概念用白话讲清楚网上讲 OIDC 的文章很多但真正对接时最容易卡住的其实是几个名词的对应关系。Client ID 就是 GitPuk 在 soular 里注册时拿到的应用标识类似门禁卡上的编号Client Secret 相当于门禁卡配套的密码GitPuk 请求 Token 时必须出示Redirect URI 是用户登录成功后 soular 允许跳转回来的地址白名单GitPuk 每次发起授权请求时都会带上这个参数soular 会严格校验它是否在白名单里。Scope 则是这次登录需要返回的信息范围通常包含openid、profile、emailopenid 是必需的profile 携带昵称和头像email 携带邮箱地址。很多新手会漏掉openid结果 ID Token 解析不出来或缺少sub字段整个登录就会失败。sub是用户在 soular 中的唯一标识GitPuk 会拿它来关联本地用户。3.3 在 soular 中创建 GitPuk 客户端在 soular 管理后台新增一个应用应用类型选择OIDC或OAuth2填写的信息大致如下配置项推荐值说明应用名称GitPuk Production方便在 soular 后台识别Redirect URIhttps://git.example.com/user/oauth2/soular/callback必须与 GitPuk 实际回调地址完全一致Scopeopenid profile email按需勾选不要给过多权限Token 有效期15 分钟Access Token 建议短一些Refresh Token按需开启GitPuk 一般不需要 Refresh TokenRedirect URI 是集成过程中最容易出问题的地方。如果你的 GitPuk 回调路径是/user/oauth2/soular/callback那么在 soular 里登记的就必须是完整 URL包括协议、域名、端口如果不是 80/443和路径。任何一处不匹配soular 都会直接拒绝。创建完成后soular 会生成一对 Client ID 和 Client Secret把这两个值记下来下一步配置 GitPuk 时要用。这里还建议顺手检查一下 soular 的 UserInfo Endpoint 是否能返回email因为 GitPuk 默认会拿邮箱来做用户匹配。如果 soular 返回的邮箱和 GitPuk 本地已有用户的邮箱不一致就会出现登录成功但无法识别本地账号的情况。3.4 调试时可直接验证的 OIDC 配置接口配置完成后先不要急着去点 GitPuk 登录页先在浏览器里访问 soular 的/.well-known/openid-configuration确认返回内容中包含authorization_endpoint、token_endpoint、userinfo_endpoint、jwks_uri这几个字段。如果哪个地址缺失后面流程必然有一环会断掉。我常用命令行的方式快速看返回结果curl https://sso.example.com/.well-known/openid-configuration看到合法的 JSON 后把返回里的关键 Endpoint 和下面 GitPuk 配置比对一下。特别注意issuer字段我遇到过一类比较隐蔽的问题soular 内部访问地址是http://soular:8080但对外是https://sso.example.com导致实际下发的 ID Token 里iss是内网地址GitPuk 做校验时一看 issuer 对不上直接拒绝。解决方式通常是在 soular 的配置中显式指定对外 issuer 地址。4. 把 GitPuk 接入 soular配置步骤与联调实录4.1 GitPuk 管理后台添加认证源每个人拿到的 GitPuk 版本可能不同菜单名称也有差异但大体都在“管理后台 - 认证源 / 认证方式”这个位置。进入配置页面后选择新增 OAuth2 或 OIDC 认证源把刚才在 soular 里拿到的信息填进去。关键项包括认证源名称、Client ID、Client Secret、Authorization Endpoint、Token Endpoint、UserInfo Endpoint 和 Scopes。如果你使用的 GitPuk 支持 OIDC Discovery 方式那么只需要填一个 Discovery URL也就是上面提到的https://sso.example.com/.well-known/openid-configuration它会自动拉取其余地址。能用 Discovery 就尽量用手工维护一套 Endpoint 地址后期 soular 升级或者迁移域名时非常容易漏改。配置表单里还有一个“允许通过该认证源自动创建用户”之类的选项建议默认开启。原因是集成初期GitPuk 本地没有 soular 用户对应的账号如果不允许自动创建用户从 soular 登录成功后会看到一个“用户不存在”的错误体验很差。开启自动创建后GitPuk 会用 soular 返回的用户信息自动建立本地账号。等运行稳定了再根据安全要求决定是否关闭这个开关改为通过用户同步接口提前创建。4.2 一条正确的登录链路应该长什么样配置完成后做联调时可以用一个尚未在 GitPuk 里创建过的测试账号走完整条链路预期过程如下浏览器访问https://git.example.com/user/login点击“使用 soular 登录”按钮请求被重定向到https://sso.example.com/...浏览器地址栏域名变化如果尚未登录过 soular会出现统一登录页面输入 soular 账号密码登录成功后浏览器收到 302 跳转回到https://git.example.com/user/oauth2/soular/callback?codexxxGitPuk 后端拿 code 请求 soular 的 Token Endpoint换取 ID TokenGitPuk 解析 ID Token确认邮件或用户名自动创建本地账号浏览器跳转到 GitPuk 首页此时右上角已经显示该用户信息。如果每步都正常说明链路已经通了。第 4 步的code是一次性的原则上只能使用一次如果 GitPuk 因为网络超时重复使用同一个 codesoular 会返回invalid_grant。这属于正常的安全机制不是 bug排查时要能判断出来。4.3 首次登录后用户角色权限怎样定很多团队在打通统一登录后会忽略一个关键设定通过 soular 自动创建出来的用户在 GitPuk 里默认是什么角色如果默认是普通用户那没问题但如果默认是管理员相当于任何能登录 soular 的人都能管理 GitPuk这是非常严重的越权风险。我经历过一次小事故就是因为自动创建的用户默认权限过高导致一位新同事登录后能进后台看到全局配置。解决方式是在 GitPuk 的认证源配置里找到“新用户默认角色”设置为普通用户再通过后续的手动授权或者用户组映射来提升权限。另一个方案是先禁用自动创建提前从 soular 导出用户列表通过 GitPuk 提供的用户导入接口批量创建创建时直接指定角色这样权限在登录前就已经确定。4.4 统一登入和本地管理员账号如何共存一个现实的问题是soular 打通之后原本 GitPuk 里的管理员账号怎么办。直接删除风险很大万一 soular 临时故障本地管理员账号反而成了救命的逃生通道。我的建议是保留一个强密码的本地管理员并只允许从内网访问平时不使用。这个账号类似于机房里的带外管理口不需要出现在日常登录页上但绝不能没有。团队里可以约定当 soular 不可用时通过本地管理员登录 GitPuk 排查认证源配置。不过本地管理员也要纳入定期改密范围不能因为“没人用”就不管它。5. 用户同步和权限映射的进阶玩法5.1 soular 用户到 GitPuk 的自动同步思路OAuth2/OIDC 解决了“认证”的问题但“用户从哪来”如果只依靠首次登录时自动创建还是不够主动。比如你希望某个项目团队在第一天就能访问 GitPuk而不是等每个人手动登录一次后才生效就需要做用户同步。常见的同步方式有两种一种是 soular 侧支持 SCIM 协议把用户和组织结构推送到 GitPuk 的服务端另一种是定时任务读取 soular 的用户 API再调用 GitPuk 的管理接口批量创建用户。如果团队规模不大我更推荐第二种因为实现起来直观而且对 GitPuk 没有额外协议要求。写定时任务时要注意幂等性已经存在的用户要跳过离职的用户标记禁用而不是删除因为删除账号会导致历史提交记录失去用户名关联。5.2 用用户组映射控制 GitPuk 组织权限GitPuk 自身的权限模型通常分组织、仓库两层组织里可以设置 Owner、Member 等角色仓库里再单独设置读、写、管理员权限。如果每个用户都手动分配又回到了台账管理的老路。更好的做法是在 soular 里维护好用户组例如gitpuk-project-a-core、gitpuk-project-a-readonly然后在 GitPuk 侧把认证源带来的组信息和本地团队做映射。有些 GitPuk 支持直接从 OIDC Token 的groups断言里读取用户组并据此自动化分配角色。如果 Token 里没有组信息也可以让 soular 在 UserInfo 接口里额外返回groups字段。这里必须注意组名要做严格校验避免把 soular 内部的管理组误映射到 GitPuk 的管理员角色上。5.3 一个适合中小团队的权限矩阵参考建议在集成初期就把权限矩阵定下来而不是等出问题再补。结合实际团队规模我习惯用下面的矩阵作为起点身份GitPuk 角色说明普通研发普通成员可以浏览和克隆有权限的仓库核心开发者仓库写入者在特定仓库上有 Push 权限技术 Leader组织 Owner管理项目成员与分支保护规则运维 / 管理员GitPuk 管理员负责全局配置和认证源维护把这个矩阵落到 GitPuk 和 soular 的组映射配置里后账号开通和权限调整都不再需要进入 GitPuk 后台逐个人点直接在 soular 里把人加入对应组下次登录权限就生效了。要注意的是组映射通常不是即时生效的取决于 GitPuk 更新用户信息的时间点如果想让权限立刻生效可以要求用户退出重新登录。6. 真实联调遇到的问题与排查方法6.1 登录跳转后提示 redirect_uri 不匹配这是一个极其常见的问题。现象是点击登录跳转到 soular 后页面提示类似Invalid redirect_uri的错误。通常原因是 soular 里登记的地址和 GitPuk 实际生成的回调地址不一致。排查思路打开浏览器开发者工具在重定向请求里找到redirect_uri参数把它和 soular 后台登记的地址逐字符对比。最常见的问题是结尾少了/、用了http而不是https、或者回调路径里包含了额外的项目名。把两边的地址完全改成一致后问题基本就消失了。6.2 登录成功后返回 GitPuk 却未建立会话有时整个跳转链路看起来没有报错日志里也能看到授权码交换成功但用户回来后仍然处于未登录状态。这种情况要先看 GitPuk 日志里对 ID Token 的解析结果。一个高频原因是email字段为空或者 GitPuk 配置里要求的唯一标识字段在 Token 中不存在。可以对比一下 soular 上该用户的邮箱地址和 GitPuk 本地用户的邮箱地址如果你以前用 GitPuk 注册过上线的邮箱后来在 soular 里换了新邮箱那么自动匹配就会失败。还有一种原因是 GitPuk 配置里打开了“验证邮箱已存在”之类的选项而返回的邮箱没有通过校验也会导致登录中断。6.3 会话经常掉线需要反复登录如果用户每次访问 GitPuk 都像“失忆”一样刚登录成功过一次下次又要重新认证一般是会话 Cookie 的持久化设置和 Token 有效期配置不协调。GitPuk 本地会话有效期可以由管理员设置默认可能偏短。soular 侧的 Access Token 有效期也会影响重新认证频率如果 Access Token 过期后 GitPuk 没有刷新凭证只能强制用户重新跳转到 soular。建议把 GitPuk 本地会话有效期调成一个可以接受的值比如 8 小时同时开启“记住我”之类的选项或者配置 Refresh Token。这类问题不是故障而是会话策略没有按用户体验调整。6.4 时钟漂移导致 Token 校验失败OIDC 的 ID Token 里带有iat和exp时间戳GitPuk 校验时会和当前服务器时间对比。如果 GitPuk 所在服务器的时间与 soular 服务器时间偏差过大Token 会被判定为“未生效”或“已过期”。排查方法是先确认两台服务器的 NTP 同步状态。很多内网服务器为了安全禁用了外网 NTP又没有配置内网时间源积累一段时间后偏差可能达到几分钟。修复办法是把 GitPuk 和 soular 都指向同一个内网时间服务器另外启动一个简单的验证把服务器当前时间与手机时间对比一下就能快速判断是否偏了。6.5 集成过程中的典型问题速查表现象可能原因解决方向跳转 soular 后报 redirect_uri 错误回调地址不一致对比两端完整 URL授权码无效 / invalid_grantcode 已过期或重复使用重新发起登录检查网络时间登录成功但 GitPuk 不识别用户email 或用户名不匹配检查 UserInfo 返回字段页面频繁回到登录页会话过期策略过短调长本地会话并配置刷新令牌Token 解析报签名错误证书或 JWKS 获取失败检查 soular 证书链与域名首页提示没有权限默认角色太低在认证源处调整新用户角色7. 上线后的运营收尾体验优化与逃生方案集成完成不是终点真正考验人的是后续的日常运营。先做一遍全局检查确认登录页没有残留多余入口如果 GitPuk 支持关闭本地注册功能一定要关掉避免有人绕过 soular 建立一套影子账号否则统一登入相当于白做。接着要把 GitPuk 后台的审计日志和 soular 的登录日志接入到团队的日志系统里这样每次登录成功或失败都能追溯到源头。如果这两个系统的日志格式差异较大建议至少把时间戳格式对齐统一成 ISO8601 的 UTC 时间否则后面查跨系统问题时时间差会让人怀疑人生。上线后最好安排一次全员演练让团队用统一账号登录一遍 GitPuk收集反馈。常见的问题是小部分老用户本地邮箱和 soular 里的邮箱不一致登录后 GitPuk 自动生成了新账号导致原有仓库权限丢失。应对策略是在正式切换前先做用户匹配把本地用户和 soular 用户的唯一标识关系批量写入减少切换带来的摩擦。我当年做切换时先让所有用户在企业微信里更新了常用邮箱然后写脚本把 GitPuk 的老邮箱批量改成新邮箱再打开统一登录整个过程只遇到个别例外。还有一条逃生经验要分享改任何认证配置前先确认自己还有一个可用的本地管理员会话。我的做法是保持一个浏览器隐身窗口用本地管理员登录着不要关掉。万一你在配置 OIDC 过程中把本地登录选项不小心关了且新配置又无法生效至少还有这个隐身窗口能救回来。如果没有预留就只能去后台改数据库或联系平台厂商非常被动。另一方面建议给 GitPuk 的认证源配置加一个“脏检查”。每次变更配置前先截图保存原有所有参数。因为这个配置页面一旦保存成功旧配置就会被覆盖而一个字段填错可能导致整站所有人都登录不进去。恢复时想不起来原来的 Client ID 或 Endpoint只能去 soular 后台重新比对耽误时间。截图加上一台跳板机上的 curl 测试脚本是成本最低的保险方案。如果团队内部有多个系统都要接 soular这次 GitPuk 的对接经验完全可以沉淀成一篇内部 SOP。把创建客户端、配置回调地址、核对 Token Endpoint、设置默认角色等步骤固化下来以后接下一个系统时直接对着操作。我在做这块时体会很深的一点是统一登录这种基础设施最怕的就是每个应用各自对接、各自踩坑最后没人能说清楚完整链路。哪怕先只跑通 GitPuk 一个系统只要把文档和脚本沉淀下来后面扩展到 CI、制品库、Wiki 系统的成本都会降低很多。
GitPuk接入soular统一登录：基于OAuth2/OIDC的SSO实践
先从实际场景说起。团队内部代码托管平台用的是自建的 GitPuk一开始只是给十几个研发用账号手工开通密码各自保管一切看起来都还凑合。等业务扩张到几十人、上百人同时接入了 CI、文档系统、制品库、监控平台之后问题就压过来了每个系统一套账号管理员每天在处理“密码重置”“离职账号清理”“权限回收”这些杂事研发同学也要反复记多套口令。后来我们决定引入 soular 作为统一认证中心让 GitPuk 与 soular 对接走 OAuth2/OIDC 协议实现统一登入也就是一套企业账号密码登录一次就能进入所有系统。这篇文章就把这次从选型、部署到踩坑的完整过程写出来内容包括最基础的 GitPuk 环境搭建、soular 侧配置、两者打通的实际步骤以及权限映射、会话过期、灰度切换这些一线实操经验适合正在做自建 Git 服务、又准备接企业 SSO 的同行参考。1. 为什么必须做统一登录没有 SSO 时的真实痛点1.1 账号体系分散带来的成本是不可见的很多团队在做大之前并不会把“账号管理”当成一个正经技术问题。GitPuk 自己维护一套用户表Jenkins 又用一套Confluence 还要再注册一遍。表面上每个系统都支持本地账号开通也很快但如果把时间拉长到一年成本相当吓人。我统计过一个不到八十人的研发部门每周平均发生 6 到 8 次密码重置每次处理加上沟通至少二十分钟一个月就是好几个小时。更麻烦的是离职场景人走了之后管理员要一个系统一个系统手动禁用账号漏掉任何一个都可能留下安全隐患。这类问题不是 GitPuk 本身造成的而是缺少一个统一的身份源。1.2 统一登录到底解决什么问题引入 soular 之后GitPuk 不再自己判断密码是否正确而是把认证请求转发给 soular。用户登录 GitPuk实际上是在 soular 上完成身份校验校验通过后由 soular 签发一个临时凭证GitPuk 再用这个凭证换取用户信息并建立会话。这样做有几个直接收益第一账号生命周期可以被集中管理新员工入职只要在 soular 里开通一次所有系统都能访问第二用户不需要为 GitPuk 单独记一套密码也就不会因为忘记密码反复打扰管理员第三审计日志收敛到 soular 一个节点谁在什么时间登录过哪些系统查起来一目了然。这就是“统一登入”最核心的价值不是省掉一次登录动作而是把身份管理从各个业务系统里抽离出来变成一个基础设施。1.3 多种集成方案之间为什么选择 OAuth2/OIDC市面上常见的统一登录方案大致有几类基于 LDAP 做账号认证、基于 SAML 做浏览器级单点登录、基于 OAuth2/OIDC 做授权与身份传递。LDAP 适合单纯的账号密码校验但它没法很好地承载“用户点击 GitPuk 页面跳转到统一登录页再跳回来”这种 Web SSO 体验SAML 在传统企业软件里很常见但配置重、消息格式复杂面对 GitPuk 这类现代 Web 应用时反而显得累赘。OAuth2 加上 OIDC 扩展是目前 Web 应用接入第三方登录事实上的标准GitPuk 天然支持soular 也把它作为主要对外协议之一所以两边衔接最顺。具体的做法是GitPuk 作为一个 OAuth2 Clientsoular 作为 Authorization Server用户访问 GitPuk 时被引导到 soular 授权页面登录成功后 soular 返回授权码GitPuk 再拿授权码去换取 ID Token 和 Access Token最后根据 Token 里的用户标识建立本地会话。2. 把基础环境搞清楚GitPuk 部署与 soular 的部署边界2.1 部署前必须明确的三个边界在动配置之前建议先画清楚三个边界。第一个是域名边界soular 和 GitPuk 不能共用同一个顶级域名下的同一台反向代理规则通常会让 sso.example.com 指向 soular让 git.example.com 指向 GitPuk二者之间通过 HTTPS 通信。第二个是数据边界soular 只管账号身份和认证凭证GitPuk 自己的项目、仓库、Issue、Merge Request 数据仍然保存在自己的数据库里两边不做数据表层面的直连。第三个是会话边界用户在 soular 登录成功后拿到的是 soular 的会话 Cookie在 GitPuk 登录成功后拿到的是 GitPuk 的会话 Cookie这两个会话彼此独立由 GitPuk 通过解析 Token 来确认当前用户身份而不是直接读取 soular 的 Cookie。这是我最早容易搞混的地方当时想着省事让 GitPuk 直接校验 soular 的 Cookie实际做出来不仅不安全还会跨域失效。2.2 GitPuk 侧的基础部署示例GitPuk 的具体安装方式取决于你们拿到的是源码、容器镜像还是安装包但部署骨架大同小异。这里给一个基于容器方式的编排示例重点是先把 GitPuk 独立跑通version: 3.8 services: gitpuk: image: registry.internal.example.com/gitpuk:2.4.0 container_name: gitpuk restart: always ports: - 3000:3000 environment: GITPUK_SERVER_DOMAIN: git.example.com GITPUK_DATABASE_TYPE: postgres GITPUK_DATABASE_HOST: db GITPUK_DATABASE_NAME: gitpuk GITPUK_DATABASE_USER: gitpuk GITPUK_DATABASE_PASSWORD: change-me GITPUK_AUTH_TYPE: oauth2 volumes: - gitpuk_data:/data depends_on: - db db: image: postgres:15 container_name: gitpuk-db restart: always environment: POSTGRES_DB: gitpuk POSTGRES_USER: gitpuk POSTGRES_PASSWORD: change-me volumes: - gitpuk_db_data:/var/lib/postgresql/data volumes: gitpuk_data: gitpuk_db_data:这个编排文件只能作为本地验证环境使用真正上生产时要做的第一件事就是替换掉默认密码并把 Postgres 单独部署不要和 GitPuk 挤在一台机器里。另一个容易被忽略的点是GITPUK_SERVER_DOMAIN必须和最终对外访问的域名一致因为 OAuth2 回调 URL 是基于这个域名生成的。如果这里写错了后面所有跳转都可能指向错误地址。部署完成后先用默认管理员账号登录创建一个业务测试用户确认 GitPuk 自身的注册、登录、建仓流程没问题再往下做集成。2.3 soular 的接入前提与证书要求soular 侧的部署通常不需要 GitPuk 参与它本身就是一个独立服务团队里如果有现成的统一认证中心跳过部署这步直接开对接即可。接入前需要确认几个前提soular 的对外地址必须是 HTTPS并且证书链要完整因为 GitPuk 在向 soular 发起 Token 请求时如果遇到自签名证书很多 HTTP 客户端默认会拒绝连接。并不是说自签名证书完全不能用而是需要在 GitPuk 所在的 JVM 或系统 CA 库里额外导入证书配置成本比较高不如直接让 Nginx 上挂一个正规证书。其次soular 需要开启 OIDC 相关的 Endpoint至少保证/.well-known/openid-configuration能通过浏览器访问到这个地址返回的 JSON 里包含授权地址、Token 地址、用户信息地址等元数据GitPuk 正是通过它来自动发现配置的。2.4 反向代理与回调地址的坑一旦把 GitPuk 和 soular 都放到 Nginx 后面就要特别注意“外部回调地址”和“内部转发地址”的区别。用户在浏览器里访问https://git.example.comNginx 把请求转发给容器的http://localhost:3000。当 GitPuk 生成 OAuth2 回调链接时它使用的是自己配置文件中的ROOT_URL或SERVER_DOMAIN而不是浏览器当前地址。所以务必将 GitPuk 的服务域名配置成对外地址同时让 Nginx 保留Host头。常见的配置错误是容器内访问路径是http://gitpuk:3000导致回调地址变成了内网地址用户在 soular 登录成功后跳回一个无法访问的内网 IP。我自己排查过一起这样的问题最终就是发现 Nginx 里少了proxy_set_header Host $host;加上之后问题立刻消失。3. soular 统一认证中心在集成中扮演的角色3.1 从“账号密码校验”升级到“身份令牌交换”soular 在集成方案里并不只是一个简单的密码校验服务它承担的是身份提供方Identity Provider角色。GitPuk 本身知道自己有哪些项目、用户有什么权限但它不再回答“你是谁”这个问题只负责回答“这个人已经由 soular 验证过我可以信任”。这个信任关系建立在令牌交换上用户访问 GitPukGitPuk 把人引导到 soular 登录页soular 验证成功后返回一个一次性授权码GitPuk 拿着授权码回到 soular 的 Token Endpoint 换取 ID Token。整个过程中GitPuk 自始至终没有得到用户的密码它只拿到了 soular 签名过的用户身份信息。这样做的好处是即使 GitPuk 被攻破攻击者拿到的也只是会话令牌而不是所有人的密码明文。3.2 OIDC 中的几个概念用白话讲清楚网上讲 OIDC 的文章很多但真正对接时最容易卡住的其实是几个名词的对应关系。Client ID 就是 GitPuk 在 soular 里注册时拿到的应用标识类似门禁卡上的编号Client Secret 相当于门禁卡配套的密码GitPuk 请求 Token 时必须出示Redirect URI 是用户登录成功后 soular 允许跳转回来的地址白名单GitPuk 每次发起授权请求时都会带上这个参数soular 会严格校验它是否在白名单里。Scope 则是这次登录需要返回的信息范围通常包含openid、profile、emailopenid 是必需的profile 携带昵称和头像email 携带邮箱地址。很多新手会漏掉openid结果 ID Token 解析不出来或缺少sub字段整个登录就会失败。sub是用户在 soular 中的唯一标识GitPuk 会拿它来关联本地用户。3.3 在 soular 中创建 GitPuk 客户端在 soular 管理后台新增一个应用应用类型选择OIDC或OAuth2填写的信息大致如下配置项推荐值说明应用名称GitPuk Production方便在 soular 后台识别Redirect URIhttps://git.example.com/user/oauth2/soular/callback必须与 GitPuk 实际回调地址完全一致Scopeopenid profile email按需勾选不要给过多权限Token 有效期15 分钟Access Token 建议短一些Refresh Token按需开启GitPuk 一般不需要 Refresh TokenRedirect URI 是集成过程中最容易出问题的地方。如果你的 GitPuk 回调路径是/user/oauth2/soular/callback那么在 soular 里登记的就必须是完整 URL包括协议、域名、端口如果不是 80/443和路径。任何一处不匹配soular 都会直接拒绝。创建完成后soular 会生成一对 Client ID 和 Client Secret把这两个值记下来下一步配置 GitPuk 时要用。这里还建议顺手检查一下 soular 的 UserInfo Endpoint 是否能返回email因为 GitPuk 默认会拿邮箱来做用户匹配。如果 soular 返回的邮箱和 GitPuk 本地已有用户的邮箱不一致就会出现登录成功但无法识别本地账号的情况。3.4 调试时可直接验证的 OIDC 配置接口配置完成后先不要急着去点 GitPuk 登录页先在浏览器里访问 soular 的/.well-known/openid-configuration确认返回内容中包含authorization_endpoint、token_endpoint、userinfo_endpoint、jwks_uri这几个字段。如果哪个地址缺失后面流程必然有一环会断掉。我常用命令行的方式快速看返回结果curl https://sso.example.com/.well-known/openid-configuration看到合法的 JSON 后把返回里的关键 Endpoint 和下面 GitPuk 配置比对一下。特别注意issuer字段我遇到过一类比较隐蔽的问题soular 内部访问地址是http://soular:8080但对外是https://sso.example.com导致实际下发的 ID Token 里iss是内网地址GitPuk 做校验时一看 issuer 对不上直接拒绝。解决方式通常是在 soular 的配置中显式指定对外 issuer 地址。4. 把 GitPuk 接入 soular配置步骤与联调实录4.1 GitPuk 管理后台添加认证源每个人拿到的 GitPuk 版本可能不同菜单名称也有差异但大体都在“管理后台 - 认证源 / 认证方式”这个位置。进入配置页面后选择新增 OAuth2 或 OIDC 认证源把刚才在 soular 里拿到的信息填进去。关键项包括认证源名称、Client ID、Client Secret、Authorization Endpoint、Token Endpoint、UserInfo Endpoint 和 Scopes。如果你使用的 GitPuk 支持 OIDC Discovery 方式那么只需要填一个 Discovery URL也就是上面提到的https://sso.example.com/.well-known/openid-configuration它会自动拉取其余地址。能用 Discovery 就尽量用手工维护一套 Endpoint 地址后期 soular 升级或者迁移域名时非常容易漏改。配置表单里还有一个“允许通过该认证源自动创建用户”之类的选项建议默认开启。原因是集成初期GitPuk 本地没有 soular 用户对应的账号如果不允许自动创建用户从 soular 登录成功后会看到一个“用户不存在”的错误体验很差。开启自动创建后GitPuk 会用 soular 返回的用户信息自动建立本地账号。等运行稳定了再根据安全要求决定是否关闭这个开关改为通过用户同步接口提前创建。4.2 一条正确的登录链路应该长什么样配置完成后做联调时可以用一个尚未在 GitPuk 里创建过的测试账号走完整条链路预期过程如下浏览器访问https://git.example.com/user/login点击“使用 soular 登录”按钮请求被重定向到https://sso.example.com/...浏览器地址栏域名变化如果尚未登录过 soular会出现统一登录页面输入 soular 账号密码登录成功后浏览器收到 302 跳转回到https://git.example.com/user/oauth2/soular/callback?codexxxGitPuk 后端拿 code 请求 soular 的 Token Endpoint换取 ID TokenGitPuk 解析 ID Token确认邮件或用户名自动创建本地账号浏览器跳转到 GitPuk 首页此时右上角已经显示该用户信息。如果每步都正常说明链路已经通了。第 4 步的code是一次性的原则上只能使用一次如果 GitPuk 因为网络超时重复使用同一个 codesoular 会返回invalid_grant。这属于正常的安全机制不是 bug排查时要能判断出来。4.3 首次登录后用户角色权限怎样定很多团队在打通统一登录后会忽略一个关键设定通过 soular 自动创建出来的用户在 GitPuk 里默认是什么角色如果默认是普通用户那没问题但如果默认是管理员相当于任何能登录 soular 的人都能管理 GitPuk这是非常严重的越权风险。我经历过一次小事故就是因为自动创建的用户默认权限过高导致一位新同事登录后能进后台看到全局配置。解决方式是在 GitPuk 的认证源配置里找到“新用户默认角色”设置为普通用户再通过后续的手动授权或者用户组映射来提升权限。另一个方案是先禁用自动创建提前从 soular 导出用户列表通过 GitPuk 提供的用户导入接口批量创建创建时直接指定角色这样权限在登录前就已经确定。4.4 统一登入和本地管理员账号如何共存一个现实的问题是soular 打通之后原本 GitPuk 里的管理员账号怎么办。直接删除风险很大万一 soular 临时故障本地管理员账号反而成了救命的逃生通道。我的建议是保留一个强密码的本地管理员并只允许从内网访问平时不使用。这个账号类似于机房里的带外管理口不需要出现在日常登录页上但绝不能没有。团队里可以约定当 soular 不可用时通过本地管理员登录 GitPuk 排查认证源配置。不过本地管理员也要纳入定期改密范围不能因为“没人用”就不管它。5. 用户同步和权限映射的进阶玩法5.1 soular 用户到 GitPuk 的自动同步思路OAuth2/OIDC 解决了“认证”的问题但“用户从哪来”如果只依靠首次登录时自动创建还是不够主动。比如你希望某个项目团队在第一天就能访问 GitPuk而不是等每个人手动登录一次后才生效就需要做用户同步。常见的同步方式有两种一种是 soular 侧支持 SCIM 协议把用户和组织结构推送到 GitPuk 的服务端另一种是定时任务读取 soular 的用户 API再调用 GitPuk 的管理接口批量创建用户。如果团队规模不大我更推荐第二种因为实现起来直观而且对 GitPuk 没有额外协议要求。写定时任务时要注意幂等性已经存在的用户要跳过离职的用户标记禁用而不是删除因为删除账号会导致历史提交记录失去用户名关联。5.2 用用户组映射控制 GitPuk 组织权限GitPuk 自身的权限模型通常分组织、仓库两层组织里可以设置 Owner、Member 等角色仓库里再单独设置读、写、管理员权限。如果每个用户都手动分配又回到了台账管理的老路。更好的做法是在 soular 里维护好用户组例如gitpuk-project-a-core、gitpuk-project-a-readonly然后在 GitPuk 侧把认证源带来的组信息和本地团队做映射。有些 GitPuk 支持直接从 OIDC Token 的groups断言里读取用户组并据此自动化分配角色。如果 Token 里没有组信息也可以让 soular 在 UserInfo 接口里额外返回groups字段。这里必须注意组名要做严格校验避免把 soular 内部的管理组误映射到 GitPuk 的管理员角色上。5.3 一个适合中小团队的权限矩阵参考建议在集成初期就把权限矩阵定下来而不是等出问题再补。结合实际团队规模我习惯用下面的矩阵作为起点身份GitPuk 角色说明普通研发普通成员可以浏览和克隆有权限的仓库核心开发者仓库写入者在特定仓库上有 Push 权限技术 Leader组织 Owner管理项目成员与分支保护规则运维 / 管理员GitPuk 管理员负责全局配置和认证源维护把这个矩阵落到 GitPuk 和 soular 的组映射配置里后账号开通和权限调整都不再需要进入 GitPuk 后台逐个人点直接在 soular 里把人加入对应组下次登录权限就生效了。要注意的是组映射通常不是即时生效的取决于 GitPuk 更新用户信息的时间点如果想让权限立刻生效可以要求用户退出重新登录。6. 真实联调遇到的问题与排查方法6.1 登录跳转后提示 redirect_uri 不匹配这是一个极其常见的问题。现象是点击登录跳转到 soular 后页面提示类似Invalid redirect_uri的错误。通常原因是 soular 里登记的地址和 GitPuk 实际生成的回调地址不一致。排查思路打开浏览器开发者工具在重定向请求里找到redirect_uri参数把它和 soular 后台登记的地址逐字符对比。最常见的问题是结尾少了/、用了http而不是https、或者回调路径里包含了额外的项目名。把两边的地址完全改成一致后问题基本就消失了。6.2 登录成功后返回 GitPuk 却未建立会话有时整个跳转链路看起来没有报错日志里也能看到授权码交换成功但用户回来后仍然处于未登录状态。这种情况要先看 GitPuk 日志里对 ID Token 的解析结果。一个高频原因是email字段为空或者 GitPuk 配置里要求的唯一标识字段在 Token 中不存在。可以对比一下 soular 上该用户的邮箱地址和 GitPuk 本地用户的邮箱地址如果你以前用 GitPuk 注册过上线的邮箱后来在 soular 里换了新邮箱那么自动匹配就会失败。还有一种原因是 GitPuk 配置里打开了“验证邮箱已存在”之类的选项而返回的邮箱没有通过校验也会导致登录中断。6.3 会话经常掉线需要反复登录如果用户每次访问 GitPuk 都像“失忆”一样刚登录成功过一次下次又要重新认证一般是会话 Cookie 的持久化设置和 Token 有效期配置不协调。GitPuk 本地会话有效期可以由管理员设置默认可能偏短。soular 侧的 Access Token 有效期也会影响重新认证频率如果 Access Token 过期后 GitPuk 没有刷新凭证只能强制用户重新跳转到 soular。建议把 GitPuk 本地会话有效期调成一个可以接受的值比如 8 小时同时开启“记住我”之类的选项或者配置 Refresh Token。这类问题不是故障而是会话策略没有按用户体验调整。6.4 时钟漂移导致 Token 校验失败OIDC 的 ID Token 里带有iat和exp时间戳GitPuk 校验时会和当前服务器时间对比。如果 GitPuk 所在服务器的时间与 soular 服务器时间偏差过大Token 会被判定为“未生效”或“已过期”。排查方法是先确认两台服务器的 NTP 同步状态。很多内网服务器为了安全禁用了外网 NTP又没有配置内网时间源积累一段时间后偏差可能达到几分钟。修复办法是把 GitPuk 和 soular 都指向同一个内网时间服务器另外启动一个简单的验证把服务器当前时间与手机时间对比一下就能快速判断是否偏了。6.5 集成过程中的典型问题速查表现象可能原因解决方向跳转 soular 后报 redirect_uri 错误回调地址不一致对比两端完整 URL授权码无效 / invalid_grantcode 已过期或重复使用重新发起登录检查网络时间登录成功但 GitPuk 不识别用户email 或用户名不匹配检查 UserInfo 返回字段页面频繁回到登录页会话过期策略过短调长本地会话并配置刷新令牌Token 解析报签名错误证书或 JWKS 获取失败检查 soular 证书链与域名首页提示没有权限默认角色太低在认证源处调整新用户角色7. 上线后的运营收尾体验优化与逃生方案集成完成不是终点真正考验人的是后续的日常运营。先做一遍全局检查确认登录页没有残留多余入口如果 GitPuk 支持关闭本地注册功能一定要关掉避免有人绕过 soular 建立一套影子账号否则统一登入相当于白做。接着要把 GitPuk 后台的审计日志和 soular 的登录日志接入到团队的日志系统里这样每次登录成功或失败都能追溯到源头。如果这两个系统的日志格式差异较大建议至少把时间戳格式对齐统一成 ISO8601 的 UTC 时间否则后面查跨系统问题时时间差会让人怀疑人生。上线后最好安排一次全员演练让团队用统一账号登录一遍 GitPuk收集反馈。常见的问题是小部分老用户本地邮箱和 soular 里的邮箱不一致登录后 GitPuk 自动生成了新账号导致原有仓库权限丢失。应对策略是在正式切换前先做用户匹配把本地用户和 soular 用户的唯一标识关系批量写入减少切换带来的摩擦。我当年做切换时先让所有用户在企业微信里更新了常用邮箱然后写脚本把 GitPuk 的老邮箱批量改成新邮箱再打开统一登录整个过程只遇到个别例外。还有一条逃生经验要分享改任何认证配置前先确认自己还有一个可用的本地管理员会话。我的做法是保持一个浏览器隐身窗口用本地管理员登录着不要关掉。万一你在配置 OIDC 过程中把本地登录选项不小心关了且新配置又无法生效至少还有这个隐身窗口能救回来。如果没有预留就只能去后台改数据库或联系平台厂商非常被动。另一方面建议给 GitPuk 的认证源配置加一个“脏检查”。每次变更配置前先截图保存原有所有参数。因为这个配置页面一旦保存成功旧配置就会被覆盖而一个字段填错可能导致整站所有人都登录不进去。恢复时想不起来原来的 Client ID 或 Endpoint只能去 soular 后台重新比对耽误时间。截图加上一台跳板机上的 curl 测试脚本是成本最低的保险方案。如果团队内部有多个系统都要接 soular这次 GitPuk 的对接经验完全可以沉淀成一篇内部 SOP。把创建客户端、配置回调地址、核对 Token Endpoint、设置默认角色等步骤固化下来以后接下一个系统时直接对着操作。我在做这块时体会很深的一点是统一登录这种基础设施最怕的就是每个应用各自对接、各自踩坑最后没人能说清楚完整链路。哪怕先只跑通 GitPuk 一个系统只要把文档和脚本沉淀下来后面扩展到 CI、制品库、Wiki 系统的成本都会降低很多。
