Troubleshooting LDAP server connections

Pexip Infinity can be configured to connect to a Windows Active Directory LDAP server, or any other LDAP-accessible database, in order to:

This section explains how Pexip Infinity connects to the LDAP server, and provides guidance on how to troubleshoot connection problems.

Note that all LDAP distinguished names must be entered as per the LDAP standard (RFC 4514). LDAP configuration is case insensitive.

Connecting to the LDAP server

When resolving the LDAP server address, the system supports DNS SRV and DNS A/AAAA lookups. The system always tries in the first instance to set up a TLS connection with the LDAP server. If that fails it may fall back to a TCP connection if allowed.

To establish a TLS connection, the Pexip Infinity platform must trust the certificate presented by the LDAP server i.e. the LDAP server’s certificate must be signed by an authority within the Pexip Infinity trusted CA certificates store. In addition, the resolved LDAP server address must match the CN (common name) contained within the certificate presented by the LDAP server.

The system will connect to the port returned by an SRV lookup, otherwise it will connect to 389 (TCP) or 636 (TLS). Requests to search the Active Directory Global Catalog use ports 3268 (TCP) and 3269 (TLS).

Connection process

If the LDAP server address is configured as an IP address, the system will connect directly to the given address, otherwise it treats it as a domain or FQDN and attempts to resolve the address via DNS lookups in the following sequence:

  1. Perform a DNS SRV lookup against _ldaps._tcp.<LDAP server address>
    (or _ldaps._tcp.gc._msdcs.<LDAP server address> if searching the AD global catalog).
  2. Perform a DNS SRV lookup against _ldap._tcp.<LDAP server address>
    (or _ldap._tcp.gc._msdcs.<LDAP server address> if searching the AD global catalog).
  3. Perform a DNS A/AAAA lookup against <LDAP server address>.

When a DNS lookup is successful, the system will first attempt to establish a TLS connection with the server at the returned address. If the TLS connection attempt fails, the system will then attempt a TCP connection, but only if Allow insecure transport is enabled. Only TLS connections are attempted as a result of _ldaps lookups.

If multiple addresses are returned by SRV lookups, the system will attempt to connect to each address in priority order.

Connectivity error messages and using the support log

Diagnostic information is also recorded in the support log (Status > Support log).

When Pexip Infinity connects successfully to the LDAP server, the support log will contain an entry similar to this:

2015-06-05T11:15:00.550+00:00 mgmt 2015-06-05 11:15:00,550 Level="INFO" Name="support.ldap" Message="Successfully connected to LDAP server" Address="server.example.com" Uri="ldaps://server.example.com"

Unable to contact the LDAP server

If Pexip Infinity cannot contact the configured LDAP server, the support log will contain an entry similar to this:

2015-06-05T08:40:29.707+00:00 mgmt 2015-06-05 08:40:29,704 Level="INFO" Name="support.ldap" Message="Failed connecting to LDAP server" Address="server.example.com" Reasons="
ldaps://server.example.com : Can't contact LDAP server
ldap://server.example.com : Can't contact LDAP server"

Ensure that the server is available at the configured address and, if the server address is specified by domain name or FQDN, ensure that DNS records exist and resolve to the correct address.

Connection errors: TLS certificate issues

If Pexip Infinity can reach the configured LDAP server, but cannot connect to it due to TLS certificate issues, the support log will contain an entry similar to this:

2015-06-05T08:55:49.042+00:00 mgmt 2015-06-05 08:55:49,042 Level="INFO" Name="support.ldap" Message="Failed connecting to LDAP server" Address="server.example.com" Reasons="
ldaps://server.example.com : Can't contact LDAP server
ldap://server.example.com : Connect error"

The reason "Connect error" means that Pexip Infinity cannot verify the LDAP server's certificate.

Ensure that the LDAP server's TLS certificate (or the CA certificate that signed it, if it is not self-signed) is in the Pexip Infinity trust store (Certificates > Root trust CA certificates).

Note that, by default, Pexip Infinity will not use any intermediate CA certificates that have been uploaded to the Management Node for the purposes of verifying certificates for external services. Those external services should present their entire certificate chain. However, some third-party systems such as Azure AD DS (e.g. when used for an LDAPS connection) cannot be configured to present their entire certificate chain; in these cases you can configure Pexip Infinity to use the intermediate certificate in the TLS verification chain (see Uploading and managing additional trusted CA certificates).

Connection errors: binding to the server fails e.g. invalid credentials

If Pexip Infinity can reach the configured LDAP server, but cannot connect to it due to binding errors, such as invalid credentials, the support log will contain an entry similar to this:

2015-06-05T09:11:03.765+00:00 mgmt 2015-06-05 09:11:03,765 Level="INFO" Name="support.ldap" Message="Failed connecting to LDAP server" Address="server.example.com" Reasons="
ldaps://server.example.com : Invalid credentials
ldap://server.example.com : Invalid credentials"

Ensure that you have entered the correct credentials. They should be for an enabled, non-expired, domain user service account (not the Administrator account), which has a password set to never expire. All usernames and passwords are case sensitive.

If you are certain that the account you are trying to bind with is configured correctly, try to bind using the:

  • bare username of the service account (e.g. ldapuser)
  • full DN of the service account (e.g. CN=ldapuser,CN=Users,DC=example,DC=com)
  • Windows logon of the service account (e.g. EXAMPLE\ldapuser).

Connection errors when using insecure transport

You cannot specify the LDAP server address as an IP address if you have also selected the Allow insecure transport option. If the server address is not specified as an FQDN you will receive "Invalid credentials" error messages.

You cannot use an IP address because the authentication handshake is encrypted using SASL technology. To achieve this, various shared keys are used — things both sides know and use as part of the handshake but are not exchanged on the wire. In this case, it is the FQDN of the LDAP server that is used.

Therefore, if you need to use insecure transport, you must ensure that you refer to the LDAP server by its FQDN (and this is the hostname ​the server uses to identify itself, not just something that points to the IP address), so that the authentication will work. See Using ldapsearch or AD Explorer to view the LDAP database below for an example of how to discover an AD server's hostname.

Alternatively, you could use secure transport, referring to the LDAP server by any name that appears in its TLS certificate, and by loading all necessary trusted CA certificates onto Pexip Infinity.

Connection errors: Error syncing with LDAP

You can receive an "Error syncing with LDAP" error message when attempting to perform a template synchronization when provisioning VMRs, devices or users.

This can be caused by invalid syntax in the template's LDAP user filter or LDAP user search DN fields. Check that all parentheses are balanced and are in the correct places, and that all operators are correctly positioned.

This message can also be received if you have not selected an LDAP sync source when configuring your sync template.

Cannot log in to Pexip Infinity despite using correct credentials

If users receive a "Please enter the correct username and password for an administrator account" message when trying to log in to Pexip Infinity, but they are using the correct username and password, this typically means that either:

  • The LDAP server cannot be contacted:

    • These errors are recorded in the Support log; see the connectivity troubleshooting guidelines above for more information.
  • The LDAP server can be contacted but the correct user records are not being searched:

    • Check the Pexip Infinity LDAP configuration settings (Users & Devices > Administrator authentication) to ensure that all objectClass and LDAP field names have been spelled correctly, and that the base DN and user search DN fields contain the correct domain and organizational unit settings.
    • If you are using nested AD security groups, see Supporting nested security groups in Windows Active Directory.
  • The LDAP server can be contacted and the user records can be found and authenticated, but the user is not authorized to access Pexip Infinity:

    • Check that administrator roles and role mappings have been configured on Pexip Infinity (Users & Devices > Administrator roles and Users & Devices > LDAP role mappings).
    • Ensure that the user's LDAP account is associated with the LDAP group DNs / role combinations that are configured on Pexip Infinity.
  • Note that usernames and passwords are case sensitive — ensure that you are using the correct case for your credentials.

Recovering local access

If necessary you can reinstate access via the Pexip Infinity local on-box database, so that administrators can log in via the default account (typically admin) and will have full administrator privileges. You may need to do this if, for example, the Authentication source is configured as LDAP database and your connectivity to the LDAP server goes down or your credentials become invalid.

To reactivate your local admin account:

  1. Log in to the Management Node over SSH.
  2. For local admin access only, run the command:

    authset LDAP LOCAL

    or, for LDAP and local admin access, run the command:

    authset LDAP BOTH

You can also disable client certificate authentication so that you can log in to the Pexip Infinity Administrator interface via the standard login page.

To disable certificate-based authentication:

  1. Log in to the Management Node over SSH.
  2. Run the command:

    authset CBA OFF

If you forget the password for the Pexip Infinity Administrator interface, you can re-run the installation wizard, being sure to change only the Web administration password setting.

VMRs, devices or user records not created as expected by a sync template

User search or user filters not being applied

If more or fewer VMRs, devices or users than expected (or no VMRs/devices/users at all) were created after performing a template synchronization, it is likely that the LDAP base DN, LDAP user search DN and LDAP user filter fields have been misconfigured.

Check that all objectCategory, objectClass and LDAP field names have been spelled correctly. Note that all LDAP user search and user filter contents are not case sensitive.

More information on Active Directory LDAP filtering can be found at https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx.

Using ldapsearch or AD Explorer to view the LDAP database

Mac and Linux systems

You can use a command line tool such as ldapsearch, which is available for Mac and Linux systems, to help test and diagnose connectivity issues with the LDAP server. Note that ldapsearch is installed by default on all Pexip Infinity nodes.

Here are some example ldapsearch queries you could use (after adapting the parameters as appropriate for your environment).

$ ldapsearch -v -h 10.0.0.8 -D "example\admin123" -w password123 -b OU=people,DC=example,DC=com

This fetches the contents of OU (org unit) people from the LDAP server at 10.0.0.8 over TCP, binding as user (sAMAccountName) admin123 in NetBIOS domain example with password password123 using simple (insecure) authentication.

$ ldapsearch -v -h dc01.example.com -Y DIGEST-MD5 -U admin123 -w password123 -b OU=people,DC=example,DC=com

This extends the previous example by addressing the LDAP server by its FQDN dc01.example.com and uses SASL/DIGEST-MD5 authentication.

Windows

Windows users can use Active Directory Explorer (AdExplorer) to navigate around and view AD structures and entries. See https://technet.microsoft.com/en-us/sysinternals/adexplorer for more information and links to download the software.

The example below shows how you can discover your AD server's actual hostname (AD-LON.example.local in this case) if you use AdExplorer to connect to your server via its IP address (10.44.10.10 in this case):