Skip to main content

LDAP

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

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