Eclipse Che 在 Azure Kubernetes Service 上实现 OIDC 认证的实践指南

背景介绍

Eclipse Che 是一款流行的云原生集成开发环境，它允许开发者在 Kubernetes 集群上创建和管理开发工作区。在 Azure Kubernetes Service (AKS) 上部署 Eclipse Che 时，身份认证是一个关键环节。由于 AKS 原生不支持外部 OIDC 提供者，这给生产环境部署带来了挑战。

核心挑战

AKS 目前存在一个已知限制：不支持配置外部 OIDC 提供者作为集群的身份认证机制。这意味着无法直接使用企业现有的身份管理系统（如 Keycloak 等）来管理对 Eclipse Che 的访问权限。

解决方案：使用 vCluster 实现 OIDC

通过虚拟 Kubernetes 集群（vCluster）技术，我们可以绕过 AKS 的限制，实现完整的 OIDC 集成。vCluster 在现有 Kubernetes 集群之上创建一个虚拟层，允许我们自定义 API 服务器的配置，包括 OIDC 参数。

关键配置步骤

1. vCluster 配置

   在 vCluster 的 values.yaml 中，我们需要配置 API 服务器的 OIDC 参数：

api:
  image: registry.k8s.io/kube-apiserver:v1.27.1
  extraArgs:
    - --oidc-issuer-url=https://your.keycloak.domain/auth/realms/che
    - --oidc-client-id=che-client
    - --oidc-username-claim=email
    - --oidc-groups-claim=groups

2. Eclipse Che 配置

   在 CheCluster 自定义资源中，我们需要确保 OIDC 配置与 vCluster 保持一致：

spec:
  components:
    cheServer:
      extraProperties:
        CHE_OIDC_USERNAME__CLAIM: email
  networking:
    auth:
      oAuthClientName: "che-client"
      oAuthSecret: "your-client-secret"
      identityProviderURL: "https://your.keycloak.domain/auth/realms/che"

生产环境注意事项

1. 客户端类型选择：建议使用私有客户端类型，并确保 vCluster 和 Eclipse Che 使用相同的客户端配置。

2. 认证流程：可以考虑使用 kubelogin 等工具来处理 kubectl 的认证流程。

3. 权限管理：通过 ClusterRoleBinding 为特定用户组分配集群管理员权限：

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: oidc-cluster-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: Group
  name: your-admin-group

常见问题解决

如果在配置过程中遇到 401 未授权错误，建议检查以下方面：

1. 确保 vCluster 和 Eclipse Che 使用相同的 OIDC 领域、客户端和密钥
2. 验证用户名声明（username claim）配置是否一致
3. 检查客户端密钥是否正确且未过期

总结

通过在 AKS 上部署 vCluster 并配置 OIDC，我们成功绕过了 AKS 的原生限制，实现了企业级的身份认证集成。这种方案不仅适用于 AKS，也可以推广到其他不支持外部 OIDC 的 Kubernetes 环境中。对于生产环境部署，建议进行充分的测试，并考虑高可用性和安全性的最佳实践。