ArgoCD Helm 部署中 Ingress 路径导致 OIDC 认证失败的解决方案

问题背景

在使用 ArgoCD Helm Chart 进行部署时，许多用户会选择通过 Ingress 配置自定义路径来访问 ArgoCD 实例。例如，将 ArgoCD 部署在 https://example.com/argo-cd 这样的子路径下。然而，当启用 Dex 进行 OIDC 认证时，系统默认生成的认证回调 URL 会忽略这个基础路径，导致认证流程失败。

问题现象

当用户配置了以下典型参数时：

global:
  domain: example.com
configs:
  params:
    server.insecure: true
    server.basehref: /argo-cd
    server.rootpath: /argo-cd

OIDC 认证流程会尝试重定向到错误的回调地址 https://example.com/api/dex/callback，而正确的地址应该是 https://example.com/argo-cd/api/dex/callback。这种不匹配会导致认证失败，并返回 404 错误。

根本原因

ArgoCD 的 Helm Chart 在默认配置下，Dex 认证回调 URL 的生成逻辑没有充分考虑 Ingress 的基础路径设置。虽然 server.basehref 和 server.rootpath 参数可以控制应用层面的路径，但它们不会自动影响 Dex 的回调 URL 生成。

解决方案

通过显式配置 configs.cm.url 参数可以解决这个问题：

configs:
  cm:
    url: https://example.com/argo-cd

这个参数会强制 Dex 使用包含基础路径的完整 URL 来生成认证回调地址。值得注意的是，这个关键参数在默认的 values.yaml 文件中并未提及，在官方文档中也没有特别说明。

最佳实践建议

1. 完整路径配置：当使用子路径部署时，建议同时配置以下参数：

   configs:
     params:
       server.basehref: /your-path
       server.rootpath: /your-path
     cm:
       url: https://your-domain.com/your-path
   

2. 安全考虑：确保同时配置正确的 TLS 设置，避免在回调过程中出现安全警告。

3. 测试验证：部署后，应该检查以下端点是否可访问：

   • 主应用页面：https://your-domain.com/your-path
   • Dex 回调端点：https://your-domain.com/your-path/api/dex/callback

技术原理深入

在 Kubernetes Ingress 配置中，路径重写和代理设置可能会导致后端应用无法感知完整的请求路径。ArgoCD 需要明确知道它的外部访问地址才能正确处理各种重定向，包括：

• 静态资源加载
• API 端点访问
• OAuth/OIDC 回调

configs.cm.url 参数实际上设置了 ArgoCD 的 ARGOCD_SERVER_URL 环境变量，这个变量会被 Dex 集成模块用来构造各种绝对 URL。

总结

在子路径部署场景下，明确配置 configs.cm.url 是确保 ArgoCD 所有功能正常工作的关键步骤。这个经验不仅适用于 GitLab 作为 OIDC 提供者的情况，也同样适用于其他认证提供者如 GitHub、Google 或 Microsoft 的集成场景。