ArgoCD-和-Argo-Workflows-接入-GitLab-SSO-完全实战指南
1. 前言
你的 Argo Workflows UI 是不是裸奔状态?谁都能打开 argo-flow.hua-ri.cn 看到所有工作流?
ArgoCD 有自己的登录系统,Argo Workflows 默认却没有。很多团队的做法是把 Argo Workflows 设成 --auth-mode=server,用网络隔离凑合。但一旦暴露到内网,就意味着零认证。
一句话概括:通过复用 ArgoCD 已有的 Dex + GitLab SSO,三处配置改动即可让 Argo Workflows 也拥有 GitLab 账号登录能力,无需引入额外组件。
本文基于真实生产环境实施经验,覆盖 ArgoCD 接入 GitLab SSO 和 Argo Workflows 复用 Dex 登录的完整流程。
2. 整体架构
2.1 认证链路
sequenceDiagram
participant User as 用户浏览器
participant AW as Argo Workflows
participant Dex as ArgoCD Dex
participant GL as GitLab (opsgit)
User->>AW: 访问 argo-flow.hua-ri.cn
AW->>User: 302 → Dex /auth
User->>Dex: 请求登录
Dex->>User: 302 → GitLab OAuth
User->>GL: GitLab 授权
GL->>Dex: 返回 authorization code
Dex->>Dex: 换取 token,签发 ID Token
Dex->>User: 302 → Argo Workflows /oauth2/callback
User->>AW: 携带 ID Token
AW->>AW: 验证 token,登录成功2.2 核心思路
Argo Workflows 原生支持 OIDC SSO,但需要一个 OIDC Provider。ArgoCD 自带 Dex(一个轻量 OIDC 中间件),且 Dex 已经配好了 GitLab connector。
关键洞察:Dex 支持注册多个 staticClient,我们只需要把 Argo Workflows 注册为 Dex 的一个客户端,就能复用 ArgoCD 的整个认证链路。
3. 前置条件
| 组件 | 版本要求 | 说明 |
|---|---|---|
| ArgoCD | v2.0+ | 需要 Dex Server 组件 |
| Argo Workflows | v3.0+ | 支持 --auth-mode=sso |
| GitLab | 任意版本 | 需要创建 OAuth Application |
| Kubernetes | v1.24+ | ServiceAccount token 需手动创建 |
| Dex | v2.35.0+ | 支持 staticClients[].secretEnv |
确认集群中 ArgoCD 已部署且包含 Dex Server:
kubectl get deploy -n argo | grep dex
# 应看到 argo-cd-argocd-dex-server
4. ArgoCD 接入 GitLab SSO
如果你的 ArgoCD 还没有配置 GitLab SSO,从这里开始。已配好的可跳到第 5 节。
4.1 GitLab 创建 OAuth Application
在 GitLab 上创建应用:
- 路径:Admin Area → Applications(管理员)或 User Settings → Applications(个人)
- Name:ArgoCD
- Redirect URI:
https://<你的ArgoCD域名>/api/dex/callback - Scopes:勾选
read_user、openid、profile、email
保存后记录 Application ID 和 Secret。
4.2 配置 argocd-cm
kubectl edit cm argocd-cm -n argo
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cm
namespace: argo
data:
# ArgoCD 对外访问地址
url: https://argocd.example.com
# Dex 配置
dex.config: |
connectors:
- type: gitlab
id: gitlab
name: GitLab
config:
# GitLab 服务地址
baseURL: https://gitlab.example.com
# OAuth Application ID
clientID: <your-application-id>
# OAuth Secret
clientSecret: <your-secret>
# 必须与 GitLab Application 中填写的一致
redirectURI: https://argocd.example.com/api/dex/callback
# 用于 Dex 内部(非必须,建议与 url 一致)
url: https://argocd.example.com
字段说明:
| 字段 | 含义 |
|---|---|
type | Dex connector 类型,GitLab 固定为 gitlab |
baseURL | GitLab 实例地址 |
clientID | GitLab OAuth Application ID |
clientSecret | GitLab OAuth Secret |
redirectURI | 回调地址,格式为 <ArgoCD URL>/api/dex/callback |
4.3 配置 RBAC(可选)
如果需要基于 GitLab 组进行权限控制,编辑 argocd-rbac-cm:
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-rbac-cm
namespace: argo
data:
# 从 OIDC token 中提取的 claim 字段
scopes: '[groups,preferred_username]'
policy.csv: |
# 定义角色权限
p, role:devops, applications, get, *, allow
p, role:devops, applications, sync, *, allow
p, role:devops, exec, create, */*, allow
# 将 GitLab 用户/组绑定到角色
g, your-gitlab-username, role:admin
g, your-gitlab-group, role:devops
# 未匹配规则的默认策略(空 = 无权限)
policy.default: ""
4.4 验证 ArgoCD SSO
ConfigMap 修改后 Dex 会自动热加载。访问 ArgoCD 登录页,应看到 "LOG IN VIA GITLAB" 按钮。
点击后跳转 GitLab 授权页 → 授权 → 回到 ArgoCD,登录成功。
5. Argo Workflows 接入 SSO(复用 ArgoCD Dex)
这是本文的核心部分。假设 ArgoCD + Dex + GitLab 已经正常工作。
5.1 原理
Argo Workflows 的 SSO 配置需要一个 OIDC issuer。ArgoCD 的 Dex 本身就是一个标准 OIDC Provider,其 discovery endpoint 为:
https://<ArgoCD域名>/api/dex/.well-known/openid-configuration
我们要做的:
- 在 Dex 中注册 Argo Workflows 为
staticClient - 在 Argo Workflows 中配置 SSO 指向这个 Dex
- 切换 argo-server 的 auth mode
5.2 Step 1:生成 Client Secret
Dex 和 Argo Workflows 需要共享一个 secret 来建立信任关系。
# 生成随机 secret
SECRET=$(openssl rand -hex 16)
echo "Secret: $SECRET" # 记住这个值
# 创建 K8s Secret,供 Argo Workflows 读取
kubectl -n argo create secret generic argo-workflows-sso \
--from-literal=client-id=argo-workflows \
--from-literal=client-secret=$SECRET
5.3 Step 2:给 Dex Server 注入 Secret
Dex 通过环境变量读取 staticClient 的 secret:
kubectl -n argo set env deploy/argo-cd-argocd-dex-server \
ARGO_WORKFLOWS_SSO_CLIENT_SECRET=$SECRET
Dex Pod 会自动重建。
5.4 Step 3:Dex 注册 Argo Workflows 客户端
编辑 argocd-cm,在 dex.config 中追加 staticClients 段:
dex.config: |
connectors:
- type: gitlab
id: gitlab
name: GitLab
config:
baseURL: https://gitlab.example.com
clientID: <your-client-id>
clientSecret: <your-client-secret>
redirectURI: https://argocd.example.com/api/dex/callback
url: https://argocd.example.com
# ===== 新增:注册 Argo Workflows 为 OIDC 客户端 =====
staticClients:
- id: argo-workflows
name: Argo Workflows
redirectURIs:
- https://argo-flow.example.com/oauth2/callback
secretEnv: ARGO_WORKFLOWS_SSO_CLIENT_SECRET
关键字段:
| 字段 | 说明 |
|---|---|
id | 客户端标识,需与 Argo Workflows 配置中的 client-id 一致 |
redirectURIs | Argo Workflows 的回调地址,格式固定为 <域名>/oauth2/callback |
secretEnv | 引用 Dex Pod 中的环境变量名(Step 2 设置的) |
保存后重启 Dex 使 staticClients 生效:
kubectl -n argo rollout restart deploy/argo-cd-argocd-dex-server
kubectl -n argo rollout status deploy/argo-cd-argocd-dex-server
5.5 Step 4:配置 Argo Workflows SSO
编辑 workflow-controller-configmap:
kubectl -n argo edit cm workflow-controller-configmap
添加 sso 字段:
data:
sso: |
# OIDC issuer,指向 ArgoCD 的 Dex
issuer: https://argocd.example.com/api/dex
# 引用 Step 1 创建的 Secret
clientId:
name: argo-workflows-sso
key: client-id
clientSecret:
name: argo-workflows-sso
key: client-secret
# 回调地址,必须与 staticClients 中的 redirectURIs 一致
redirectUrl: https://argo-flow.example.com/oauth2/callback
# 请求的 OIDC scopes
scopes:
- openid
- profile
- email
- groups
5.6 Step 5:创建 RBAC ServiceAccount
Argo Workflows SSO 登录后,需要一个 ServiceAccount 来映射用户权限。先创建一个"允许所有 SSO 用户"的默认账户:
apiVersion: v1
kind: ServiceAccount
metadata:
name: argo-workflows-sso-default
namespace: argo
annotations:
# expr-lang 表达式,"true" 表示匹配所有用户
workflows.argoproj.io/rbac-rule: "true"
# 优先级,数字越大优先级越高
workflows.argoproj.io/rbac-rule-precedence: "0"
---
# K8s 1.24+ 需要手动创建 token Secret
apiVersion: v1
kind: Secret
metadata:
name: argo-workflows-sso-default-token
namespace: argo
annotations:
kubernetes.io/service-account.name: argo-workflows-sso-default
type: kubernetes.io/service-account-token
kubectl apply -f argo-workflows-sso-sa.yaml
如果需要更细粒度的权限控制,可以按 GitLab group 创建多个 ServiceAccount:
apiVersion: v1
kind: ServiceAccount
metadata:
name: argo-workflows-admin
namespace: argo
annotations:
# 只有 admin 组的用户匹配此规则
workflows.argoproj.io/rbac-rule: "'admin' in groups"
workflows.argoproj.io/rbac-rule-precedence: "1"
5.7 Step 6:切换 argo-server 认证模式
kubectl -n argo patch deploy argo-server --type json \
-p '[{"op":"replace","path":"/spec/template/spec/containers/0/args","value":["server","--auth-mode=sso","--secure=false"]}]'
等待 Pod 重建完成:
kubectl -n argo rollout status deploy/argo-server
5.8 验证
# 检查 SSO redirect 是否正常
curl -s https://argo-flow.example.com/oauth2/redirect -D - -o /dev/null | head -5
期望看到 302 跳转到 Dex:
HTTP/2 302
location: https://argocd.example.com/api/dex/auth?client_id=argo-workflows&redirect_uri=...
浏览器访问 Argo Workflows,点击 LOGIN 按钮 → GitLab 授权 → 登录成功。
6. 完整配置参考(生产实例)
以下是经过验证的真实集群配置。
6.1 argocd-cm(含 Argo Workflows staticClient)
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cm
namespace: argo
data:
admin.enabled: "true"
url: https://argocd-sdk-devpre.hua-ri.cn
dex.config: |
connectors:
- type: gitlab
id: gitlab
name: GitLab
config:
baseURL: https://gitlab.hua-ri.cn
clientID: <your-gitlab-application-id>
clientSecret: <your-gitlab-application-secret>
redirectURI: https://argocd-sdk-devpre.hua-ri.cn/api/dex/callback
url: https://argocd-sdk-devpre.hua-ri.cn
users.anonymous.enabled: "false"
staticClients:
- id: argo-workflows
name: Argo Workflows
redirectURIs:
- https://argo-flow.hua-ri.cn/oauth2/callback
secretEnv: ARGO_WORKFLOWS_SSO_CLIENT_SECRET
6.2 workflow-controller-configmap(SSO 部分)
apiVersion: v1
kind: ConfigMap
metadata:
name: workflow-controller-configmap
namespace: argo
data:
sso: |
issuer: https://argocd-sdk-devpre.hua-ri.cn/api/dex
clientId:
name: argo-workflows-sso
key: client-id
clientSecret:
name: argo-workflows-sso
key: client-secret
redirectUrl: https://argo-flow.hua-ri.cn/oauth2/callback
scopes:
- openid
- profile
- email
- groups
6.3 argo-server Deployment(关键部分)
spec:
template:
spec:
containers:
- name: argo-server
image: quay.io/argoproj/argocli:v3.7.3
args:
- server
- --auth-mode=sso
- --secure=false
ports:
- containerPort: 2746
name: web
7. auth-mode 详解
Argo Workflows 支持三种认证模式,可组合使用:
| 模式 | 行为 | 适用场景 |
|---|---|---|
server | 无认证,所有请求使用 Server 自身 SA | 开发/测试、已有外部认证网关 |
client | 用户需提供 K8s ServiceAccount Token | CLI 访问、服务间调用 |
sso | OIDC SSO 登录 | 生产环境 Web UI |
组合使用的注意事项:
--auth-mode=sso --auth-mode=client:同时支持 SSO 和 Token 登录,login 页面会显示两种入口--auth-mode=sso --auth-mode=server:不推荐,server模式会覆盖sso的强制登录,等于没有认证
生产建议:只用 --auth-mode=sso。
8. 常见问题排查
8.1 登录页报错 "Failed to load version/info"
现象:登录页右下角弹出红色错误提示。
原因:前端在未认证时调用 /api/v1/info 接口被拒绝,这是 Argo Workflows v3.5+ 的已知 cosmetic issue(GitHub #12168)。
解决:忽略即可,不影响 SSO 登录功能。登录成功后错误消失。
8.2 点击 LOGIN 后报 "failed to get token"
可能原因:
-
Dex 未加载 staticClients:修改 argocd-cm 后需要重启 Dex
kubectl -n argo rollout restart deploy/argo-cd-argocd-dex-server -
Secret 不一致:Dex 环境变量中的 secret 与
argo-workflows-ssoSecret 中的client-secret不匹配# 检查 Dex 环境变量 kubectl -n argo get deploy argo-cd-argocd-dex-server -o jsonpath='{.spec.template.spec.containers[0].env}' # 检查 Secret kubectl -n argo get secret argo-workflows-sso -o jsonpath='{.data.client-secret}' | base64 -d -
redirectURL 不匹配:
workflow-controller-configmap中的redirectUrl必须与staticClients[].redirectURIs完全一致
8.3 登录成功但无权限 "no service account rule matches"
原因:缺少匹配的 RBAC ServiceAccount。
解决:创建 5.6 节中的默认 ServiceAccount。
8.4 Argo Workflows Pod 启动失败
查看日志:
kubectl -n argo logs deploy/argo-server | grep -i "sso\|error"
常见错误:
failed to verify provider: argo-server 无法访问 Dex issuer URL(网络/DNS 问题)secret not found:argo-workflows-ssoSecret 不存在或 key 名称错误
8.5 ArgoCD SSO 与 admin 登录的关系
| 登录方式 | 入口 | 是否受 Dex 配置影响 |
|---|---|---|
| admin 密码 | ArgoCD 登录页输入框 | 否,走 ArgoCD 内部认证 |
| GitLab SSO | "LOG IN VIA GITLAB" 按钮 | 是,走 Dex |
| Argo Workflows SSO | LOGIN 按钮 | 是,走 Dex |
修改 Dex 配置不会影响 admin 密码登录。
9. 多集群部署
如果有多套集群需要接入,每个集群独立执行,注意替换变量:
| 变量 | 说明 | 示例 |
|---|---|---|
| ArgoCD 域名 | 各集群的 ArgoCD 入口 | argocd-sdk-dev.hua-ri.cn |
| Argo Workflows 域名 | 各集群的 Workflows 入口 | argo-flow-dev.hua-ri.cn |
| GitLab redirectURI | ArgoCD Dex 回调 | https://<ArgoCD域名>/api/dex/callback |
| Workflows redirectUrl | Argo Workflows 回调 | https://<Workflows域名>/oauth2/callback |
| issuer | Dex OIDC endpoint | https://<ArgoCD域名>/api/dex |
每个集群的 Secret 应独立生成,不要跨集群共享。
GitLab OAuth Application 的 clientID 和 clientSecret 可以多集群共用(同一个 GitLab 实例),但 redirectURI 需要在 GitLab Application 配置中添加所有集群的回调地址。
10. 决策指南
什么时候用这个方案
- ArgoCD 已部署且有 Dex
- 团队使用 GitLab 管理代码
- 需要保护 Argo Workflows UI
- 不想引入额外认证组件
什么时候不用
- 没有 ArgoCD → 考虑直接部署 Dex 或用 oauth2-proxy
- 用 GitHub/Okta/LDAP → 把 Dex connector 类型换成对应的即可,流程相同
- 需要与公司统一登录(非 OIDC 协议)集成 → 需要在 Ingress 层做认证代理
快速决策树
flowchart TD
A[需要保护 Argo Workflows] --> B{集群有 ArgoCD?}
B -->|是| C{ArgoCD 有 Dex SSO?}
B -->|否| D[部署独立 Dex 或 oauth2-proxy]
C -->|是| E[本文方案:注册 staticClient]
C -->|否| F[先配 ArgoCD SSO,再按本文操作]11. 参考资料
| 资料 | 来源 |
|---|---|
| Argo Workflows SSO 官方文档 | https://argo-workflows.readthedocs.io/en/latest/argo-server-sso/ |
| Argo Workflows 复用 ArgoCD Dex | https://argo-workflows.readthedocs.io/en/latest/argo-server-sso-argocd/ |
| ArgoCD 用户管理文档 | https://argo-cd.readthedocs.io/en/stable/operator-manual/user-management/ |
| Dex GitLab Connector | https://dexidp.io/docs/connectors/gitlab/ |
| ArgoCD GitLab SSO 配置参考 | https://blog.csdn.net/weixin_45133467/article/details/127587190 |
| GitHub Issue: login page error | https://github.com/argoproj/argo-workflows/issues/12168 |