OAuth2 Proxy配置详解：安全身份验证代理的核心配置指南

OAuth2 Proxy配置详解：安全身份验证代理的核心配置指南

oauth2_proxy A reverse proxy that provides authentication with Google, Github or other provider 项目地址: https://gitcode.com/gh_mirrors/oa/oauth2_proxy

什么是OAuth2 Proxy

OAuth2 Proxy是一个开源的反向代理和身份验证服务，它位于您的应用程序前端，为没有内置身份验证机制的Web应用提供OAuth2认证层。它支持多种OAuth提供商(如Google、GitHub、Azure AD等)，通过简单的配置即可为应用添加身份验证功能。

核心配置解析

网络监听设置

# http_address = "127.0.0.1:4180"
# https_address = ":443"

这部分定义了OAuth2 Proxy监听的网络地址和端口。默认情况下，HTTP服务监听在127.0.0.1的4180端口，HTTPS服务监听在所有网络接口的443端口。在生产环境中，建议仅启用HTTPS监听以确保通信安全。

TLS安全配置

# tls_cert_file = ""
# tls_key_file = ""

当启用HTTPS服务时，必须配置TLS证书和私钥文件路径。这些文件通常从证书颁发机构(CA)获取，或使用Let's Encrypt等免费服务生成。

上游服务配置

# upstreams = [
#     "http://127.0.0.1:8080/"
# ]

upstreams定义了OAuth2 Proxy保护的后端服务地址。可以配置多个上游服务，OAuth2 Proxy会根据请求路径进行路由分发。

OAuth2核心参数

# client_id = "123456.apps.googleusercontent.com"
# client_secret = ""

这些是OAuth2提供商(如Google)颁发给您的应用程序的凭证。client_id是公开的标识符，而client_secret必须严格保密，不应直接写入配置文件，建议通过环境变量或密钥管理服务注入。

身份验证域控制

# email_domains = [
#     "yourcompany.com"
# ]

此配置限制只有特定域名(如yourcompany.com)的电子邮件账户才能通过认证。使用"*"允许任何邮箱地址，但生产环境中应避免这种宽松策略。

高级安全配置

请求头传递

# pass_basic_auth = true
# pass_user_headers = true
# pass_host_header = true

这些选项控制哪些请求头信息会被转发到上游服务。pass_user_headers特别有用，它会将认证用户的电子邮件和用户名通过X-Forwarded-User和X-Forwarded-Email头发送给后端应用。

访问令牌传递

# pass_access_token = false

启用此选项后，OAuth访问令牌将通过X-Forwarded-Access-Token头传递给上游服务，使后端应用能够代表用户调用OAuth提供商的API。

双重认证

# htpasswd_file = ""

除了OAuth认证外，还可以配置htpasswd文件实现用户名/密码二次认证。文件需使用htpasswd -s命令生成，采用SHA加密存储密码。

Cookie安全设置

# cookie_name = "_oauth2_proxy"
# cookie_secret = ""
# cookie_domain = ""
# cookie_expire = "168h"
# cookie_refresh = ""
# cookie_secure = true
# cookie_httponly = true

Cookie配置对安全性至关重要：

• cookie_secret应为16、24或32字节的随机字符串，用于加密Cookie
• cookie_expire设置会话有效期(默认168小时即7天)
• cookie_refresh定义令牌自动刷新间隔
• secure和httponly标志应始终启用，防止XSS和中间人攻击

最佳实践建议

1. 生产环境必须启用HTTPS：配置有效的TLS证书，禁用HTTP监听

2. 严格限制访问域：不要使用通配符(*)email_domains，明确指定允许的企业域名

3. 保护敏感信息：client_secret和cookie_secret应通过安全方式注入，而非直接写在配置文件中

4. 定期轮换凭证：定期更换client_secret和cookie_secret增强安全性

5. 监控和日志：启用request_logging监控认证请求，及时发现异常行为

6. 会话管理：根据安全要求调整cookie_expire，平衡用户体验和安全性

通过合理配置OAuth2 Proxy，您可以为内部应用快速添加企业级身份验证层，无需修改现有应用代码，同时满足现代安全合规要求。

oauth2_proxy A reverse proxy that provides authentication with Google, Github or other provider 项目地址: https://gitcode.com/gh_mirrors/oa/oauth2_proxy