LDAP

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 LDAP

   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:
       - type: ldap
         id: ldap
         name: LDAP
         config:
           host: myldap.company.tld:636 # Your LDAP server hostname:port
           # insecureNoSSL: true                               # Not recommended but required if not using TLS (port 389)
           # insecureSkipVerify: true                          # Not recommended but required for self-signed certificates
           # rootCAData: ( base64 encoded PEM file )
           # startTLS: true                                    # Use ldap:// instead of ldaps:// protocol
   
           # The DN and password for an application service account. The connector uses
           # these credentials to search for users and groups. Not required if the LDAP
           # server provides access for anonymous auth.
           # Please note that if the bind password contains a `$`, it has to be saved in an
           # environment variable which should be given as the value to `bindPW`.
           bindDN: uid=serviceaccount,cn=users,dc=example,dc=com
           bindPW: password
   
           # User search maps a username and password entered by a user to a LDAP entry.
           userSearch:
             # BaseDN to start the search from. It will translate to the query
             # "(&(objectClass=person)(uid=<username>))".
             baseDN: cn=users,dc=example,dc=com
             # Optional filter to apply when searching the directory.
             filter: "(objectClass=person)"
             # username attribute used for comparing user entries. This will be translated
             # and combined with the other filter as "(<attr>=<username>)".
             username: uid
             # The following three fields are direct mappings of attributes on the user entry.
             # String representation of the user.
             idAttr: uid
             # Required. Attribute to map to Email.
             emailAttr: mail
             # Maps to display name of users. No default value.
             nameAttr: name
   
           # Group search queries for groups given a user entry.
           groupSearch:
             # BaseDN to start the search from. It will translate to the query
             # "(&(objectClass=group)(member=<user uid>))".
             baseDN: cn=groups,dc=freeipa,dc=example,dc=com
             # Optional filter to apply when searching the directory.
             filter: "(objectClass=group)"
             # Represents group name.
             nameAttr: name
             # Following list contains field pairs that are used to match a user to a group. It adds an additional
             # requirement to the filter that an attribute in the group must match the user's
             # attribute value.
             userMatchers:
               - userAttr: uid
                 groupAttr: member
     staticClients:
       - name: vCluster Platform
         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

   For details about configuring dex for LDAP, take a look at the dex documentation for LDAP.

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 + LDAP

   After saving the new platform configuration, the platform is going to restart itself and you should be able to log in via LDAP 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