Connectivity testing and troubleshooting

This feature is available with G Suite Enterprise, Cloud Identity Premium, G Suite Enterprise for Education, and G Suite for Education.

Before you try to connect your LDAP client to the Secure LDAP service, optionally you might want to do a quick connectivity test using simple tools like ldapsearch, ADSI, or ldp.exe. These tools can also be used for troubleshooting if you encounter errors while trying to connect your LDAP client to the service.

The tests described in the sections below enable you to understand if you have a configuration issue on your end, common error messages, and recommendations for how those issues can be fixed.

This article contains the following sections:

Note: If you need to contact G Suite Support or Cloud Identity Premium Support during this process, be sure to save the output of the commands. Make sure you remove any personally identifiable information from the output before sharing them with the support team.

Verify connectivity and run an LDAP query

Once you've set up the Secure LDAP service in the Google Admin console, you can use one of these three simple tools to verify connectivity with Secure LDAP: ldapsearch, ADSI, or ldp.exe. For details and instructions, see the sections below.

ldapsearch

Use the ldapsearch utility from a command line to make a basic LDAP query. A successful LDAP query result indicates that the LDAP client and underlying TLS session and TCP connection are working as intended.

To test connectivity with ldapsearch:

  1. Create an LDAP configuration, and download the certificate, following the instructions in 1. Add LDAP clients.

    Note: To simplify the testing environment, make sure there's at least one user in the organizational unit for which you authorize LDAP client access.
     
  2. Execute an LDAP query.

    The following command exemplifies how to use the ldapsearch command line tool to query a particular user (for more details, see OpenLDAP lapsearch): 
     

    LDAPTLS_CERT={crt_file} LDAPTLS_KEY={key_file} ldapsearch -H ldaps://ldap.google.com:636 -b dc={domain},dc={domain} '(mail={user_email})'

    Replace the following placeholders:

    {crt_file} : The name of the .crt file
    {key_file} : The filename of the .key file
    {domain} : Each part of the domain name, for example: example.com would become "dc=example,dc=com"
    {user_email} : Primary email address of a user in the domain.

Use ldapsearch with stunnel

If your deployment requires you to use stunnel, use the following commands:

ldapsearch -H ldap://{stunnel_host}:{stunnel_port} -b
dc={domain},dc={domain} '(mail={user_email})'

Replace the stunnel specific placeholders:
{stunnel_host} : IP address or hostname of the machine running stunnel in your network.
{stunnel_port} : the port where stunnel is running, check your stunnel configuration

Successful scenario of the ldapsearch command

A successful output of the ldapsearch command will list the user with the email (as specified when creating the LDAP client) in LDIF format.

For example:

# extended LDIF
#
# LDAPv3
# base <dc=example,dc=com> with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#

# example.com
dn: dc=example,dc=com
objectClass: top
objectClass: domain
objectClass: dcObject
dc: example

# admin-group, Groups, example.com
dn: cn=admin-group,ou=Groups,dc=example,dc=com
objectClass: top
objectClass: groupOfNames
objectClass: posixGroup
cn: admin-group
displayName: admin-group
description:
gidNumber: 12345
member: uid=admin,ou=Users,dc=example,dc=com
memberUid: admin
googleAdminCreated: FALSE


# example-user, Users, example.com
dn: uid=example-user,ou=Users,dc=example,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
uid: example-user
googleUid: example-user
posixUid: example-user
cn: example-user
cn: FirstName LastName
sn: FirstName
displayName: FirstName LastName
givenName: FirstName
mail: example-user@example.com
uidNumber: 12345
gidNumber: 12345
homeDirectory: /home/example-user
loginShell: /bin/bash
gecos:

Possible errors

  • OpenLDAP client and/or library are compiled without SNI support

    SNI (Server Name Indication) is required to be supported by the LDAP client (OpenLDAP in this case). If SNI is not available, you might see an error similar to the following:

    SASL/EXTERNAL authentication started

    ldap_sasl_interactive_bind_s: Unknown authentication method (-6)
     additional info: SASL(-4): no mechanism available:

    Recommendation:
    • If you are using MacOS, SASL is enabled by default and can be bypassed with the option "-x".
    • Add the -d5 option to ldapsearch and check the output for the following line:

      TLS certificate verification: depth: 0, err: 18, subject: /OU=No SNI provided; please fix your client.
       
  • ldapsearch returns status 0 (success) but no users are outputs

    Specifying ldapsearch option -x (use SASL authentication) with client certificates will successfully authenticate but will not list users in the domain.

    Recommendation: Remove the option -x and try again.

ADSI Edit (Windows)
  1. Follow steps 1–11 in ldp.exe (Windows) to install the client certificates.
  2. Go to Action > Connect to…
  3. Enter the following connection settings:

    Name: Type a name for your connection, such as Google LDAP.
    Connection Point: “Select or type a Distinguished Name or Naming Context”
    Enter your domain name in DN format (for example, dc=example,dc=com for example.com).

    Computer: “Select or type a domain or server”
    ldap.google.com

    Use SSL-based Encryption: Checked
     
  4. Click Advanced..., and enter the following details:

    Specify credentials: Checked
    Username: The access credential username from the Admin console
    Password: The access credential password from the Admin console
    Port Number: 636
    Protocol: LDAP
    Simple bind authentication: Checked
     
  5. Click OK, and then click OK again.
  6. If connectivity is successful, directory contents in the base DN are displayed in the right pane.
ldp.exe (Windows)
  1. Install OpenSSL.
  2. Convert the certificate and key files to one PKCS12 formatted file. At a command prompt, enter the following:

    openssl pkcs12 -inkey ldap-client.key -in ldap-client.crt -export -out ldap-client.p12

    Enter a password to encrypt the output file.
     
  3. Go to the Control Panel.
  4. In the search box, search for “certificate," and click Manage user certificates.
  5. Go to Action > All Tasks > Import…
  6. Select Current User, and click Next.
  7. Click Browse…
  8. In the file type dropdown in the lower-right corner of the dialog box, select Personal Information Exchange (*.pfx;*.p12).
  9. Select the ldap-client.p12 file from step 2, click Open, and then click Next.
  10. Enter the password from step 2 and click Next.
  11. Select the Personal certificate store, click Next, and then click Finish.
  12. Run Ldp.exe.
  13. Go to Connection > Connect...
  14. Enter the following connection details:

    Server: ldap.google.com
    Port: 636
    Connectionless: Unchecked
    SSL: Checked
     
  15. Click OK.
  16. Go to View > Tree.
  17. Enter the base DN. This is your domain name in DN format. (for example, dc=example,dc=com for example.com).
  18. Click OK.
  19. If connectivity is successful, directory contents in the base DN are displayed in the right pane.

If needed, run basic connectivity testing

If you're unable to obtain a successful result in Verify connectivity and run an LDAP query, follow the instructions in this section for connectivity testing. If ldapsearch is not successful in returning the expected user and does not give a clear indication that the underlying TLS session is successful, use the OpenSSL client to verify that the network layers that OpenLDAP relies on are working as expected.

To conduct basic connectivity testing:

  1. Install the openssl client utility for your operating system.

    Most GNU/Linux distributions use the package name "openssl". See details about other operating systems.
     
  2.  Make a manual connection to the Secure LDAP service using the openssl client:

    openssl s_client -connect ldap.google.com:636

    Confirm that the SSL negotiation has succeeded by the presence of the following line at the end of the openssl s_client output: 

    Verify return code: 0 (ok)

Possible errors

OpenSSL client/library does not support SNI (Server Name Indication)

During the connectivity test, the following output might be returned:

Verify return code: 18 (self signed certificate)

The Secure LDAP service requires a TLS client that supports and initiates a TLS session using SNI (Server Name Indication). If the TLS client does not support SNI, then the TLS server (ldap.google.com) returns a self-signed certificate that will not pass CA validation checks, to indicate that SNI is required.

This behavior can be confirmed by checking the OpenSSL client output for the following line near the start of the output:

depth=0 OU = "No SNI provided; please fix your client.", CN = invalid2.invalid

Causes for this error may include an OpenSSL version that does not support SNI, or an application that uses the OpenSSL library with SNI explicitly disabled.

Connection refused

If the following output is returned—where {timestamp} is a UNIX timestamp in microseconds—the TCP connection is being actively refused before the TLS negotiation can start:

{timestamp}:error:0200206F:system library:connect:Connection refused:crypto/bio/b_sock2.c:110:
{timestamp}:error:2008A067:BIO routines:BIO_connect:connect error:crypto/bio/b_sock2.c:111:connect:errno=111

This may be caused by the following:

  • An application-level or system-level firewall on the local machine
  • A firewall on the same physical network or upstream network

To investigate, use tcptraceroute to determine which host is refusing the connection—for example, tcptraceroute ldap.google.com 636.

Related articles

Was this helpful?
How can we improve it?