oauth2-proxy Bitbucket Provider 接入指南OAuth 配置、Team 与 Repository 访问控制【免费下载链接】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导读本文档面向需要将 oauth2-proxy 与 Bitbucket Cloud 集成的开发者系统讲解如何创建 Bitbucket OAuth consumer、配置回调地址与权限以及通过--bitbucket-team与--bitbucket-repository参数实现细粒度的登录授权限制。读完本文你将能够独立完成 Bitbucket 作为身份提供方Identity Provider的完整接入并理解其内部验证流程与源码实现方便排查授权失效等问题。一、整体原理Bitbucket 在 oauth2-proxy 中的角色oauth2-proxy 是一个反向代理负责拦截用户请求并引导其完成 OAuth 2.0 授权流程。当选择 Bitbucket 作为 Provider 时oauth2-proxy 会将未认证用户重定向到 Bitbucket 的授权端点完成登录与授权通过授权码换取 Access Token调用 Bitbucket API 校验用户身份邮箱、团队归属与仓库访问权限校验通过后写入会话Session放行后续请求。从源码看Bitbucket 相关的默认端点定义在 providers/bitbucket.go 中用途默认 URL登录端点LoginURLhttps://bitbucket.org/site/oauth2/authorize令牌交换端点RedeemURLhttps://bitbucket.org/site/oauth2/access_token用户校验端点ValidateURLhttps://api.bitbucket.org/2.0/user/emails用户资料端点ProfileURL无Bitbucket 不提供 Profile URLBitbucket 默认请求的 Scope 为email对应bitbucketDefaultScope email用于读取用户的主邮箱。二、在 Bitbucket Cloud 上创建 OAuth Consumer要启用 Bitbucket 登录首先需要在 Bitbucket 侧注册一个 OAuth consumer。原文档给出的步骤如下参见 bitbucket.md新增 OAuth consumer在 Bitbucket 的 OAuth on Bitbucket Cloud 管理页面创建一个新的 OAuth consumer配置回调地址Callback URL填写https://oauth2-proxy/oauth2/callback其中oauth2-proxy需替换为 oauth2-proxy 实际对外暴露的主机名。这是 OAuth 授权完成后 Bitbucket 回调 oauth2-proxy 的地址必须与 oauth2-proxy 实际监听路径/oauth2/callback完全匹配选择权限Permissions在权限Permissions部分至少勾选Account → Email读取用户主邮箱用于身份标识Team membership → Read当使用--bitbucket-team限制登录范围时需要该权限读取用户的团队归属Repositories → Read当使用--bitbucket-repository限制登录范围时需要该权限读取用户对仓库的访问权限记录凭证创建完成后记下生成的Client ID与Client Secret稍后填入 oauth2-proxy 配置。权限选择的完整性与后续访问控制功能一一对应如果只打算做基础登录可以只选 Account → Email但只要涉及 Team 或 Repository 限制就必须同步开通对应的读取权限否则验证接口会返回 403 而拒绝登录。三、基础运行参数启用 Bitbucket Provider在 oauth2-proxy 启动参数中传入以下三个选项即可启用 Bitbucket 登录--providerbitbucket --client-idClient ID --client-secretClient Secret参数说明参数说明--providerbitbucket指定使用 Bitbucket Provider对应源码 providers.go 中的BitbucketProvider类型bitbucket--client-idBitbucket OAuth consumer 的 Client ID--client-secretBitbucket OAuth consumer 的 Client Secret从源码看--client-id与--client-secret最终写入ProviderData而--providerbitbucket会在 providers/providers.go 的工厂函数中被分派到NewBitbucketProvider由它完成默认端点和默认 Scope 的初始化。默认行为重要在未配置任何额外限制参数时所有拥有 Bitbucket 账号的用户都可以通过认证登录。这意味着只要用户能完成 Bitbucket OAuth 授权就会被放行。若你的应用只对内部团队成员开放务必配置下一节的访问控制参数。四、访问控制限制为 Team 成员或仓库协作者默认配置放行所有 Bitbucket 用户这在大多数内部场景下过宽。oauth2-proxy 为此提供了两个专用的访问控制参数4.1 限制为指定 Team 成员--bitbucket-teamTeam name作用仅允许指定 Team 的成员登录Team name使用 Bitbucket 上的团队名称用户名而非显示名称生效逻辑开启后oauth2-proxy 在验证阶段会额外请求https://api.bitbucket.org/2.0/teams?rolemember遍历返回的团队列表若用户不属于目标团队则拒绝登录。4.2 限制为指定仓库的访问者--bitbucket-repositoryRepository name作用仅允许能访问指定仓库的用户登录Repository name使用形如workspace/repo-slug的完整仓库全名full_name例如myteam/myapp生效逻辑开启后oauth2-proxy 会请求https://api.bitbucket.org/2.0/repositories/workspace?rolecontributorqfull_namerepo通过过滤查询确认用户对该仓库具有 contributor协作者及以上权限。4.3 参数组合使用两个参数可以同时使用此时用户必须同时满足“是目标 Team 成员”且“对目标仓库有访问权限”才会放行AND 关系。权限校验顺序固定为先校验 Team 归属再校验仓库访问最后返回主邮箱。这两个参数在遗留配置体系Legacy Options中定义于 legacy_options.goflagSet.String(bitbucket-team, , restrict logins to members of this team) flagSet.String(bitbucket-repository, , restrict logins to user with access to this repository)同时它们也支持通过环境变量OAUTH2_PROXY_BITBUCKET_TEAM、OAUTH2_PROXY_BITBUCKET_REPOSITORY注入便于容器化部署。五、源码级解析Scope 自动调整与验证流程理解内部的实现细节有助于在配置后快速定位问题。5.1 Scope 随限制参数自动扩展在 bitbucket.go 的NewBitbucketProvider中默认 Scope 为email。当你配置了--bitbucket-team时setTeam方法会自动把team追加进 Scopefunc (p *BitbucketProvider) setTeam(team string) { p.Team team if !strings.Contains(p.Scope, team) { p.Scope team } }同理配置--bitbucket-repository时setRepository会自动追加repositoryScopefunc (p *BitbucketProvider) setRepository(repository string) { p.Repository repository if !strings.Contains(p.Scope, repository) { p.Scope repository } }因此仅配置--providerbitbucketScope 为email追加--bitbucket-teamScope 变为email team追加--bitbucket-repositoryScope 变为email repository两者都配置Scope 为email team repository。对应的单元测试见 bitbucket_test.go 中的TestBitbucketProviderScopeAdjustForTeam与TestBitbucketProviderScopeAdjustForRepository分别断言 Scope 被调整为email team与email repository。5.2 验证阶段的三步请求GetEmailAddress是 Bitbucket Provider 的核心验证函数bitbucket.go其执行顺序如下获取邮箱请求/2.0/user/emails?access_token...解析返回的邮箱列表取is_primarytrue的那一条作为用户身份标识可选校验 Team请求/2.0/teams?rolememberaccess_token...遍历团队列表比对p.Team未命中则记录日志 team membership test failed, access denied 并返回空邮箱登录被拒绝可选校验仓库请求/2.0/repositories/workspace?rolecontributorqfull_name...access_token...比对返回的full_name与p.Repository未命中则记录日志 repository access test failed, access denied 并拒绝登录。这里的逻辑对应测试TestBitbucketProviderGetEmailAddress仅校验邮箱与TestBitbucketProviderGetEmailAddressAndGroup同时校验团队归属测试通过模拟 HTTP 后端返回{email: ..., is_primary: true}来验证解析与授权行为。5.3 认证失败的表现当验证失败时GetEmailAddress返回空字符串且 error 为 nil团队/仓库未命中场景或返回错误请求本身失败场景。oauth2-proxy 会据此判定用户未通过认证并拒绝其访问同时日志中会输出上述 access denied 提示便于运维排查。六、Alpha 配置格式YAML如果项目启用了 Alpha 配置--alpha-configBitbucket 的配置等价写法如下字段定义见 alpha_config.md 的BitbucketOptions一节providers: - id: bitbucket provider: bitbucket clientID: Client ID clientSecret: Client Secret bitbucketConfig: team: Team name # 可选限制为团队成员 repository: Repository name # 可选限制为仓库协作者BitbucketOptions在源码 providers.go 中定义字段类型说明teamstring限制登录为指定团队的成员对应--bitbucket-teamrepositorystring限制登录为可访问指定仓库的用户对应--bitbucket-repository七、完整示例与实战建议7.1 仅开放 Bitbucket 登录全员可登录--providerbitbucket --client-idyour-client-id --client-secretyour-client-secret --email-domain* --upstreamhttp://127.0.0.1:8080 --http-address0.0.0.0:4180 --cookie-secret...注意--email-domain*表示接受任意域名邮箱Bitbucket 场景常用若希望进一步按邮箱域名过滤可改为具体的域名列表。--cookie-secret用于加密会话 Cookie生产环境必须配置。7.2 仅允许某团队登录--providerbitbucket --client-idyour-client-id --client-secretyour-client-secret --bitbucket-teammy-dev-team7.3 仅允许能访问某仓库的用户登录--providerbitbucket --client-idyour-client-id --client-secretyour-client-secret --bitbucket-repositorymy-org/my-private-repo7.4 实战建议回调地址必须 HTTPS 一致Bitbucket OAuth consumer 中配置的回调地址应与 oauth2-proxy 对外实际地址严格一致含协议与端口否则授权回调会失败权限与限制参数配套使用--bitbucket-team/--bitbucket-repository时务必在 Bitbucket consumer 权限中勾选 Team membership → Read 与 Repositories → Read否则校验请求会被 Bitbucket API 以 403 拒绝网络可达性oauth2-proxy 所在环境必须能访问bitbucket.org与api.bitbucket.org若存在代理或防火墙需提前放行日志排障验证失败时日志会输出 team membership test failed, access denied 或 repository access test failed, access denied可直接据此判断是权限不足还是参数填错。八、总结接入 Bitbucket 只需三步创建 OAuth consumer配好回调地址与权限→ 填入--providerbitbucket、--client-id、--client-secret→ 按需追加--bitbucket-team/--bitbucket-repository收紧登录范围默认放开所有 Bitbucket 用户生产环境建议通过 Team 或 Repository 参数限定授权范围限制参数会触发 Scope 自动扩展与额外的 Bitbucket API 校验理解 bitbucket.go 中的三步验证流程邮箱 → Team → 仓库有助于快速定位授权问题测试用例集中在 bitbucket_test.go可作为验证默认端点、Scope 调整与邮箱解析行为的参考。据此配置即可将 Bitbucket Cloud 作为可靠的统一身份来源为内部系统提供基于 OAuth 2.0 的反向代理认证保护。【免费下载链接】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），仅供参考 oauth2-proxy Bitbucket Provider 接入指南：OAuth 配置、Team 与 Repository 访问控制
oauth2-proxy Bitbucket Provider 接入指南OAuth 配置、Team 与 Repository 访问控制【免费下载链接】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导读本文档面向需要将 oauth2-proxy 与 Bitbucket Cloud 集成的开发者系统讲解如何创建 Bitbucket OAuth consumer、配置回调地址与权限以及通过--bitbucket-team与--bitbucket-repository参数实现细粒度的登录授权限制。读完本文你将能够独立完成 Bitbucket 作为身份提供方Identity Provider的完整接入并理解其内部验证流程与源码实现方便排查授权失效等问题。一、整体原理Bitbucket 在 oauth2-proxy 中的角色oauth2-proxy 是一个反向代理负责拦截用户请求并引导其完成 OAuth 2.0 授权流程。当选择 Bitbucket 作为 Provider 时oauth2-proxy 会将未认证用户重定向到 Bitbucket 的授权端点完成登录与授权通过授权码换取 Access Token调用 Bitbucket API 校验用户身份邮箱、团队归属与仓库访问权限校验通过后写入会话Session放行后续请求。从源码看Bitbucket 相关的默认端点定义在 providers/bitbucket.go 中用途默认 URL登录端点LoginURLhttps://bitbucket.org/site/oauth2/authorize令牌交换端点RedeemURLhttps://bitbucket.org/site/oauth2/access_token用户校验端点ValidateURLhttps://api.bitbucket.org/2.0/user/emails用户资料端点ProfileURL无Bitbucket 不提供 Profile URLBitbucket 默认请求的 Scope 为email对应bitbucketDefaultScope email用于读取用户的主邮箱。二、在 Bitbucket Cloud 上创建 OAuth Consumer要启用 Bitbucket 登录首先需要在 Bitbucket 侧注册一个 OAuth consumer。原文档给出的步骤如下参见 bitbucket.md新增 OAuth consumer在 Bitbucket 的 OAuth on Bitbucket Cloud 管理页面创建一个新的 OAuth consumer配置回调地址Callback URL填写https://oauth2-proxy/oauth2/callback其中oauth2-proxy需替换为 oauth2-proxy 实际对外暴露的主机名。这是 OAuth 授权完成后 Bitbucket 回调 oauth2-proxy 的地址必须与 oauth2-proxy 实际监听路径/oauth2/callback完全匹配选择权限Permissions在权限Permissions部分至少勾选Account → Email读取用户主邮箱用于身份标识Team membership → Read当使用--bitbucket-team限制登录范围时需要该权限读取用户的团队归属Repositories → Read当使用--bitbucket-repository限制登录范围时需要该权限读取用户对仓库的访问权限记录凭证创建完成后记下生成的Client ID与Client Secret稍后填入 oauth2-proxy 配置。权限选择的完整性与后续访问控制功能一一对应如果只打算做基础登录可以只选 Account → Email但只要涉及 Team 或 Repository 限制就必须同步开通对应的读取权限否则验证接口会返回 403 而拒绝登录。三、基础运行参数启用 Bitbucket Provider在 oauth2-proxy 启动参数中传入以下三个选项即可启用 Bitbucket 登录--providerbitbucket --client-idClient ID --client-secretClient Secret参数说明参数说明--providerbitbucket指定使用 Bitbucket Provider对应源码 providers.go 中的BitbucketProvider类型bitbucket--client-idBitbucket OAuth consumer 的 Client ID--client-secretBitbucket OAuth consumer 的 Client Secret从源码看--client-id与--client-secret最终写入ProviderData而--providerbitbucket会在 providers/providers.go 的工厂函数中被分派到NewBitbucketProvider由它完成默认端点和默认 Scope 的初始化。默认行为重要在未配置任何额外限制参数时所有拥有 Bitbucket 账号的用户都可以通过认证登录。这意味着只要用户能完成 Bitbucket OAuth 授权就会被放行。若你的应用只对内部团队成员开放务必配置下一节的访问控制参数。四、访问控制限制为 Team 成员或仓库协作者默认配置放行所有 Bitbucket 用户这在大多数内部场景下过宽。oauth2-proxy 为此提供了两个专用的访问控制参数4.1 限制为指定 Team 成员--bitbucket-teamTeam name作用仅允许指定 Team 的成员登录Team name使用 Bitbucket 上的团队名称用户名而非显示名称生效逻辑开启后oauth2-proxy 在验证阶段会额外请求https://api.bitbucket.org/2.0/teams?rolemember遍历返回的团队列表若用户不属于目标团队则拒绝登录。4.2 限制为指定仓库的访问者--bitbucket-repositoryRepository name作用仅允许能访问指定仓库的用户登录Repository name使用形如workspace/repo-slug的完整仓库全名full_name例如myteam/myapp生效逻辑开启后oauth2-proxy 会请求https://api.bitbucket.org/2.0/repositories/workspace?rolecontributorqfull_namerepo通过过滤查询确认用户对该仓库具有 contributor协作者及以上权限。4.3 参数组合使用两个参数可以同时使用此时用户必须同时满足“是目标 Team 成员”且“对目标仓库有访问权限”才会放行AND 关系。权限校验顺序固定为先校验 Team 归属再校验仓库访问最后返回主邮箱。这两个参数在遗留配置体系Legacy Options中定义于 legacy_options.goflagSet.String(bitbucket-team, , restrict logins to members of this team) flagSet.String(bitbucket-repository, , restrict logins to user with access to this repository)同时它们也支持通过环境变量OAUTH2_PROXY_BITBUCKET_TEAM、OAUTH2_PROXY_BITBUCKET_REPOSITORY注入便于容器化部署。五、源码级解析Scope 自动调整与验证流程理解内部的实现细节有助于在配置后快速定位问题。5.1 Scope 随限制参数自动扩展在 bitbucket.go 的NewBitbucketProvider中默认 Scope 为email。当你配置了--bitbucket-team时setTeam方法会自动把team追加进 Scopefunc (p *BitbucketProvider) setTeam(team string) { p.Team team if !strings.Contains(p.Scope, team) { p.Scope team } }同理配置--bitbucket-repository时setRepository会自动追加repositoryScopefunc (p *BitbucketProvider) setRepository(repository string) { p.Repository repository if !strings.Contains(p.Scope, repository) { p.Scope repository } }因此仅配置--providerbitbucketScope 为email追加--bitbucket-teamScope 变为email team追加--bitbucket-repositoryScope 变为email repository两者都配置Scope 为email team repository。对应的单元测试见 bitbucket_test.go 中的TestBitbucketProviderScopeAdjustForTeam与TestBitbucketProviderScopeAdjustForRepository分别断言 Scope 被调整为email team与email repository。5.2 验证阶段的三步请求GetEmailAddress是 Bitbucket Provider 的核心验证函数bitbucket.go其执行顺序如下获取邮箱请求/2.0/user/emails?access_token...解析返回的邮箱列表取is_primarytrue的那一条作为用户身份标识可选校验 Team请求/2.0/teams?rolememberaccess_token...遍历团队列表比对p.Team未命中则记录日志 team membership test failed, access denied 并返回空邮箱登录被拒绝可选校验仓库请求/2.0/repositories/workspace?rolecontributorqfull_name...access_token...比对返回的full_name与p.Repository未命中则记录日志 repository access test failed, access denied 并拒绝登录。这里的逻辑对应测试TestBitbucketProviderGetEmailAddress仅校验邮箱与TestBitbucketProviderGetEmailAddressAndGroup同时校验团队归属测试通过模拟 HTTP 后端返回{email: ..., is_primary: true}来验证解析与授权行为。5.3 认证失败的表现当验证失败时GetEmailAddress返回空字符串且 error 为 nil团队/仓库未命中场景或返回错误请求本身失败场景。oauth2-proxy 会据此判定用户未通过认证并拒绝其访问同时日志中会输出上述 access denied 提示便于运维排查。六、Alpha 配置格式YAML如果项目启用了 Alpha 配置--alpha-configBitbucket 的配置等价写法如下字段定义见 alpha_config.md 的BitbucketOptions一节providers: - id: bitbucket provider: bitbucket clientID: Client ID clientSecret: Client Secret bitbucketConfig: team: Team name # 可选限制为团队成员 repository: Repository name # 可选限制为仓库协作者BitbucketOptions在源码 providers.go 中定义字段类型说明teamstring限制登录为指定团队的成员对应--bitbucket-teamrepositorystring限制登录为可访问指定仓库的用户对应--bitbucket-repository七、完整示例与实战建议7.1 仅开放 Bitbucket 登录全员可登录--providerbitbucket --client-idyour-client-id --client-secretyour-client-secret --email-domain* --upstreamhttp://127.0.0.1:8080 --http-address0.0.0.0:4180 --cookie-secret...注意--email-domain*表示接受任意域名邮箱Bitbucket 场景常用若希望进一步按邮箱域名过滤可改为具体的域名列表。--cookie-secret用于加密会话 Cookie生产环境必须配置。7.2 仅允许某团队登录--providerbitbucket --client-idyour-client-id --client-secretyour-client-secret --bitbucket-teammy-dev-team7.3 仅允许能访问某仓库的用户登录--providerbitbucket --client-idyour-client-id --client-secretyour-client-secret --bitbucket-repositorymy-org/my-private-repo7.4 实战建议回调地址必须 HTTPS 一致Bitbucket OAuth consumer 中配置的回调地址应与 oauth2-proxy 对外实际地址严格一致含协议与端口否则授权回调会失败权限与限制参数配套使用--bitbucket-team/--bitbucket-repository时务必在 Bitbucket consumer 权限中勾选 Team membership → Read 与 Repositories → Read否则校验请求会被 Bitbucket API 以 403 拒绝网络可达性oauth2-proxy 所在环境必须能访问bitbucket.org与api.bitbucket.org若存在代理或防火墙需提前放行日志排障验证失败时日志会输出 team membership test failed, access denied 或 repository access test failed, access denied可直接据此判断是权限不足还是参数填错。八、总结接入 Bitbucket 只需三步创建 OAuth consumer配好回调地址与权限→ 填入--providerbitbucket、--client-id、--client-secret→ 按需追加--bitbucket-team/--bitbucket-repository收紧登录范围默认放开所有 Bitbucket 用户生产环境建议通过 Team 或 Repository 参数限定授权范围限制参数会触发 Scope 自动扩展与额外的 Bitbucket API 校验理解 bitbucket.go 中的三步验证流程邮箱 → Team → 仓库有助于快速定位授权问题测试用例集中在 bitbucket_test.go可作为验证默认端点、Scope 调整与邮箱解析行为的参考。据此配置即可将 Bitbucket Cloud 作为可靠的统一身份来源为内部系统提供基于 OAuth 2.0 的反向代理认证保护。【免费下载链接】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），仅供参考