Skip to main content

Other (Dex)

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

    The platform uses the CNCF project dex for single sign-on.

    The easiest case is this one:

    • $VCLUSTER_PRO_HOSTNAME = vcluster-platform.mycompany.tld (where 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:

    dex-config.yaml
    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 the platform to use dex for authentication

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

    Platform OIDC config for dex
    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 platform configuration, platform is going to restart itself and you should be able to log in via $OTHER_PROVIDER and dex.

  6. Disable Username + Password Authentication (optional)

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

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