oauth2-proxy 集成 SourceHut 认证提供方配置、自建实例与原理剖析【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxySourceHutsr.ht是一个面向开发者的开源托管平台其元服务meta.sr.ht提供标准 OAuth 2.0 认证能力。本文讲解如何让 oauth2-proxy 借助 SourceHut 账户完成反向代理前的身份认证从在meta.sr.ht注册 OAuth 客户端、配置回跳地址到针对自建 SourceHut 实例覆盖四个关键端点再到结合源码剖析会话补全GraphQL 拉取邮箱与用户名与令牌校验的实现细节并给出基于邮箱的访问控制方案。读完本文你将能独立把 oauth2-proxy 与 SourceHut 官方或自建实例对接起来并验证其行为。一、SourceHut 提供方的工作原理oauth2-proxy 将 SourceHut 作为内置的 Provider 之一。在源码层面它由 providers/srht.go 中的SourceHutProvider实现该结构体内嵌了通用ProviderData并声明实现了Provider接口providers/srht.go。从源码可以看到该提供方默认指向 SourceHut 官方元服务meta.sr.ht预置了四个端点与一个只读权限范围providers/srht.go端点默认值用途Login URL授权https://meta.sr.ht/oauth2/authorize发起 OAuth 授权请求Redeem URL换 tokenhttps://meta.sr.ht/oauth2/access-token用授权码换取访问令牌Profile URL用户信息https://meta.sr.ht/queryGraphQL 端点用于获取用户资料Validate URL令牌校验https://meta.sr.ht/profile校验访问令牌是否有效默认 Scopemeta.sr.ht/PROFILE:RO只读读取用户档案权限当用户以--providersourcehut启动时providers/providers.go 会命中options.SourceHutProvider分支并调用NewSourceHutProvider完成上述默认值的注入。另外需要注意providerRequiresOIDCProviderVerifier对 SourceHut 返回falseproviders/providers.go说明该提供方走的是「令牌校验 用户信息补全」的经典 OAuth 2.0 流程而非依赖 OIDC Discovery 的自动发现机制——这也正是自建实例时必须手动指定四个端点的原因。二、前置准备注册 OAuth 客户端无论使用官方meta.sr.ht还是自建实例第一步都是在 SourceHut 侧创建一个 OAuth 客户端打开https://meta.sr.ht/oauth2自建实例则为https://meta.your.instance/oauth2新建一个 OAuth client在Redirection URI回跳地址一栏填写 oauth2-proxy 的认证回调地址格式必须是https://internal.yourcompany.com/oauth2/callback其中https://internal.yourcompany.com是 oauth2-proxy 对外服务的实际域名/oauth2/callback是固定的回调路径。注册完成后记下该客户端生成的 Client ID 与 Client Secret它们将作为--client-id与--client-secret传入 oauth2-proxy。三、基础配置接入官方 SourceHut使用官方 SourceHut 元服务时不需要配置任何端点只需在启动命令中声明 provider 类型与客户端凭据./oauth2-proxy \ --providersourcehut \ --client-idyour-client-id \ --client-secretyour-client-secret \ --email-domainyourcompany.com \ --http-address0.0.0.0:4180 \ --upstreamhttp://127.0.0.1:8080 \ --cookie-secreta-secure-random-secret除--providersourcehut外其余为 oauth2-proxy 的通用参数--email-domain限定允许认证的邮箱域详见下文「访问控制」--upstream指向被保护的后端服务--cookie-secret用于加密会话 Cookie。四、接入自建 SourceHut 实例如果团队自行部署了 SourceHut则需要显式覆盖以下四个端点让 oauth2-proxy 指向自己的实例官方配置说明./oauth2-proxy \ --providersourcehut \ --client-idyour-client-id \ --client-secretyour-client-secret \ --login-urlhttps://meta.your.instance/oauth2/authorize \ --redeem-urlhttps://meta.your.instance/oauth2/access-token \ --profile-urlhttps://meta.your.instance/query \ --validate-urlhttps://meta.your.instance/profile这四个参数在 pkg/apis/options/legacy_options.go 中定义对应的命令行标志与配置文件字段映射如下命令行标志配置文件字段cfg含义--login-urllogin_url认证端点Authorization Endpoint--redeem-urlredeem_url令牌兑换端点Token Endpoint--profile-urlprofile_url资料访问端点UserInfo/GraphQL Endpoint--validate-urlvalidate_url访问令牌校验端点这些 URL 最终会在newProviderDataFromConfig中被逐个解析进ProviderDataproviders/providers.go若任一 URL 无法解析oauth2-proxy 会聚合返回错误并拒绝启动因此自建实例的地址必须书写为合法且可访问的 URL。五、会话补全与令牌校验的源码级实现在 OAuth 授权码流程完成、拿到 access token 之后SourceHutProvider 还需要把用户信息写入会话并周期性校验令牌是否仍然有效。这两件事分别由EnrichSession与ValidateSession完成providers/srht.go。5.1 通过 GraphQL 补全邮箱与用户名EnrichSession向后端ProfileURL即/query端点发送一个POST请求请求体是 GraphQL 查询{query: { me { username, email } }}并在Authorization: Bearer access_token头中携带访问令牌。返回的 JSON 形如{ data: { me: { username: bitfehler, email: chbitfehler.net } } }随后实现分别从data.me.email与data.me.username中取值写入会话的Email、PreferredUsername与User字段providers/srht.go。也就是说oauth2-proxy 用于展示登录用户名、参与邮箱过滤的字段正是通过这一次 GraphQL 请求从 SourceHut 拉取的。5.2 令牌校验的两种判定ValidateSession调用通用的validateToken并构造一个带Accept: application/json的 OIDC 风格请求头providers/srht.go、providers/util.go最终访问ValidateURL即/profile端点来确认 access token 是否有效。该行为在 providers/srht_test.go 中有对应测试覆盖当后端对/query与/profile均返回正确响应时模拟用户bitfehlerValidateSession返回true当后端不返回任何/query、/profile响应404时ValidateSession返回false。如果你在排查「登录成功后很快又失效」「用户信息为空」等问题可以优先检查这两个端点的可达性与返回格式是否与上述测试中的样例一致。六、访问控制目前仅支持基于邮箱的授权文档明确指出默认配置下任何拥有 SourceHut 账户的用户都能通过认证。若要限制访问范围目前 SourceHut 提供方仅支持基于邮箱的授权方式不支持基于组group的过滤相关说明见 Providers 索引文档。三种邮箱授权写法如下# 1. 授权某个邮箱域下的所有用户 --email-domainyourcompany.com # 2. 授权指定邮箱白名单文件每行一个邮箱地址 --authenticated-emails-file/path/to/allowed-emails.txt # 3. 放开所有邮箱域慎用相当于所有账户可登录 --email-domain*由于 SourceHut 提供方的邮箱来自/query端点返回的me.email字段因此上述过滤在自建实例下同样生效——只要自建实例正确返回了邮箱信息。七、快速验证与排障建议确认回调地址一致meta.sr.ht/oauth2中填写的 Redirection URI 必须与 oauth2-proxy 实际暴露的https://你的域名/oauth2/callback完全一致含协议与端口。确认默认端点是否适用仅在使用官方meta.sr.ht时才能省略四个 URL 参数自建实例必须全部显式指定否则会跳转到官方地址导致认证失败。验证用户信息拉取用 access token 手动请求POST https://meta.your.instance/query请求体为{query: { me { username, email } }}确认能返回邮箱与用户名。观察日志与测试参考 providers/srht_test.go 中 mock 后端的响应格式可帮助判断是 oauth2-proxy 配置问题还是 SourceHut 实例返回不符合预期。结语SourceHut 是 oauth2-proxy 内置提供方中比较「轻量」的一个它不依赖 OIDC Discovery而是通过/authorize、/access-token、/query、/profile四个固定端点完成授权、换令牌、拉资料与校验四步闭环。无论是直连官方meta.sr.ht还是接入自建实例核心都在于正确填写四个端点地址与回调 URL而访问控制方面请记住当前版本的 SourceHut 提供方只支持邮箱维度的授权--email-domain/--authenticated-emails-file。结合本文给出的源码路径与测试用例你可以快速定位并解决集成过程中遇到的大多数问题。【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考