Enable Multi‑Tenant OIDC Authentication in KubeSphere Using Dex and GitLab

Introduction

KubeSphere’s multi‑tenant feature is essential for production environments where developers, operations, and testers need separate accounts with different permissions. The platform provides a built‑in OAuth service and account system, and can integrate external identity providers such as LDAP or OIDC.

Authentication Chain

Usage Scenario

Assuming a minimal KubeSphere installation, we use an OIDC provider (Dex) that connects to GitLab for authentication.

Install Dex

Dex is an OpenID Connect identity service that forwards authentication to connectors such as LDAP, SAML, GitHub, GitLab, Google, or Active Directory. It returns an OAuth2 token to the client.

1. Create an application in GitLab and select the scopes read_user profile email openid. Record the application ID and secret.

# Add Dex Helm repository
helm repo add dex https://charts.dexidp.io
# Download Dex chart
helm pull dex/dex
# Extract chart files
tar xf dex-0.5.0.tgz

2. Edit values.yaml to configure the chart (replica count, image, storage, connectors, static clients, service ports, ingress, etc.).

replicaCount: 1
image:
  repository: dexidp/dex
  pullPolicy: IfNotPresent
  tag: "v2.29.0"
config:
  issuer: https://dex-qke.lishuai.fun
  storage:
    type: kubernetes
    config:
      inCluster: true
  web:
    http: 0.0.0.0:5556
  connectors:
  - type: gitlab
    id: gitlab
    name: GitLab
    config:
      baseURL: https://gitlab.lishuai.fun
      clientID: <your-client-id>
      clientSecret: <your-client-secret>
      redirectURI: https://dex-qke.lishuai.fun/callback
      groups:
      - k8s-auth
      - k8s-auth/dashboard
      - k8s-auth/dashboard/show
  staticClients:
  - id: dex-k8s-authenticator
    name: dex-k8s-authenticator
    secret: generatedLongRandomPhrase
    redirectURIs:
    - http://kubesphere.lishuai.fun/oauth/redirect/dex

Important notes:

GitLab groups must match the project‑group that contains authorized users.

If the cluster lacks cert-manager, create the TLS secret manually.

Install Dex in the cluster:

# Create namespace
kubectl create ns dex
# Install chart
kubectl -n dex install dex dex
# Verify pod
kubectl -n dex get pod

Configure KubeSphere

After Dex is running, modify cluster-configuration.yaml in the kubesphere-system namespace to add the OIDC provider.

apiVersion: installer.kubesphere.io/v1alpha1
kind: ClusterConfiguration
metadata:
  name: ks-installer
  namespace: kubesphere-system
spec:
  authentication:
    jwtSecret: "<your‑jwt‑secret>"
    authenticateRateLimiterMaxTries: 10
    authenticateRateLimiterDuration: 10m
    oauthOptions:
      accessTokenMaxAge: 1h
      accessTokenInactivityTimeout: 30m
      identityProviders:
      - name: dex
        type: OIDCIdentityProvider
        mappingMethod: auto
        provider:
          clientID: "dex-k8s-authenticator"
          clientSecret: "generatedLongRandomPhrase"
          issuer: https://dex-qke.lishuai.fun
          redirectURL: http://kubesphere.lishuai.fun/oauth/redirect/dex
          scopes:
          - openid
          - email

Key parameter meanings: authenticateRateLimiterMaxTries – maximum consecutive login failures before the user is locked. authenticateRateLimiterDuration – time window for the above limit. loginHistoryRetentionPeriod – how long login records are kept. multipleLogin – whether a user can log in from multiple locations simultaneously. jwtSecret – secret used to sign JWT tokens (minimum 32 characters).

OAuth options details: accessTokenMaxAge – token validity period (0h for member clusters, 2h otherwise). accessTokenInactivityTimeout – idle timeout after which the token must be refreshed. identityProviders – list of external providers (e.g., GitLab).

After editing, apply the configuration:

kubectl apply -f cluster-configuration.yaml

Or edit directly:

kubectl -n kubesphere-system edit cc ks-installer

Example configuration snippet (truncated):

apiVersion: installer.kubesphere.io/v1alpha1
kind: ClusterConfiguration
metadata:
  name: ks-installer
spec:
  authentication:
    jwtSecret: "********"
    authenticateRateLimiterMaxTries: 10
    authenticateRateLimiterDuration: 10m
    oauthOptions:
      accessTokenInactivityTimeout: 30m
      accessTokenMaxAge: 1h
      identityProviders:
      - name: github
        type: GitHubIdentityProvider
        mappingMethod: auto
        provider: {}

Monitor the installer logs to ensure the changes take effect:

kubectl -n kubesphere-system logs -l app=ks-installer -f

Login Experience

After the configuration is applied, the KubeSphere login page shows a “Login via Dex” button.

Clicking the button redirects to GitLab for authentication. The first login requires authorizing the Dex application; only users belonging to the specified GitLab project group are allowed.

After authorizing, KubeSphere prompts to confirm the account information, where the username can be edited.

Finally, the user can log in, but initially has no permissions; an administrator must assign appropriate roles.