oauth2-proxy 接入 login.gov从应用注册到 JWT 签名的完整配置指南【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxylogin.gov 是美国政府为公众服务提供的 OIDC 身份提供商IdP。本文面向需要在 oauth2-proxy 中集成 login.gov 的开发者完整讲解在 login.gov 开发者控制台注册应用、生成用于客户端断言client assertion的 RSA 密钥对、启动反向代理并完成登录的每一步并深入源码解释登录流程背后的 nonce 校验、acr_values 参数与邮件验证机制。读完本文你将具备在本地或云环境Docker中端到端跑通 login.gov 认证代理的实战能力。概述login.gov 与 oauth2-proxy 的集成方式login.gov 是一个面向美国政府机构的 OIDCOpenID Connect身份提供商。作为美国政府机构你可以通过 login.gov/developers/ 上提供的联系方式与 login.gov 团队沟通了解如何获取用于集成测试和生产访问的 login.gov 账号。login.gov 官方开发者指南见 developers.login.gov不过 oauth2-proxy 已经帮你处理了除在 login.gov 控制台注册应用所需数据之外的一切工作。在 oauth2-proxy 中login.gov 是一个内置的 provider注册名为login.gov其实现位于 providers/logingov.go。从源码看provider 的默认端点与 scope 已经在构造时写死登录端点https://secure.login.gov/openid_connect/authorize令牌端点https://secure.login.gov/api/openid_connect/token用户信息端点同时用作 profile 与 validate 端点https://secure.login.gov/api/openid_connect/userinfo默认 scopeemail openid这些默认值见 providers/logingov.go测试用例TestNewLoginGovProvider在 providers/logingov_test.go 中对上述默认值做了逐一断言。前置条件与演示环境假设本文以一个演示场景展开你有一个运行在http://localhost:3000/的待保护应用proxy 启动在http://localhost:4180/并且你已经拥有一个用于测试的机构agency集成账号。以下所有配置均基于这个本地假设真实部署时请使用真实主机名并用防火墙等方式确保应用只能被 proxy 访问。第一步在 login.gov 控制台注册应用登录 login.gov 开发者控制台后注册你的应用。以下字段是注册时的关键点注册项建议值说明Identity protocolOpenid connect协议必须选择 OIDCIssuer按 login.gov 对 OIDC 的指引填写该字符串在下文统一记为${LOGINGOV_ISSUER}Public key由 2048 位 RSA 私钥生成的自签名证书.pem格式证书私钥内容记为${OAUTH2_PROXY_JWT_KEY}用于给客户端断言 JWT 签名Return to App URLhttp://localhost:4180/授权完成后的回跳地址Redirect URIshttp://localhost:4180/oauth2/callbackoauth2-proxy 的 OAuth 回调端点Attribute Bundle确保勾选email授权返回的用户属性中必须包含 email其中client-id直接使用${LOGINGOV_ISSUER}这一点与常规 OAuth 应用使用独立 client id 的习惯不同是 login.gov 的特殊约定——oauth2-proxy 源码在构造 ID Token 时也是用Issuer/Subject字段写入ClientID见 providers/logingov.go。生成自签名证书Public keylogin.gov 要求你上传一个自签名证书的公钥用于验签你的应用所签发的 JWT。快速生成方式如下openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -nodes -subj /CUS/STWashington/LDC/OGSA/OU18F/CNlocalhost生成后key.pem的内容即为${OAUTH2_PROXY_JWT_KEY}RSA 私钥PEM 格式cert.pem的自签名证书内容作为 Public key 上传到 login.gov 控制台。key.pem需要妥善保管oauth2-proxy 将用它签发用于 OAuth 令牌交换的client_assertionJWT。第二步启动 oauth2-proxy命令行方式注册完成后用下面的命令行启动 proxy./oauth2-proxy -provider login.gov \ -client-id${LOGINGOV_ISSUER} \ -redirect-urlhttp://localhost:4180/oauth2/callback \ -oidc-issuer-urlhttps://idp.int.identitysandbox.gov/ \ -cookie-securefalse \ -email-domaingsa.gov \ -upstreamhttp://localhost:3000/ \ -cookie-secretsomerandomstring12341234567890AB \ -cookie-domainlocalhost \ -skip-provider-buttontrue \ -pubjwk-urlhttps://idp.int.identitysandbox.gov/api/openid_connect/certs \ -profile-urlhttps://idp.int.identitysandbox.gov/api/openid_connect/userinfo \ -jwt-key${OAUTH2_PROXY_JWT_KEY}参数逐项说明参数作用说明-provider login.gov选择 login.gov provider对应源码loginGovProviderName常量-client-id${LOGINGOV_ISSUER}OAuth client id即注册时填写的 Issuer 字符串-redirect-urlhttp://localhost:4180/oauth2/callback回调地址必须与控制台 Redirect URIs 一致-oidc-issuer-urlhttps://idp.int.identitysandbox.gov/OIDC 发行方 URL此处为 login.gov 集成测试sandbox环境-cookie-securefalse允许非 HTTPS 环境使用 cookie本地演示必须关闭生产环境应保持 true-email-domaingsa.gov邮件域名白名单仅允许该域名的 email 通过认证-upstreamhttp://localhost:3000/上游应用地址proxy 将认证后的请求转发至此-cookie-secretsomerandomstring12341234567890ABcookie 加密密钥需满足 oauth2-proxy 的最小长度要求-cookie-domainlocalhostcookie 作用域域名与访问的 host 保持一致-skip-provider-buttontrue跳过 provider 选择页只有一个 provider 时直接跳转登录-pubjwk-url.../certslogin.gov 公钥 JWK 端点用于校验 id_token 签名-profile-url.../userinfo用户信息端点用于获取并验证 email-jwt-key${OAUTH2_PROXY_JWT_KEY}客户端断言签名私钥即key.pem内容其中-pubjwk-url、-jwt-key、-jwt-key-file是 login.gov provider 专属参数在 pkg/apis/options/providers.go 的LoginGovOptions中定义映射关系见 pkg/apis/options/legacy_options.go。参数底层行为-pubjwk-urloauth2-proxy 在验证 login.gov 返回的 id_token 时会实时拉取该端点返回的 JWKS取第一个公钥完成验签见 providers/logingov.go 的checkNonce函数。-jwt-key与-jwt-key-file二选一源码 providers/logingov.go 明确要求两者必须且只能设置一个——同时设置会报错cannot set both jwt-key and jwt-key-file options都不设置会报错login.gov provider requires a private key for signing JWTs。传入的 PEM 会通过jwt.ParseRSAPrivateKeyFromPEM解析为 RSA 私钥。第三步云环境与 Docker 部署密钥文件方式上述所有命令行参数都可以用环境变量设置方便在云/Docker 环境中使用。不过有一个容易踩坑的地方部分云环境通过 docker env-file 注入环境变量而 env-file不支持 PEM 这种多行变量。遇到这种情况时可以改用密钥文件方案在仓库顶层目录创建jwt_signing_key.pem文件内容为 PEM 格式的私钥执行 docker build构建过程会把该文件复制进镜像通过环境变量或命令行参数指定镜像内的密钥路径# 环境变量方式 OAUTH2_PROXY_JWT_KEY_FILE/etc/ssl/private/jwt_signing_key.pem # 或命令行方式 --jwt-key-file/etc/ssl/private/jwt_signing_key.pem源码中JWTKeyFile分支会调用os.ReadFile读取该路径再解析 PEM见 providers/logingov.go因此镜像内必须存在该文件。第四步验证登录流程启动成功后在浏览器访问http://localhost:4180/你应该能被重定向到 login.gov 集成测试服务器完成认证认证成功后回跳到http://localhost:4180/oauth2/callback最终被代理转发到http://localhost:3000/上的应用。真实部署时请用真实主机名替换 localhost并确保应用只能从 proxy 访问如防火墙隔离。登录背后的源码流程整个认证流程在 providers/logingov.go 中可分为三个阶段1. 构造登录 URLGetLoginURL源码在登录请求中自动附加两个参数见 providers/logingov.goacr_valueshttp://idmanagement.gov/ns/assurance/loa/1若未显式指定即认证保证级别Level of Assurancenonce随机32字符用于防重放攻击。nonce 由randSeq(32)随机生成见 providers/logingov.go。测试TestLoginGovProviderGetLoginURL对这两个参数的存在性做了断言见 providers/logingov_test.go。2. 令牌交换Redeem拿到授权码后oauth2-proxy 用你的 RSA 私钥签发一个 RS256 签名的client_assertionJWT有效期 5 分钟Issuer/Subject 为 client idAudience 为令牌端点连同code、grant_typeauthorization_code以及可选的code_verifier即 PKCEPOST 到令牌端点换取access_token与id_token见 providers/logingov.go。3. 校验与建会话checkNonceemailFromUserInfo用-pubjwk-url拉取的公钥验签 id_token并比对nonceclaim 与发起登录时发送的 nonce 是否一致见 providers/logingov.go用access_token请求 userinfo 端点要求返回的email非空且email_verified为 true否则报错见 providers/logingov.go最终组装SessionStateAccessToken、IDToken、Email并设置过期时间见 providers/logingov.go。TestLoginGovProviderSessionData完整模拟了 redeem 端点、userinfo 端点与 JWKS 端点三个 mock 服务验证了 session 中的 email 与 access token 正确写入TestLoginGovProviderBadNonce则验证了 nonce 不匹配时整个兑换流程会报错见 providers/logingov_test.go。进阶跳过 OIDC Discovery部分 provider 不支持通过 issuer URL 进行 OIDC discoveryoauth2-proxy 无法从 provider 元数据自动获取 authorization、token 和 jwks URI 端点。此时可以设置--skip-oidc-discovery并手动提供这些端点-provider oidc -client-id oauth2-proxy -client-secret proxy -redirect-url http://127.0.0.1:4180/oauth2/callback -oidc-issuer-url http://127.0.0.1:5556 -skip-oidc-discovery -login-url http://127.0.0.1:5556/authorize -redeem-url http://127.0.0.1:5556/token -oidc-jwks-url http://127.0.0.1:5556/keys -cookie-securefalse -email-domain example.com该开关对应 legacy 参数skip-oidc-discovery见 pkg/apis/options/legacy_options.go启用后 oauth2-proxy 不再尝试从 issuer 发现端点而是直接用-login-url、-redeem-url、-oidc-jwks-url提供的地址。小结login.gov 接入的关键点可以概括为三件事在控制台正确注册应用并上传自签名公钥、用key.pem或jwt_signing_key.pem文件为客户端断言提供签名私钥、按需补齐-pubjwk-url与-profile-url等专属参数。oauth2-proxy 已内置 login.gov 的默认端点与 scope配合 providers/logingov.go 中 nonce、acr_values、email 验证等安全细节你可以直接用上述命令把本地应用保护起来真实生产环境只需将 localhost 换成真实域名、开启-cookie-secure并用防火墙隔离上游应用即可。更多 provider 与配置说明可参考 docs/versioned_docs/version-7.11.x/configuration/overview.md。【免费下载链接】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），仅供参考