Supported editions for this feature: Frontline Standard; Business Plus; Enterprise Standard and Enterprise Plus; Education Fundamentals, Education Standard, Teaching and Learning Upgrade, and Education Plus; Enterprise Essentials Plus. Compare your edition
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:
- Verify connectivity and run an LDAP query
Running an LDAP query enables you to confirm that you can connect to Secure LDAP and perform queries.
- If needed, run basic connectivity testing
If running an LDAP query fails, run basic connectivity testing to test for network access and authentication.
Note: If you need to contact Google Workspace 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.
ldapsearchUse 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:
- Create an LDAP configuration, and download the certificate, following the instructions in 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.
- Execute an LDAP query. This example queries a particular user (for more details, see OpenLDAP ldapsearch).
LDAPTLS_CERT={crt_file} LDAPTLS_KEY={key_file} ldapsearch -H ldaps://ldap.google.com:636 -b dc={domain},dc={domain} '(mail={user_email})'Replace placeholders as follows:
- {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.
Notes on using ldapsearch
- If no BindDN value is provided, ldapsearch uses the key and certificate to authorize the search.
- If the BindDN value is an LDAP username that you generated in Admin console, ldapsearch will use the permissions of the LDAP client as configured in Admin console.
ldapsearch -H ldaps://ldap.google.com:636 -b dc={domain},dc={domain} -D {ldap_access_credentials_username} -W '(mail={user_email}) - If BindDN value is an email address or LDAP distinguished name of a Workspace User, ldapsearch will use the credentials of that user to search based on their permissions.
ldapsearch -H ldaps://ldap.google.com:636 -b dc={domain},dc={domain} -D {workspace_username@domain} -W '(mail={user_email})'
Use ldapsearch with stunnel
If your deployment requires you to use stunnel, follow these steps:
- In Admin console, generate access credentials to produce the username and password needed by ldapsearch.
- Use the following command:
ldapsearch -x -D "{username}" -w {password} -H ldap://{stunnel_host}:{stunnel_port} -b dc={domain},dc={domain} '(mail={user_email})'Replace placeholders as follows:
- {username} Username from the generated credentials in Admin Console
- {password} Password from the generated credentials in Admin Console
- {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
- {user_email} Primary email address of a user in the domain
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
-d5option 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-xand try again.
- Follow steps 1–11 in ldp.exe (Windows) to install the client certificates.
- Go to Action > Connect to…
- 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
- 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
- Click OK, and then click OK again.
- If connectivity is successful, directory contents in the base DN are displayed in the right pane.
- Install OpenSSL.
- 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.
- Go to the Control Panel.
- In the search box, search for “certificate," and click Manage user certificates.
- Go to Action > All Tasks > Import…
- Select Current User, and click Next.
- Click Browse…
- In the file type dropdown in the lower-right corner of the dialog box, select Personal Information Exchange (*.pfx;*.p12).
- Select the ldap-client.p12 file from step 2, click Open, and then click Next.
- Enter the password from step 2 and click Next.
- Select the Personal certificate store, click Next, and then click Finish.
- Run Ldp.exe.
- Go to Connection > Connect...
- Enter the following connection details:
Server: ldap.google.com
Port: 636
Connectionless: Unchecked
SSL: Checked
- Click OK.
- Go to View > Tree.
- Enter the base DN. This is your domain name in DN format. (for example, dc=example,dc=com for example.com).
- Click OK.
- 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:
- Install the openssl client utility for your operating system.
Most GNU/Linux distributions use the package name "openssl". See details about other operating systems.
-
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.
