Connecting LDAP external directory services to PE

Puppet Enterprise connects to external Lightweight Directory Access Protocol (LDAP) directory services through its role-based access control (RBAC) service. Because PE integrates with cloud LDAP service providers, such as Okta, you can use the users and user groups that already exist in your external directory service.

Specifically, you can:
  • Connect multiple LDAP directory services.
  • Authenticate external directory users.
  • Authorize access for external directory users based on RBAC permissions.
  • Store and retrieve group and group membership information from your external directory.
    Tip: Puppet stores local accounts and directory service integration credentials securely. Local account passwords are hashed using SHA-256 multiple times, along with a 32-bit salt. To update the algorithm to argon2id (only for non-FIPS enabled systems) or to configure password algorithm parameters, refer to Configure the password algorithm. Directory service lookup credentials configured for directory lookup purposes are encrypted using AES-128. Puppet does not store the directory credentials used for authenticating to Puppet. These are different from the directory service lookup credentials.

PE supports OpenLDAP and Active Directory. If you have predefined groups in OpenLDAP or Active Directory, you can import these groups into the console and assign user roles to them, as explained in Working with LDAP users and user groups. Users in an imported group inherit the permissions specified in the group's assigned user roles. If new users are added to the group in the external directory, they also inherit the permissions of the role to which that group belongs.

Important: The connection to OpenLDAP and Active Directory is read-only. If you want to make changes to remote users or user groups, you need to edit the information directly in the external directory.

Connect to external directory services

PE connects to your external directory service(s) when a user logs in or when groups are imported. The supported directory services are OpenLDAP and Active Directory.

Tip: You can connect multiple LDAP directories. With multiple LDAP directories, when a user logs in for the first time, PE looks for the user in your LDAP directories in the order the directories were added to PE. To learn more about this, go to Working with LDAP users and user groups.
  1. In the console, on the Access control page, click the LDAP tab.
  2. Click Connect to an LDAP directory or Add an LDAP directory.
  3. Input the directory information.

    For information about each field, refer to External directory settings.

    If you do not supply User relative distinguished name or Group relative distinguished name, PE's RBAC service searches the entire base DN for the user or group.

  4. Click Connect. PE tests if the connection is valid and then saves the configuration.
    PE only tests the connection to the LDAP server. It does not test or validate LDAP queries.
  5. Repeat these steps if you need to connect additional LDAP directories.
What to do next
To allow your LDAP users to access PE, you need to import LDAP groups and assign roles, as explained in Working with LDAP users and user groups. Optionally, you can Verify directory server certificates.

External directory settings

The table below lists the LDAP external directory connection fields in the PE console, the equivalent system name for each field as used by the RBAC API, and provides examples of each settings for an Active Directory service and an OpenLDAP service. Additional details are provided below the table.

Important: This table provides generic examples for some settings. These examples may not be appropriate for your configuration. Make sure you use values appropriate for your directory service.
Display name System name (for RBAC API) Example Active Directory settings Example OpenLDAP settings
Directory name display_name My Active Directory My Open LDAP Directory
Login help help-link
Tip: This field can be empty (null).
 https://myweb.com/ldaploginhelp https://myweb.com/ldaploginhelp
Hostname hostname myhost.delivery.exampleservice.net myhost.delivery.exampleservice.net
Port port 389 (or 636 for LDAPS) 389 (or 636 for LDAPS)
Lookup user login cn=queryuser,cn=Users,dc=puppetlabs,dc=com cn=admin,dc=delivery,dc=puppetlabs,dc=net
Lookup password password The lookup user's password The lookup user's password
Connection timeout (seconds) connect_timeout
Tip: Must be an integer representing a number of seconds.
 10 10
Connect using ssl, start_tls
Tip: In API requests, these are separate keys. Set the desired connection setting to true and the undesired setting to false.
 SSL StartTLS
Certificate chain (optional) cert_chain
Tip: Use this optional setting to define unique certificate chains across servers.
 Paste in a plain text certificate chain or leave blank. Paste in a plain text certificate chain or leave blank.
Validate the hostname? (optional) ssl_hostname_validation Default is yes Default is true
Allow wildcards in SSL certificate? (optional) ssl_wildcard_validation Default is no Default is false
Base distinguished name base_dn dc=puppetlabs,dc=com dc=puppetlabs,dc=com
User login attribute user_lookup_attr sAMAccountName cn
User email address field user_email_attr mail mail
User full name user_display_name_attr displayName displayName
User relative distinguished name user_rdn cn=users ou=users
Group object class group_object_class
Tip: This required field has no default value, but it can be empty (nil).
 group groupOfUniqueNames
Group membership field group_member_attr member uniqueMember
Group name attribute group_name_attr name displayName
Group lookup attribute group_lookup_attr cn cn
Group relative distinguished name group_rdn cn=groups ou=groups
Turn off LDAP_MATCHING_RULE_IN_CHAIN? (optional) disable_ldap_matching_rule_in_chain Default is no Default is false
Search nested groups? (optional) search_nested_groups Default is no Default is false

Explanation of external directory settings

Directory name
The name that you provide here is used to refer to the external directory service anywhere it is used in the PE console. For example, when you view a remote user in the console, the name that you provide in this field is listed in the console as the source for that user. Set any name of your choice.
Login help (optional)
A URL supplied here becomes a "Need help logging in?" link on the login screen. The href attribute of this link is set to the URL that you provide.
Hostname
The FQDN of the directory service to which you are connecting.
Port
The port that PE uses to access the directory service. The port is generally 389, unless you choose to connect using SSL, in which case it is generally 636.
Lookup user (optional)
The distinguished name (DN) of the directory service user account that PE uses to query information about users and groups in the directory server. If a username is supplied, this user must have read access for all directory entries that are to be used in the console. We recommend that this user is restricted to read-only access to the directory service.
If your LDAP server is configured to allow anonymous binding, you do not need to provide a lookup user. In this case, the RBAC service binds anonymously to your LDAP server.
Lookup password (optional)
The lookup user's password.
If your LDAP server is configured to allow anonymous binding, you do not need to provide a lookup password. In this case, the RBAC service binds anonymously to your LDAP server.
Connection timeout (seconds)
The number of seconds that PE attempts to connect to the directory server before timing out. Ten seconds is fine in the majority of cases. If you are experiencing timeout errors, make sure the directory service is up and reachable, and then increase the timeout if necessary.
Connect using
Select the security protocol you want to use to connect to the external directory.
SSL and StartTLS encrypt the data transmitted.
Plain text is not a secure connection.
In addition, to ensure that the directory service is properly identified, configure the ds-trust-chain to point to a copy of the public key for the directory service. For more information, see Verify directory server certificates.
Certificate chain (optional)
Use this field if you need to specify different certificate chains between servers.
This option is not available when you choose to connect to the external directory using plain text.
Validate the hostname?
Select Yes to verify that the Directory Service hostname used to connect to the LDAP server matches the hostname on the SSL certificate.
This option is not available when you choose to connect to the external directory using plain text.
Allow wildcards in SLL certificate?
Select Yes to allow a connection to a Directory Services server with a SSL certificates that use a wildcard (*) specification.
This option is not available when you choose to connect to the external directory using plain text.
Base distinguished name
When PE constructs queries to your external directory (for example to look up user groups or users), the queries consist of the relative distinguished name (RDN) (optional) + the base distinguished name (DN), and are then filtered by lookup/login attributes. For example, if PE wants to authenticate a user named Bob who has the RDN ou=bob,ou=users, it sends a query in which the RDN is concatenated with the DN specified in this field (for example, dc=puppetlabs,dc=com). This gives a search base of ou=bob,ou=users,dc=puppetlabs,dc=com.
The base DN that you provide in this field specifies where in the directory service tree to search for groups and users. It is the part of the DN that all users and groups that you want to use have in common. It is commonly the root DN (example dc=example,dc=com) but in the following example of a directory service entry, you could set the base DN to ou=Puppet,dc=example,dc=com because both the group and the user are also under the organizational unit ou=Puppet.
Example directory service entry:
# A user named Harold
dn: cn=harold,ou=Users,ou=Puppet,dc=example,dc=com
objectClass: organizationalPerson
cn: harold
displayName: Harold J.
mail: harold@example.com
memberOf: inspectors
sAMAccountName: harold11

# A group Harold is in
dn: cn=inspectors,ou=Groups,ou=Puppet,dc=example,dc=com
objectClass: group
cn: inspectors
displayName: The Inspectors
member: harold
User login attribute
This is the directory attribute that the user uses to log in to PE. For example, if you specify sAMAccountName as the user login attribute, Harold logs in with the username "harold11" because sAMAccountName=harold11 in the example directory service entry provided above.
The value provided by the user login attribute must be unique among all entries under the User RDN + Base DN search base you’ve set up.
For example, say you’ve selected the following settings: 
base DN = dc=example,dc=com
user RDN = null
user login attribute = cn
When Harold tries to log in, the console searches the external directory for any entries under dc=example,dc=com that have the attribute/value pair cn=harold. (This attribute/value pair does not need to be contained within the DN). However, if there is another user named Harold who has the DN cn=harold,ou=OtherUsers,dc=example,dc=com, two results are returned and the login does not succeed because the console does not know which entry to use. Resolve this issue by either narrowing your search base such that only one of the entries can be found, or using a value for login attribute that you know to be unique. This makes sAMAccountName a good choice if you’re using Active Directory, as it must be unique across the entire directory.
User email address
The directory attribute to use when displaying the user's email address in PE.
User full name
The directory attribute to use when displaying the user's full name in PE.
User relative distinguished name (optional)
The user RDN that you set here is concatenated with the base DN to form the search base when looking up a user. For example, if you specify ou=users for the user RDN, and your base DN setting is ou=Puppet,dc=example,dc=com, PE finds users that have ou=users,ou=Puppet,dc=example,dc=com in their DN.
This setting is optional. If you choose not to set it, PE searches for the user in the base DN (example: ou=Puppet,dc=example,dc=com). Setting a user RDN is helpful in the following situations:
  • When you experience long wait times for operations that contact the directory service (either when logging in or importing a group for the first time). Specifying a user RDN reduces the number of entries that are searched.
  • When you have more than one entry under your base DN with the same login value.
Tip: It is not currently possible to specify multiple user RDNs. If you want to filter RDNs when constructing your query, we suggest creating a new lookup user who only has read access for the users and groups you want to use in PE.
Group object class
The name of an object class that all groups have.
Group membership field
Tells PE how to find which users belong to which groups. This is the name of the attribute in the external directory groups that indicates who the group members are.
Group name attribute
The attribute that stores the display name for groups. This is used for display purposes only.
Group lookup attribute
The value used to import groups into PE. Given the example directory service entry provided above, the group lookup attribute would be cn. When specifying the Inspectors group in the console to import it, provide the name inspectors.
The value for this attribute must be unique under your search base. If you have users with the same login as the lookup of a group that you want to use, you can narrow the search base, use a value for the lookup attribute that you know to be unique, or specify the Group object class that all of your groups have in common but your users do not.
Tip: If you have a large number of nested groups in your group hierarchy, or you experience slowness when logging in with RBAC, we recommend disabling nested group search unless you need it for your authorization schema to work.
Group relative distinguished name (optional)
The group RDN that you set here is concatenated with the base DN to form the search base when looking up a group. For example, if you specify ou=groups for the group RDN, and your base DN setting is ou=Puppet,dc=example,dc=com, PE finds groups that have ou=groups,ou=Puppet,dc=example,dc=com in their DN.
This setting is optional. If you choose not to set it, PE searches for the group in the base DN (example: ou=Puppet,dc=example,dc=com). Setting a group RDN is helpful in the following situations:
  • When you experience long wait times for operations that contact the directory service (either when logging in or importing a group for the first time). Specifying a group RDN reduces the number of entries that are searched.
  • When you have more than one entry under your base DN with the same lookup value.
Tip: It is not currently possible to specify multiple group RDNs. If you want to filter RDNs when constructing your query, create a new lookup user who only has read access for the users and groups you plan to use in PE.
Note: At present, PE supports only a single Base DN. Use of multiple user RDNs or group RDNs is not supported.
Turn off LDAP_MATCHING_RULE_IN_CHAIN?
When PE detects an Active Directory that supports the LDAP_MATCHING_RULE_IN_CHAIN feature, PE automatically uses it. You can select Yes to turn off the LDAP matching rule that looks up the chain of ancestry for an object until it finds a match. For organizations with a large number of group memberships, matching rule in chain can slow performance.
Search nested groups?
When authorizing users, the RBAC service can search nested groups. Nested groups are groups that belong to external directory groups. For example, assume your external directory has a System Administrators group, and you've given that group a Superusers user role in RBAC. If you selected Yes for this setting, in addition to assigning the Superusers role to individual users in the System Administrators group, RBAC looks for other groups in the System Administrators group and assigns the Superusers role to the individual users in those nested groups.
By default, this setting is not selected and RBAC does not search nested groups. To enable nested group searches, select Yes.
Important: This setting causes RBAC to search the entire group hierarchy when users log in; therefore, you might experience slowdowns in performance if you have a lot of nested groups. To avoid these performance issues, don't enable this option. With nested group search disabled, RBAC only searches the groups it is configured to use for user roles.
Note: In Puppet Enterprise (PE) versions 2015.3 and earlier, RBAC searched nested groups by default. If you upgrade from one of these earlier versions, this setting is preserved and RBAC continues to search nested groups by default. You'll need to disable it if you don't want to use nested searching anymore.

Verify directory server certificates

To ensure that RBAC isn't being subjected to a Man-in-the Middle (MITM) attack, verify the directory server's certificate.

When you select SSL or StartTLS as the security protocol to use for communications between PE and your directory server, the connection to the directory is encrypted. To ensure that the directory service is properly identified, configure the ds-trust-chain to point to a copy of the public key for the directory service.

The RBAC service verifies directory server certificates using a trust store file, in Java Key Store (JKS), PEM, or PKCS12 format, that contains the chain of trust for the directory server's certificate. This file needs to exist on disk in a location that is readable by the user running the RBAC service.

To turn on verification:

  1. In the console, click Node groups.
  2. Open the PE Infrastructure node group and select the PE Console node group.
  3. Click Classes. Locate the puppet_enterprise::profile::console class.
  4. In the Parameter field, select rbac_ds_trust_chain.
  5. In the Value field, set the absolute path to the trust store file.
  6. Click Add parameter and commit changes.
  7. To make the change take effect, run Puppet. Running Puppet restarts pe-console services.
Results
After setting this value, the directory server's certificate is verified whenever RBAC is configured to connect to the directory server using SSL or StartTLS.