Connecting Enterprise PKS to an LDAP Server

Page last updated:

Warning: Pivotal Container Service (PKS) v1.5 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy.
To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic describes how to connect Enterprise Pivotal Container Service (Enterprise PKS) to an external LDAP server.

Overview

User Account and Authentication (UAA), the identity management service for Enterprise PKS, can authenticate users either through its internal user account store or external authentication mechanisms such as an LDAP server or a SAML identity provider.

To enable an internal user account store for UAA, you select Internal UAA in the Enterprise PKS tile > UAA.

If you want to connect Enterprise PKS to an external LDAP server, you must integrate the UAA server with your LDAP server by following the instructions in Integrate UAA with an LDAP Server below. This enables UAA to delegate authentication to your LDAP user store.

Integrate UAA with an LDAP Server

To integrate UAA with one or more LDAP servers:

  1. In Enterprise PKS > UAA, under Configure your UAA user account store with either internal or external authentication mechanisms, select LDAP Server. LDAP Server configuration pane

  2. Under Server URL, enter the URLs that point to your LDAP server. For example, ldaps://example.com. If you have multiple LDAP servers, separate their URLs with spaces. Each URL must include one of the following protocols:

    • ldap://: Enter this protocol if your LDAP server uses an unencrypted connection.
    • ldaps://: Enter this protocol if your LDAP server uses SSL for an encrypted connection. To support an encrypted connection, the LDAP server must hold a trusted certificate or you must import a trusted certificate to the JVM truststore.
  3. Under LDAP Credentials, enter the LDAP Distinguished Name (DN) and password for binding to the LDAP server. For example, cn=administrator,ou=Users,dc=example,dc=com. If the bind user belongs to a different search base, you must use the full DN.

    Note: We recommend that you provide LDAP credentials that grant read-only permissions on the LDAP search base and the LDAP group search base.

  4. Under User Search Base, enter the location in the LDAP directory tree where LDAP user search begins. For example, a domain named cloud.example.com may use ou=Users,dc=example,dc=com as its LDAP user search base.

  5. Under User Search Filter, enter a string to use for LDAP user search criteria. The search criteria allows LDAP to perform more effective and efficient searches. For example, the standard LDAP search filter cn=Smith returns all objects with a common name equal to Smith.

    In the LDAP search filter string that you use to configure Enterprise PKS, use {0} instead of the username. For example, use cn={0} to return all LDAP objects with the same common name as the username. In addition to cn, other common attributes are mail, uid, and for Active Directory, sAMAccountName.

    Note: For information about testing and troubleshooting your LDAP search filters, see Configuring LDAP Integration with Pivotal Cloud Foundry.

  6. Under Group Search Base, enter the location in the LDAP directory tree where the LDAP group search begins. For example, a domain named cloud.example.com may use ou=Groups,dc=example,dc=com as its LDAP group search base. You must configure Group Search Base if you want to map an external LDAP group to a role in Enterprise PKS or a Kubernetes group.

    Note: To map the groups under this search base to roles in Enterprise PKS, follow the instructions in Grant Enterprise PKS Access to an External LDAP Group.

  7. Under Group Search Filter, enter a string that defines LDAP group search criteria. The default value is member={0}.

  8. Under Server SSL Cert, paste in the root certificate from your CA certificate or your self-signed certificate.

    LDAP Server configuration pane

  9. For Server SSL Cert AltName, do one of the following:

    • If you are using ldaps:// with a self-signed certificate, enter a Subject Alternative Name (SAN) for your certificate.
    • If you are not using ldaps:// with a self-signed certificate, leave this field blank.
  10. Under First Name Attribute, enter the attribute name in your LDAP directory that contains user first names. For example, cn.

  11. Under Last Name Attribute, enter the attribute name in your LDAP directory that contains user last names. For example, sn.

  12. Under Email Attribute, enter the attribute name in your LDAP directory that contains user email addresses. For example, mail.

  13. Under Email Domain(s), enter a comma-separated list of the email domains for external users who can receive invitations to Apps Manager.

  14. Under LDAP Referrals, choose how UAA handles LDAP server referrals to other user stores. UAA can follow the external referrals, ignore them without returning errors, or generate an error for each external referral and abort the authentication.

  15. Under External Groups Whitelist, enter a comma-separated list of group patterns that need to be populated in the user’s id_token. For more information about accepted patterns, see the description of config.externalGroupsWhitelist in the OAuth/OIDC Identity Provider Documentation.

    Note: When sent as a Bearer token in the Authentication header, wide pattern queries for users who are members of multiple groups can cause the size of the id_token to extend beyond what is supported by web servers.

    External Groups Allowlist field

  16. Click Save.

Complete Your Tile Configuration

Next Steps

For information about creating Enterprise PKS roles and managing Kubernetes cluster access, see:


Please send any feedback you have to pks-feedback@pivotal.io.