Gogs 如何启用反向代理 HTTP 头认证（含自动注册）接入 SSO 登录
【免费下载链接】gogsThe painless way to host your own Git service项目地址: https://gitcode.com/GitHub_Trending/go/gogs
如果你的反向代理（Nginx、Caddy、Apache 等）已经通过 SSO、OAuth 或客户端证书完成了用户认证，Gogs 可以不依赖自己的登录表单，直接信任代理传入的 HTTP 头中的用户名。配合自动注册选项，首次访问的 SSO 用户会在 Gogs 中自动创建账号。本文基于 认证文档 中 "HTTP header" 一节，以及随仓库发布的 conf/app.ini 给出完整配置路径。
适用前提：
- Gogs 部署在反向代理之后，且该代理会在请求中携带已认证用户名；
- Gogs 只能通过这个可信反向代理访问（这一点决定该功能是否安全，见文末限制）。
要修改的配置
所有选项都位于 Gogs 主配置文件的[auth]段，文件为custom/conf/app.ini。仓库自带的默认配置见 conf/app.ini（第 222–232 行），四项相关设置及默认值为：
| 选项 | 默认值 | 作用 |
|---|---|---|
ENABLE_REVERSE_PROXY_AUTHENTICATION | false | 开启从请求头读取已认证用户名 |
REVERSE_PROXY_AUTHENTICATION_HEADER | X-WEBAUTH-USER | 携带用户名的 HTTP 头名称 |
ENABLE_REVERSE_PROXY_AUTO_REGISTRATION | false | 用户名在 Gogs 中不存在时自动创建账号 |
TRUSTED_PROXY_IPS | 127.0.0.0/8,::1/128 | 允许设置该认证头的 IP 或 CIDR 列表 |
启用并开启自动注册的最小配置：
[auth] ENABLE_REVERSE_PROXY_AUTHENTICATION = true REVERSE_PROXY_AUTHENTICATION_HEADER = X-WEBAUTH-USER ENABLE_REVERSE_PROXY_AUTO_REGISTRATION = true TRUSTED_PROXY_IPS = 127.0.0.0/8,::1/128关于TRUSTED_PROXY_IPS：实现上 Gogs 只信任来自这些地址的请求中的认证头（见 isRequestFromTrustedProxy），这是针对"直接访问 Gogs 时可伪造认证头冒充任意用户"问题的修复，见 CHANGELOG.md 中的安全条目。默认值只覆盖回环地址；如果你的反向代理运行在其他主机上，必须把代理的源地址（IP 或 CIDR）加进这个列表，否则头会被忽略。列表支持 CIDR 写法，单个 IP 不带掩码也可以。
反向代理一侧要做的事
前提是代理端在通过 SSO/OAuth 认证用户后，把认证用户名写入你配置的 HTTP 头再转发给 Gogs。以 Nginx 为例，在 反向代理文档 给出的server块基础上，需要给代理到 Gogs 的 location 增加一行设置该头的指令：
location / { proxy_pass http://localhost:3000; # 头名称必须与 REVERSE_PROXY_AUTHENTICATION_HEADER 一致； # 取值来自你 SSO 集成返回的已认证用户名，按实际集成的变量替换 proxy_set_header X-WEBAUTH-USER <已认证用户名>; }其中<已认证用户名>是占位符，需要你按自己的 SSO 集成提供的变量或取值方式替换，头名称保持与REVERSE_PROXY_AUTHENTICATION_HEADER一致。文档没有针对具体 SSO 产品给出代理配置，这部分由你的集成方式决定。
同时保持 反向代理文档 中的约定：custom/conf/app.ini里的EXTERNAL_URL与用户实际访问的 URL 一致；由反向代理做 TLS 终结时 Gogs 保持PROTOCOL = http。
修改app.ini后重启 Gogs 使配置生效。
如何验证
Gogs 的认证处理逻辑在 authenticatedUser，据此可以核对三种情况：
- 已存在用户：经反向代理发出携带认证头的请求，Gogs 按头中的用户名查找用户，命中即视为该用户已登录，不经过密码或 Basic Auth。
- 新用户 + 自动注册：用户名查不到且
ENABLE_REVERSE_PROXY_AUTO_REGISTRATION = true时，Gogs 自动创建一个已激活（activated）状态的账号，邮箱为占位地址（形如uuid@localhost）；用户首次登录后可自行更新邮箱。验证方式：访问后到 Gogs 用户/管理界面确认该账号已存在。 - 新用户 + 未开自动注册：账号不会创建，该请求按未认证处理。
另外可以核对安全边界：请求必须来自TRUSTED_PROXY_IPS中的地址，头才会被采信。绕过代理、直接从外部地址向 Gogs 发带X-WEBAUTH-USER头的请求，认证头会被忽略。管理面板的配置页也会展示当前的TrustedProxyIPs值（见 admin/config.tmpl），可用于确认配置已被加载。
限制与注意事项
- 官方文档的警告：只在 Gogs 完全经由可信反向代理访问时才开启此功能。若 Gogs 对互联网直接可达，任何人可通过自行设置该头冒充任意用户。
- 自动注册创建的账号使用占位邮箱，不携带 SSO 侧的真实邮箱信息；后续邮箱由用户本人登录后更新。
TRUSTED_PROXY_IPS的条目解析失败（非法 CIDR）会导致配置加载报错（见 internal/conf/conf.go），填写时确认格式为 IP 或 CIDR，多个值用逗号分隔。
完成以上配置后，SSO 用户经代理访问 Gogs 即以其身份登录，新用户按自动注册设置决定是否落库；调整代理位置或网络拓扑后，记得同步更新TRUSTED_PROXY_IPS。
【免费下载链接】gogsThe painless way to host your own Git service项目地址: https://gitcode.com/GitHub_Trending/go/gogs
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
