Skip to main content

Other (Dex)

vCluster Platform supports a variety of other auth providers. You can follow this generic guide to configure SSO for any of the auth providers, including:

  • OpenShift
  • LinkedIn
  • AuthProxy
  • Bitbucket Cloud
  • Atlassian Crowd
  • Gitea

  1. Choose DEX_HOSTNAME And Configure DNS

    vCluster Platform uses the CNCF project dex for single sign-on.

    The easiest case is this one:

    • $VCLUSTER_PRO_HOSTNAME = vcluster-platform.mycompany.tld (where vCluster Platform is running)
    • $DEX_HOSTNAME = dex.mycompany.tld (where dex should be running)

  2. Create Dex Config For $OTHER_PROVIDER

    Create the file dex-config.yaml with the following dex configuration:

    ingress:
      enabled: true
      hosts:
      - host: dex.yourcompany.tld                             # Use $DEX_HOSTNAME
        paths:
          - path: /
    config:
      issuer: https://dex.yourcompany.tld                     # "https://" + $DEX_HOSTNAME
      connectors:
      - {YOUR_CONNECTOR_CONFIG}                               # SEE LINKS BELOW! (do not remove the '-' and indent correctly)
      staticClients:
      - name: Loft
        id: loft                                              # Define a $DEX_CLIENT_ID
        secret: XXXXXXXXXXXXXX                                # Define a $DEX_CLIENT_SECRET (can be any secret key)
        redirectURIs:
        - 'https://vcluster-platform.mycompany.tld/auth/oidc/callback'     # vCluster Platform URL + /auth/oidc/callback
      oauth2:
        skipApprovalScreen: true
      web:
        http: 0.0.0.0:5556
      storage:
        type: kubernetes
        config:
          inCluster: true

    Check the official artifacthub.io page for all available options.

    To fill the connectors section shown above, go to the appropriate docs page for the auth provider you want to use in combination with dex:

  3. Deploy Dex via Helm

    After creating the file dex-config.yaml, you can now install dex via helm:

    helm install dex dex --repo https://charts.dexidp.io \
      --create-namespace --namespace dex \
      -f dex-config.yaml \
      --wait

  4. Configure vCluster Platform To Use Dex For Authentication

    To tell vCluster Platform to use dex for SSO, navigate to Admin > Config in vCluster Platform and adjust your config as shown below:

    auth:
      oidc:
        issuerUrl: https://dex.mycompany.tld # Use $DEX_HOSTNAME (see above)
        clientId: "" # Use $DEX_CLIENT_ID (see above)
        clientSecret: "" # Use $DEX_CLIENT_SECRET (see above)
        type: "github" # Optional: SSO Login Button Icon ("", github, gitlab, microsoft, google)
        usernameClaim: "email" # Optional: Which part of the dex token to use as vCluster Platform username (default: email)
        usernamePrefix: "" # Optional: Add prefix to usernameClaim for vCluster Platform username
        groupsClaim: "groups" # Optional: Add Kubernetes groups for this user
        groupsPrefix: "loft-" # Optional: Prefix for Kubernetes groups
        caFile: "" # Optional: Path to a CA cert of dex within the vCluster Platform container (default: '')

  5. Authenticate via Dex + $OTHER_PROVIDER

    After saving the new vCluster Platform configuration, vCluster Platform will restart itself and you should be able to log in via $OTHER_PROVIDER and dex.

  6. Disable Username + Password Authentication (optional)

    To disable password-based authentication, navigate to Admin > Config add these two lines to your config:

    auth:
      oidc: ...             # This is your SSO configuration (make sure this is working!)
      password:
        disabled: true      # Disable password-based authentication