OAuth2-Proxy 中 Bearer Token 验证失败返回401状态码的配置方案

背景介绍

在使用 OAuth2-Proxy 作为认证代理时，开发者经常会遇到一个常见需求：当客户端通过 API 直接访问后端服务时，如果提供的 Bearer Token 无效或缺失，系统应当返回 401 状态码，而不是重定向到 OIDC 登录页面。这种场景在混合使用浏览器访问和 API 调用的应用中尤为常见。

问题现象

典型的配置组合包括 OAuth2-Proxy 和 Nginx Ingress Controller。当配置正确时：

1. 浏览器用户访问会正常重定向到 OIDC 提供方进行登录
2. API 调用携带有效 Bearer Token 时能成功访问后端

但当 API 调用携带无效或缺失的 Token 时，系统会错误地重定向到登录页面，而不是返回预期的 401 状态码。

解决方案

关键配置要点

通过分析问题根源，发现关键在于 Nginx Ingress 的注解配置。以下是解决方案的核心要点：

1. 分离前端和后端路由：需要将前端页面和 API 端点分别配置在不同的 Ingress 资源中
2. 调整认证注解：在 API 的 Ingress 配置中移除 nginx.ingress.kubernetes.io/auth-signin 注解
3. 保留必要认证：保留 nginx.ingress.kubernetes.io/auth-url 注解以确保认证检查仍然生效

配置示例

对于 API 端点的 Ingress 配置应简化为：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  annotations:
    nginx.ingress.kubernetes.io/auth-url: "https://your-domain.com/oauth2/auth"
spec:
  # 其他常规配置...

原理解析

auth-signin 注解的本意是指定错误页面位置，当认证失败时会重定向到该地址。这正是导致 API 调用被重定向到登录页面的原因。移除该注解后：

1. 认证检查仍然通过 auth-url 进行
2. 认证失败时不再有重定向逻辑
3. 系统会直接返回 401 状态码

实施建议

1. 环境隔离：建议将前端和后端部署在不同的路径或子域下
2. 测试验证：使用 Postman 或 curl 工具测试 API 端点，验证以下场景：
   • 无 Token 请求应返回 401
   • 无效 Token 请求应返回 401
   • 有效 Token 请求应返回 200 和预期数据
3. 监控日志：检查 OAuth2-Proxy 和 Nginx 日志，确认认证流程符合预期

总结

通过合理配置 Ingress 注解，可以实现 OAuth2-Proxy 对 API 调用的正确处理，使其在 Token 验证失败时返回 401 状态码而非重定向。这种方案既保持了浏览器用户的正常登录流程，又满足了 API 调用的认证需求，是混合应用场景下的理想解决方案。