4. Connect LDAP clients to the Secure LDAP service

Use the instructions in this article to connect your LDAP client to the Secure LDAP service.

IMPORTANT:

Be sure to read your vendor documentation
The details in this article for connecting your LDAP client to the Secure LDAP service are for reference only, and are subject to change. In addition to these help instructions, be sure to read your vendor documentation for the most up-to-date steps for connecting your client to the Secure LDAP service.
Before you get started
Before using these instructions, make sure you have already added the client to the Secure LDAP service, configured access permissions, downloaded a client certificate and key, and optionally created access credentials.
Connectivity testing
Optionally, before you begin with these steps, you might want to do a quick connection test using simple tools like ldapsearch, ADSI, and ldp.exe. You can also use these tools for troubleshooting if you encounter errors while trying to connect your LDAP client to the service. For instructions, see Secure LDAP connectivity testing.
How to complete your setup steps
After connecting the LDAP client by following the instructions on this page, you'll need to complete the setup of your LDAP client by switching the service status to On in the Google Admin console. For instructions, see 5. Switch LDAP clients to On.

What's included in this article

This article includes the following sections:

Basic configuration instructions—Includes generic instructions for connecting LDAP clients that are not specified in this article.
Configuration instructions for specific LDAP clients—Includes instructions for connecting specific LDAP clients (such as Atlassian Jira or OpenVPN) to the Secure LDAP service. The steps vary depending on the type of client.
Configuration instructions for Java applications—Includes generic instructions for Java-based applications that offer LDAP functionality.
Optional: Use stunnel as a proxy—This section includes instructions that specify additional considerations when connecting LDAP clients that don't support digital certificates.

These instructions assume that the client key and cert files that you download are called ldap-client.key and ldap-client.crt.

Basic configuration instructions

This section includes generic instructions for connecting your LDAP client to the Secure LDAP service. If your LDAP client is not listed in the instructions below, be sure to consult the documentation for that application.

Note: Certain LDAP clients such as Atlassian Jira and SSSD perform a user lookup to get more information about a user during user authentication. To make sure user authentication works correctly for such LDAP clients, you'll need to turn on Read user information for all organizational units where Verify user credentials is turned on. (For instructions, see Configure access permissions.)

To connect the LDAP client to the Secure LDAP service:

Configure your LDAP client with Cloud Directory as your LDAP server.
Upload the certificate to your LDAP client.

The Secure LDAP service uses TLS client certificates as the primary authentication mechanism. To begin the process of uploading the certificate to the LDAP client, open the LDAP client's authentication or directory settings, and enter the details from the table below.

Note: For complete details about how and where to upload TLS certificates, please see your vendor documentation.

Use the following table for basic connection information:

Hostname	ldap.google.com
Ports	389 for LDAP with StartTLS enabled 636 for LDAPS (SSL/TLS enabled)
Base DN	Your domain in DN format. For example: dc=example,dc=com for example.com
Username and Password	In addition to authenticating with a certificate, some LDAP clients require that you enter a username and password. If the username and password fields are not mandatory, you can skip this step. Generate a username and password in the Google Admin console. For instructions, see Generate access credentials.
Client certificate and key files	Use the certificate and key file downloaded from the Google Admin console. If the LDAP client doesn’t provide a way to authenticate with a client certificate, see Use stunnel as a proxy. IMPORTANT: Some LDAP clients, such as Apache Directory Studio, don't support the uploading of digital certificates. To address this scenario, see Use stunnel as a proxy.

Configuration instructions for specific LDAP clients

ADSI Edit (Windows)

Follow these steps:

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, active directory contents in the base DN are displayed in the right pane.

Apache Directory Studio

To use Apache Directory Studio, connect through stunnel and use an access credential (username and password) generated in the Google Admin console. Assuming the credentials are in place, and assuming stunnel is listening on localhost port 1389, follow these steps:

Click File > New…
Select LDAP Browser > LDAP Connection.
Click Next.
Enter the connection parameters:

Connection name: Choose a name, such as Google LDAP
Hostname: localhost
Port: 1389 (or the stunnel listen/accept port)
Encryption method: No encryption (Note: If stunnel is running remotely, encryption between stunnel and the client is recommended.)
Click Next.
Enter the authentication parameters:

Authentication Method: Simple Authentication
Bind DN or user: The access credential username from the Admin console
Bind password: The access credential password from the Admin console
Click Next.
Enter the base DN.
This is your domain name in DN format (dc=example,dc=com for example.com).
Click Finish.

Atlassian Jira

Atlassian Jira performs a user lookup to get more information about a user during user authentication. To make sure user authentication works correctly for this LDAP client, you'll need to turn on Read user information and Read group information for all organizational units where Verify user credentials is turned on. (For instructions, see Configure access permissions.)

Important: Using the following instructions potentially exposes the keystorePassword to users and log files. Take precautions to avoid unauthorized access to the local shell, logfile, and Google Admin console. As an alternative to the following instructions, use the stunnel4 method (see Optional: Use stunnel as a proxy).

Note: The following instructions assume Jira is installed at /opt/atlassian/jira.

To connect an Atlassian Jira client to the Secure LDAP service:

Copy the certificate and key to your Jira server(s). (This is the certificate that’s generated in the Google Admin console while adding the LDAP client to the Secure LDAP service.)

For example:
$ scp ldap-client.key user@jira-server:
Convert the certificate and keys to Java keystore format. You will be prompted for passwords throughout this process. For simplicity, select a secure password and use the same one for all of the prompts.

$ openssl pkcs12 -export -out jira-ldap.pkcs12 -in ldap-client.crt -inkey ldap-client.key $ sudo /opt/atlassian/jira/jre/bin/keytool -v -importkeystore -srckeystore jira-ldap.pkcs12 -srcstoretype PKCS12 -destkeystore /opt/atlassian/jira/jira-ldap.jks -deststoretype JKS
Configure Jira to use the newly created keystore. Follow the directions here to add options:

“-Djavax.net.ssl.keyStore=/opt/atlassian/jira/jira-ldap.jks -Djavax.net.ssl.keyStorePassword=password”

On Linux:
1. Edit /opt/atlassian/jira/bin/setenv.sh.
2. Find the JVM_SUPPORT_RECOMMENDED_ARGS setting.
3. Add “-Djavax.net.ssl.keyStore=/opt/atlassian/jira/jira-ldap.jks -Djavax.net.ssl.keyStorePassword=password”, replacing “password” with the password you selected above.
Restart Jira.

$ /opt/atlassian/jira/bin/stop-jira.sh $ /opt/atlassian/jira/bin/start-jira.sh
Sign in to the Jira web interface as an administrator.
1. Go to Settings > User management. (For settings, go to the gear icon in the upper right.)
2. Click User Directories.
3. Click Add Directory.
4. Choose LDAP as the type.
5. Click Next.

Enter the following:

Name	Google Secure LDAP
Directory type	OpenLDAP
Hostname	ldap.google.com
Port	636
Use SSL	Checked
Username	Generate a username and password in the Google Admin console. For instructions, see Generate access credentials.
Password	Generate a username and password in the Google Admin console. For instructions, see Generate access credentials.
Base DN	Your domain name in DN format. (for example, dc=example,dc=com for example.com)
Additional User DN	Optional. “ou=Users”
Additional Group DN	Optional. “ou=Groups”
LDAP Permissions	Read only
Advanced Settings	Unchanged
User Schema Settings > User Name Attribute	googleUid
User Schema Settings > User Name RDN Attribute	uid
Group Schema Settings > Group Object Class	groupOfNames
Group Schema Settings > Group Object Filter	(objectClass=groupOfNames)
Membership Schema Settings > Group Members Attribute	member
Membership Schema Settings > Use the User Membership Attribute	Checked

Grant a role to a group.

Before Atlassian Jira can allow a user to log in, that user must be a member of a group that's granted access to Jira.

To grant a role to a group:
1. Go to Settings > Applications > Application access.
2. In the Select group text box, enter the name of the Google group for which you want to provide access to Jira.

CloudBees Core / Jenkins

For instructions on connecting CloudBees Core to the Secure LDAP service, see Configure CloudBees Core with Google's Cloud Identity Secure LDAP.

FreeRadius

Follow these steps:

Install and configure FreeRADIUS at /etc/freeradius/3.0/.

Once FreeRADIUS is installed, you can add the LDAP configuration by installing the freeradius-ldap plugin.

$ sudo apt-get install freeradius freeradius-ldap
Copy the LDAP client key and cert files to /etc/freeradius/3.0/certs/ldap-client.key and /etc/freeradius/3.0/certs/ldap-client.crt respectively.

$ chown freeradius:freeradius /etc/freeradius/3.0/certs/ldap-client.* $ chmod 640 /etc/freeradius/3.0/certs/ldap-client.*
Enable the LDAP module.

$ cd /etc/freeradius/3.0/mods-enabled/ $ ln -s ../mods-available/ldap ldap
Edit /etc/freeradius/3.0/mods-available/ldap.
1. ldap->server = 'ldaps://ldap.google.com:636'
2. identity = username from the application credentials
3. password = password from the application credentials
4. base_dn = ‘dc=domain,dc=com’
5. tls->start_tls = no
6. tls->certificate_file = /etc/freeradius/3.0/certs/ldap-client.cer
7. tls->private_key_file = /etc/freeradius/3.0/certs/ldap-client.key
8. tls->require_cert = ‘allow’
9. Comment out all fields in the breadcrumb representing the section 'ldap -> post-auth -> update'
Edit /etc/freeradius/3.0/sites-available/default.
This modifies the FreeRadius client connection. If you are not using the default client, be sure to update the relevant client (inner-tunnel or any custom client) that you have configured.
1. Modify the authorize section to add the following block at the bottom after the password authentication protocol (PAP) statement:
  
  if (User-Password) { update control { Auth-Type := ldap } }
2. In the authorize section, enable LDAP by removing the ‘-’ sign before it.
  
  #
  # The ldap module reads passwords from the LDAP database.
  ldap
3. Modify the authenticate section by editing the Auth-Type LDAP block as follows:
  
  # Auth-Type LDAP { ldap # }
4. Modify the authenticate section by editing the Auth-Type PAP block as follows:
  
  Auth-Type PAP { # pap ldap }

GitLab

For instructions on connecting GitLab to the Secure LDAP service, see Configure Google Secure LDAP for GitLab.

Itopia/Ubuntu

For instructions on connecting Itopia/Ubuntu to the Secure LDAP service, see Configuring Google Cloud Identity LDAP on Ubuntu 16.04 for user logins.

Ivanti / LanDesk

Follow these steps:

On your Ivanti Web server, open OpenLDAPAuthenticationConfiguration.xml or OpenLDAPSSLAuthenticationConfiguration.xml in a text editor in both of the following folders:

C:\ProgramData\LANDesk\ServiceDesk\servicedesk.Framework and C:\ProgramData\LANDesk\ServiceDesk\servicedesk.WebAccess (where servicedesk is the instance name)
Update the <Server> value to ldap.google.com.
Update the <Port> value to port 3268 for clear text with StartTLS enabled and to 3269 for SSL/TLS Port (the defaults are 389 for the clear text port or 636 for the SSL/TLS port).
Set the <TestDN> value to your domain name in DN format. (for example, dc=example,dc=com for example.com).
To both ..ProgramData\LANDesk\ServiceDesk\ServiceDesk.Framework\tps.config, and ..ProgramData\LANDesk\ServiceDesk\WebAccess\tps.config, add the line:

<add key="AuthenticationProvider" value="Touchpaper.Integrations.OpenLDAPLogon.OpenLDAPAuthenticationProvider" />

or the line:

<add key="AuthenticationProvider" value="Touchpaper.Integrations.OpenLDAPSSLLogon.OpenLDAPSSLAuthenticationProvider" />
In the Ivanti Configuration Center, open the required instance.
Adjacent to the Service Desk Framework application, click Edit.
The Edit Application dialog for the Service Desk Framework appears.
In the Configuration parameters group, select Explicit only in the Logon policy list, then click OK.
Adjacent to the Web Access application, click Edit.
The Edit Application dialog for Web Access appears.
In the Configuration parameters group, select Explicit only in the Logon policy list, and then click OK.

When logging in, use the associated domain user's network password.

Exception logging for LDAP server authentication

If you're having problems configuring LDAP server authentication, you can enable exception logging to help you to identify the problem. By default, this is disabled, and we recommend that you disable the exception logging again when you have finished your investigations.

To enable exception logging for LDAP Server authentication:

Open the appropriate authentication configuration XML file in a text editor:

DirectoryServiceAuthenticationConfiguration.xml, OpenLDAPAuthenticationConfiguration.xml, or OpenLDAPSSLAuthenticationConfiguration.xml
Change the line:

<ShowExceptions>false</ShowExceptions>
to
<ShowExceptions>true</ShowExceptions>
Save the changes.

Ldp.exe (Windows)

Follow these steps:

Convert the certificate and key files to one PKCS12 formatted file. At a command prompt, enter the following:

If you are in macOS or Linux, use the following commands:

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

Enter a password to encrypt the output file.

If you are in Windows, use the following commands:

$ certutil -mergepfx ldap-client.crt ldap-client.p12

Important: The two files (<CERT_FILE>.crt and <CERT_FILE>.key) must be located in the same directory. Also, make sure both key and crt have an identical name (with a different extension). In this example, we use the names ldap-client.crt and ldap-client.key.
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, LDP.exe displays the Active Directory contents—such as all attributes present in the base DN—in the right pane.

Netgate / pfSense

For instructions on connecting Netgate/pfSense to the Secure LDAP service, see Configuring Google Cloud Identity as an Authentication Source.

OpenLDAP / ldapsearch (Linux)

To access your LDAP directory from the command line, you may use the OpenLDAP ldapsearch command.

Assuming your client certificate and key files are ldap-client.crt and ldap-client.key, your domain is example.com, and the username is jsmith:

$ LDAPTLS_CERT=ldap-client.crt LDAPTLS_KEY=ldap-client.key ldapsearch -H ldaps://ldap.google.com -b dc=example,dc=com '(uid=jsmith)'

This sets the relevant environment variables to point to the client keys. You can replace the other ldapsearch options with your desired filters, requested attributes, and so on. For other details, please see the ldapsearch man pages (“man ldapsearch”).

ldapsearch (macOS)

Follow these steps:

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 your password to encrypt the output file.
Click in the upper-right corner of the menu bar, and type Keychain Access.
Open the Keychain Access application, and from the list on the left, click System.
Click the File option in the top-left menu bar and select Import Items.
Browse to the location with the generated ldap-client.p12, select ldap-client.p12, and click Open.
If prompted, enter your password.
A certificate with the name LDAP Client should now appear on the list of System Keychain certificates.
Click the arrow next to the LDAP Client certificate. A private key appears below that.
1. Double-click the private key.
2. From the dialog box, select the Access Control tab and click + in the lower-left corner.
3. From the window that opens, type Command+Shift+G to open a new window, and then replace the existing text with /usr/bin/ldapsearch.
4. Click Go.
  
  This opens a window with ldapsearch highlighted.
5. Click Add.
6. Click Save Changes, and enter your password if prompted.
  
  You are now ready to access your LDAP directory from the command line, using the OpenLDAP ldapsearch command.
Assuming the ldap-client.p12 file that you imported into the keychain earlier has the name LDAP Client, your domain is example.com, and the username is jsmith, enter the following:

$ LDAPTLS_IDENTITY="LDAP Client" ldapsearch -H ldaps://ldap.google.com:636 -b dc=example,dc=com '(uid=jsmith)'

This sets the relevant environment variables to point to the imported client certificate. You can replace the other ldapsearch options with your desired filters, requested attributes, and so on. For more details, please see the ldapsearch man pages (man ldapsearch).

OpenVPN (community version)

Follow these steps:

If needed, install and configure OpenVPN, or if you have already done so, open the settings page in OpenVPN.

General VPN configuration is beyond the scope of this help article. Once a VPN is configured, you may add user authentication and authorization via LDAP. In particular, you will need to install the openvpn-auth-ldap plugin.

$ sudo apt-get install openvpn openvpn-auth-ldap
Copy the LDAP client key and cert files to /etc/openvpn/ldap-client.key and /etc/openvpn/ldap-client.crt.
Create a file, /etc/openvpn/auth-ldap.conf, containing the following (assuming that example.com is the domain name):

<LDAP> URL ldaps://ldap.google.com:636 # Timeout 15 TLSEnable false TLSCACertDir /etc/ssl/certs TLSCertFile /etc/openvpn/ldap-client.crt TLSKeyFile /etc/openvpn/ldap-client.key </LDAP> <Authorization> BaseDN "dc=example,dc=com" SearchFilter "(uid=%u)" # (or choose your own LDAP filter for users) RequireGroup false </Authorization>
Edit the OpenVPN configuration file, often named /etc/openvpn/server.conf, or similar. At the bottom of the file, add the following:

plugin /usr/lib/openvpn/openvpn-auth-ldap.so /etc/openvpn/auth-ldap.conf verify-client-cert optional
Restart the OpenVPN server.

$ sudo systemctl restart openvpn@server
Configure the VPN clients to use the users’ usernames and passwords. For example, in an OpenVPN client configuration, add auth-user-pass to the end of the OpenVPN client configuration file and start the OpenVPN client:

$ openvpn --config /path/to/client.conf
Follow instructions for using stunnel as a proxy.

OpenVPN Access Server (commercial version)

For instructions on connecting OpenVPN Access Server to the Secure LDAP service, see Configuring Google Secure LDAP with OpenVPN Access Server.

PaperCut MF and NG

For instructions on connecting PaperCut to the Secure LDAP service, see How to sync and authenticate Google Workspace and Google Cloud Identity users in PaperCut.

Puppet Enteprise

For instructions on connecting Puppet Enterprise to the Secure LDAP service, see Google Cloud Directory for PE.

Softerra LDAP Browser

Important: Before you begin, be sure you've installed Softerra LDAP Browser with version number 4.5 (4.5.19808.0) or later. See LDAP Browser 4.5.

Follow these steps:

Convert the certificate and key files to one PKCS12 formatted file. At a command prompt, enter the following:

If you are in macOS or Linux, use the following commands:

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

Enter a password to encrypt the output file.

If you are in Windows, use the following commands:

$ certutil -mergepfx ldap-client.crt ldap-client.p12

Important: The two files (<CERT_FILE>.crt and <CERT_FILE>.key) must be located in the same directory. Also, make sure both key and crt have an identical name (with a different extension). In this example, we use the names ldap-client.crt and ldap-client.key.
In the Softerra LDAP Browser, install the key pair.
1. Go to Tools > Certificate Manager.
2. Click Import…
3. Click Next.
4. Click Browse…
5. In the File type drop-down list in the lower-right corner of the dialog box, select Personal Information Exchange (*.pfx;*.p12).
6. Select the ldap-client.p12 file from step 2 above.
7. Click Open and then click Next.
8. Enter the password from step 2 above, and click Next.
9. Select the Personal certificate store.
10. Click Next.
11. Click Finish.
Add a server profile.
1. Go to File > New > New Profile…
2. Enter a name for the profile, such as Google LDAP.
3. Click Next.
  
  Enter the following:
  
  Host: ldap.google.com
  Port: 636
  Base DN: Your domain name in DN format. (eg. dc=example,dc=com for example.com)
  Use secure connection (SSL): Checked
4. Click Next.
5. Select External (SSL Certificate).
6. Click Next.
7. Click Finish.

Sophos Mobile

For instructions on connecting Sophos Mobile to the Secure LDAP service, see Connecting Sophos Mobile to Google Cloud Identity / Google Cloud Directory using Secure LDAP.

Splunk

When connecting Splunk to the Secure LDAP service, be sure to use Splunk version 8.1.4 or later. When using older Splunk versions such as Splunk version 8.1.3, excessive LDAP queries might be sent to the LDAP server, which could result in your LDAP quota being exhausted quickly. For more information about Splunk version 8.1.3 issues, see Splunk known issues.

Follow these steps:

Copy the LDAP client key and cert files to /home/splunk/splunkadmin/etc/openldap/certs/ldap-client.key and /home/splunkadmin/splunk/etc/openldap/certs/ldap-client.crt.

$ cat /home/splunkadmin/splunk/etc/openldap/certs/ldap-client.crt /home/splunkadmin/splunk/etc/openldap/certs/ldap-client.key > /home/splunkadmin/splunk/etc/openldap/certs/ldap-client.pem $ sudo chown $(splunkuser):$(splunkuser) /home/splunkadmin/splunk/etc/openldap/certs/ldap-client.* $ sudo chmod 644 /home/splunkadmin/splunk/etc/openldap/certs/ldap-client.*
Edit the ldap.conf file to add the following configs:
ssl start_tls TLS_REQCERT never TLS_CERT /home/splunkadmin/splunk/etc/openldap/certs/ldap.pem TLS_KEY /home/splunkadmin/splunk/etc/openldap/certs/ldap.pem
Add the following configs in the user's /home/splunkadmin/.ldaprc file:

TLS_CERT /home/splunkadmin/splunk/etc/openldap/certs/ldap-client.pem TLS_KEY /home/splunkadmin/splunk/etc/openldap/certs/ldap-client.pem
Add the LDAP strategy using the Splunk web UI. Enter the following details, and then click Save:

Name	Google Secure LDAP
Host	ldap.google.com
Port	636
SSL enabled	Checked
Connection order	1
Bind DN	Enter the access credentials that you generated in the Google Admin console.
Bind DN password	Enter the access credentials that you generated in the Google Admin console.
Base DN	Your domain name in DN format (for example, dc=example,dc=com for the domain, example.com)
User base filter	Enter the User base filter for the object class you want to filter your users on.
User name attribute	uid
Real name attribute	displayname
Email attribute	mail
Group mapping attribute	dn
Group base DN	Your domain name in DN format (for example, ou=Groups,dc=example,dc=com for the domain, example.com)
Static group search filter	Enter the Static group search filter for the object class you want to filter your static groups on.
Group name attribute	cn
Static member attribute	member

SSSD (Red Hat Enterprise and CentOS)

SSSD performs a user lookup to get more information about a user during user authentication. To make sure user authentication works correctly for this LDAP client, you'll need to turn on Read user information and Read group information for all organizational units where Verify user credentials is turned on. (For instructions, see Configure access permissions.)

To connect an SSSD client on Red Hat 8 or CentOS 8 to the Secure LDAP service:

Add the SSSD client to the Secure LDAP service:
1. From the Google Admin console, go to Apps > LDAP > ADD CLIENT.
  Be sure to sign in with your corporate account, and not with your personal Gmail account.
2. Enter the Client details, and click CONTINUE.
3. Configure the Access permissions:
  Verify user credentials—Entire domain
  Read user information—Entire domain
  Read group information—On
4. Click ADD LDAP CLIENT.
5. Download the generated certificate.
6. Click CONTINUE TO CLIENT DETAILS.
7. Change the Service status to ON.
Install dependencies:

dnf install openldap-clients sssd-ldap install -d --mode=700 --owner=sssd --group=root /etc/sssd/ldap

unzip certificate .zip file and copy the .crt and .key files to /etc/sssd/ldap
(Optional) Test with ldapsearch:
LDAPTLS_REQCERT=never \ LDAPTLS_KEY=Google.key \ LDAPTLS_CERT=Google.crt \ ldapsearch -H ldaps://ldap.google.com:636/ \ -b dc=example,dc=com \ -D usertoverify@example.com \ -W \ '(mail=usertoverify@example.com)' \ mail dn

Enter the user's Google password when prompted.

Note: The user must have a Google Workspace Enterprise or Cloud Identity Premium license assigned to them.
Create the file /etc/sssd/sssd.conf with the following contents:

[sssd] services = nss, pam domains = example.com

[domain/example.com] ldap_tls_cert = /etc/sssd/ldap/Google.crt ldap_tls_key = /etc/sssd/ldap/Google.key ldap_tls_reqcert = never ldap_uri = ldaps://ldap.google.com ldap_search_base = dc=example,dc=com id_provider = ldap auth_provider = ldap ldap_schema = rfc2307bis ldap_user_uuid = entryUUID
Update the permissions and SELinux labels:

chown 0:0 /etc/sssd/sssd.conf /etc/sssd/ldap/* chmod 600 /etc/sssd/sssd.conf /etc/sssd/ldap/* restorecon -FRv /etc/sssd
Restart SSSD:

systemctl restart sssd
Test:

ssh to server:
ssh -l user@example.com {HOSTNAME}

Troubleshooting

Check SSSD version (must be greater than or equal to 1.15.2):

# sssd --version 2.2.3
On RHEL/CentOS (or any distro with SELinux enforcement), the SSSD config files and certificate file and key must be in a directory accessible by the sssd_conf_t role:

# egrep "object_r:sssd_conf_t" /etc/selinux/targeted/contexts/files/file_contexts

Check the /var/log/audit/audit.log for AVC deny messages.
Check that /etc/nsswitch.conf has "sss" for the passwd, shadow, group, and netgroup entities:

passwd: files sss shadow: files sss group: files sss netgroup: files sss

Here, local files will override LDAP users.
Check /var/log/sssd.conf for config errors:

Example:
[sssd] [sss_ini_add_snippets] (0x0020): Config merge error: File /etc/sssd/sssd.conf did not pass access check. Skipping.

Action: You need to chmod 600 the .conf file.

Example:
[sssd] [sss_ini_call_validators] (0x0020): [rule/allowed_domain_options]: Attribute 'ldap_groups_use_matching_rule_in_chain' is not allowed in section 'domain/{DOMAIN}'. Check for typos.

[sssd] [sss_ini_call_validators] (0x0020): [rule/allowed_domain_options]: Attribute 'ldap_initgroups_use_matching_rule_in_chain' is not allowed in section 'domain/{DOMAIN}'. Check for typos.

Action: Remove the unsupported group match LDAP extensions from sssd.conf.
Check /var/log/sssd_{DOMAIN}.log for LDAP/network/auth errors.

Example:

[sssd[be[example.com]]] [sss_ldap_init_sys_connect_done] (0x0020): ldap_install_tls failed: [Connect error] [error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed (self signed certificate)]

Action: You need to add "ldap_tls_reqcert = never" to sssd.conf.

To increase verbosity of errors, add "debug_level = 9" in sssd.conf under the domain section and restart sssd.

SSSD (other Linux distributions)

To connect an SSSD client to the Secure LDAP service:

Install SSSD version >= 1.15.2.

$ sudo apt-get install sssd
Assuming your client cert and key files are named /var/ldap-client.crt and /var/ldap-client.key and your domain is example.com, edit /etc/sssd/sssd.conf with a configuration such as:

[sssd]
services = nss, pam
domains = example.com

[domain/example.com]
ldap_tls_cert = /var/ldap-client.crt
ldap_tls_key = /var/ldap-client.key
ldap_uri = ldaps://ldap.google.com
ldap_search_base = dc=example,dc=com
id_provider = ldap
auth_provider = ldap
ldap_schema = rfc2307bis
ldap_user_uuid = entryUUID
ldap_groups_use_matching_rule_in_chain = true
ldap_initgroups_use_matching_rule_in_chain = true
Change ownership and permission of the config file:

$ sudo chown root:root /etc/sssd/sssd.conf $ sudo chmod 600 /etc/sssd/sssd.conf
Restart SSSD:

$ sudo service sssd restart

Tip: If you're using the SSSD module on Linux computers without external IP addresses on Google Compute Engine, you can still connect to the Secure LDAP service as long as you have internal access to Google services enabled. For details, see Configuring Private Google Access.

macOS

Follow the steps below to connect the macOS client for user account authentication using the Secure LDAP service.

System requirements

The macOS must be Catalina Version 10.15.4 or later.
A Google super admin user ID is required to complete step 1 in the preparation phase.
You need local admin permissions to perform this configuration.

Preparation phase

The instructions in this section focus on how to manually set up and test macOS authentication using the Secure LDAP service.

Step 1: Onboard macOS as an LDAP client in the Google Admin console

For instructions, see Add LDAP clients, or watch this Secure LDAP demo. You will also download an auto-generated TLS client certificate during this process.

Step 2: Import the certificate into the system keychain

Copy the certificate (the zip file downloaded in step 1) and key to the macOS machine.
Tip: Unzip the file to find cert and key files.
Import the key pair into the system keychain:
1. Convert the key and cert into a PKCS 12 (p12) file. Run the following command in the terminal:
  
  openssl pkcs12 -export -out ldap-client.p12 -in ldap-client.crt -inkey ldap-client.key
  
  Tip: Write down the name of the .p12 file.
  
  The system will ask you to enter a password. Enter a password with which to encrypt the p12 file.
2. Open the Keychain Access application.
3. Click on the System keychain.
4. Click File > Import Items.
5. Select the ldap-client.p12 file created above.
6. If prompted, enter the admin password to allow modification of the system keychain.
7. Enter the password you created above to decrypt the .p12 file.
  Note: Expect to see a new cert and associated private key show up in the list of keys. It may be called LDAP Client. Write down the cert’s name for the next step below.
8. Follow step 6 in the ldapsearch (macOS) section in this article to set up Access Control for the private key to add apps specified below. If the private key is not showing under the All Items category, try to switch to the My Certificates category, and locate the correct private key entry by expanding the corresponding certificate.
  
  The ldapsearch app, as specified in the instructions, is relevant only if troubleshooting is needed, and not for other purposes. It’s typically removed before providing users access to macOS.
  
  The following three apps must be added to the Access Control list:
  
  /System/Library/CoreServices/Applications/Directory Utility /usr/libexec/opendirectoryd /usr/bin/dscl
Add a line to the /etc/openldap/ldap.conf file, ensuring that "LDAP Client" is exactly the same certificate name as shown in the macOS Keychain Access application after importing the .p12 file (the name comes from the X.509 Subject Common Name of the generated certificate):

sudo bash -c 'echo -e "TLS_IDENTITY\tLDAP Client" >> /etc/openldap/ldap.conf'

Step 3: Point the device to Google directory for authentication

Open the Directory Utility application to create a new LDAP directory node:

Click the lock to make changes and enter your password.
Select LDAPv3 and click the pencil icon to edit settings.
Click New…
For the server name, enter ldap.google.com, select Encrypt using SSL, and click Manual.
Select the new server name and click Edit…
Enter a descriptive name such as Google Secure LDAP for the configuration name.
Select Encrypt using SSL and make sure the port is set to 636.
Go to the Search & Mappings tab.
1. Choose RFC2307 from the Access this LDAPv3 server using dropdown list.
2. When prompted, enter the domain-related information into Search Base Suffix. For example, enter dc=zomato,dc=com for a domain name of zomato.com.
3. Click OK.
4. Configure attributes under the Users record type:
  1. In the Record Types and Attributes section, select Users and click the “+” button.
  2. In the popup window, choose Attribute Types, select GeneratedUID, and then click OK to close the popup window.
    
    GeneratedUID should be displayed under Users after it’s expanded.
  3. Click on the GeneratedUID, and click the “+” icon in the box on the right.
  4. Enter apple-generateduid in the text box, and click Enter.
  5. Under the Users node, click the NFSHomeDirectory attribute.
  6. In the screen on the right, update the value for this attribute to #/Users/$uid$
  7. Click OK and enter your password to save the changes.
From the Directory Utility window, configure the new LDAP config:
1. Go to Search Policy tab.
2. Click the lock icon to make changes, and enter the password of the current user when prompted.
3. Change the dropdown option from Search Path to Custom path.
4. Open the Authentication tab and click the “+” icon.
5. Choose /LDAPv3/ldap.google.com from the Directory Domains list, and then click Add.
6. Click the Apply button, and enter your admin password if prompted.
Run the following four commands to disable the DIGEST-MD5, CRAM-MD5, NTLM, and GSSAPI SASL authentication mechanisms. The macOS will use Simple Bind to authenticate using the Google Secure LDAP service:

sudo /usr/libexec/PlistBuddy -c "add ':module options:ldap:Denied SASL Methods:' string DIGEST-MD5" /Library/Preferences/OpenDirectory/Configurations/LDAPv3/ldap.google.com.plist sudo /usr/libexec/PlistBuddy -c "add ':module options:ldap:Denied SASL Methods:' string CRAM-MD5" /Library/Preferences/OpenDirectory/Configurations/LDAPv3/ldap.google.com.plist sudo /usr/libexec/PlistBuddy -c "add ':module options:ldap:Denied SASL Methods:' string NTLM" /Library/Preferences/OpenDirectory/Configurations/LDAPv3/ldap.google.com.plist sudo /usr/libexec/PlistBuddy -c "add ':module options:ldap:Denied SASL Methods:' string GSSAPI" /Library/Preferences/OpenDirectory/Configurations/LDAPv3/ldap.google.com.plist
Reboot to reload the OpenDirectory configuration.

Step 4: Create a mobile account (allows offline login)

Any Google Workspace or Cloud Identity user can log in using a network account (Google account) using their username and password. This login process needs network connectivity. If a user needs to log in with or without connection to the network, a mobile account can be created. A mobile account lets you use your network account (Google account) username and password to sign in, whether or not you’re connected to the network. For more details, see Create and configure mobile accounts on Mac.

To create a mobile account for Secure LDAP users:

Run the following command to connect to the Secure LDAP server and set up a home path and mobile account(s):

sudo /System/Library/CoreServices/ManagedClient.app/Contents/Resources/createmobileaccount -n $uid -v

Tip: Replace $uid with the username part of the email address associated with the user’s Google account. For example, jsmith is the username part for jsmith@solarmora.com.
When prompted for the SecureToken admin user name, enter your admin username, and enter your password in the next prompt. This will add $uid into the FileVault. This is needed if the macOS disk is encrypted.

Step 5: (Optional) Set the login screen preference

Go to System preferences > Users & Groups > Login Options at the bottom left.
Unlock the lock by providing admin credentials.
Change the Display login window as to Name and password.

Step 6: Reboot and log in to your device

Make sure the device is connected to the Internet. If you don’t have an internet connection, the login for the Secure LDAP user will not work.
Note: Internet connection is needed only for the first login. Any subsequent logins can occur without Internet access.
Sign in to the device with the user account that's configured to use Secure LDAP for authentication.

Deployment phase

The instructions in this section focus on automating the device configuration for your users. Perform steps 1 and 2 below on the same macOS device where you completed your manual configuration during the preparation phase.

Step 1: Create a Mac Profile with certificate using Apple Configurator 2

Install Apple Configurator 2 on the machine where you manually configured macOS authentication with Secure LDAP.
Open Apple Configurator 2, create a new profile and in the Certificate section, click Configure, and import the previously generated .p12 file.
Note: Make sure this .p12 has a password. Enter this password in the Password section of the Certificate.
Save this Profile.
Open this profile in any text editor and add the following lines in first <dict> tag:

<key>PayloadScope</key> <string>System</string>

This is added, as Apple Configurator does not support profiles for macOS yet.
In the second <dict> tag, parallel to certificate data, add the following lines:

<key>AllowAllAppsAccess</key> <true/>

This will make sure that this certificate can be accessed by all applications.

Step 2: Convert Directory config file (plist) to xml

In this step, you are extracting all the manual configurations that you completed during step 3 of the preparation phase into a XML file. You can use this file and the Mac profile created in step 1 above to automatically configure other macOS devices.

Copy /Library/Preferences/OpenDirectory/Configurations/LDAPv3/ldap.google.com.plist to your desktop or elsewhere.
Convert it to XML so that you can inspect it in any text editor. Run the following command in Terminal:

sudo plutil -convert xml1 <path>/ldap.google.com.plist

You can access the file as <path>/ldap.google.com.plist.
Change the permission of the above file so that you can open the XML file. Make sure it is not empty.

Step 3: Create a python script to automate the configuration on your end-user devices

Copy the python script below and save it as a python file (.py file).

Note: This sample script is provided on an as-is basis. Google support will not provide support for sample scripts.

Ldap_pythong_config.py

#!/usr/bin/python from OpenDirectory import ODNode, ODSession, kODNodeTypeConfigure from Foundation import NSMutableData, NSData

import os import sys

# Reading plist GOOGLELDAPCONFIGFILE = open(sys.argv[1], "r") CONFIG = GOOGLELDAPCONFIGFILE.read() GOOGLELDAPCONFIGFILE.close()

# Write the plist od_session = ODSession.defaultSession() od_conf_node, err = ODNode.nodeWithSession_type_error_(od_session, kODNodeTypeConfigure, None) request = NSMutableData.dataWithBytes_length_(b'\x00'*32, 32) request.appendData_(NSData.dataWithBytes_length_(CONFIG, len(CONFIG))) response, err = od_conf_node.customCall_sendData_error_(99991, request, None)

# Edit the default search path and append the new node to allow for login os.system("dscl -q localhost -append /Search CSPSearchPath /LDAPv3/ldap.google.com") os.system("bash -c 'echo -e \"TLS_IDENTITY\tLDAP Client\" >> /etc/openldap/ldap.conf' ")

Step 4: Auto configure end-user devices

Go to other macOS devices that you would like to configure and follow these steps:

Copy the Mac Profile file generated in step 1, XML config file generated in step 2, and the python script from step 3 to the device.
Run the following command:

sudo python </path/to/saved_python_script> </path/to/ldap.google.com.plist generated in step 2>
To import certificates into the macOS system keychain, double-click on the Mac profile file generated in step 1, and when prompted provide your macOS local admin credentials. You will then be prompted to enter the .p12 password that you set during the preparation phase.
Restart the macOS machine.
Create mobile accounts as instructed in step 4 of the preparation phase, and optionally set additional preferences outlined in step 5 of the preparation phase.

Limitations and guidelines

For users signing in to macOS using their Google credentials, their Workspace account username must be different from their macOS user profile user ID, or sign-in is blocked.
Once a user starts signing in to macOS using Google credentials, user password management (reset or recovery) must happen on the Google website (for example, at myaccount.google.com or in the Google Admin console). If you choose to do password management using a third-party solution, then make sure the latest password is synchronized with Google.
If the admin creates a new user or resets an existing user’s password with the Ask for a password change at the next sign-in setting turned on, the user cannot sign in to Mac using the temporary password set by the admin.
Workaround: The user needs to sign in to Google using another device (for example, their mobile device or other desktop device), set a permanent password, and then sign in to macOS using the new password.
The Mac must be connected to a working internet connection so that ldap.google.com is reachable during the first sign-in after the above configuration. Any subsequent sign-ins won't need Internet access as long as you opted to set up a mobile account.
Google Secure LDAP integration with macOS is tested on macOS Catalina and Big Sur.

Troubleshooting

If you have problems connecting to the Secure LDAP service, follow the instructions below.

Step 1: Verify the connection.

Verify the connection using odutil.
Run the odutil show nodenames command in the terminal.
Verify that the /LDAPv3/ldap.google.com status is online. If it's not online, try the telnet option.

Verify the connection using nc.
Execute the following command in the terminal: nc -zv ldap.google.com 636
If you aren't able to connect to Google using this approach, try connecting using IPv4.

Verify the connection with IPv4.
You can change your device to use IPv4 using the following steps:

Go to System Preferences > Network > Wi-Fi > Advanced.
Under the Advanced menu, go to the TCP/IP tab.
Change the drop-down selection from Configure IPv6 to Link-local only.
Click OK, and then click Apply to save the changes.
Check service authentication via ldapsearch connectivity and valid search.

Step 2: Check whether you are able to see directory objects.

Open Directory Utility, and then open the Directory Editor tab.
Select the /LDAPv3/ldap.google.com node in the drop-down list.
Verify whether you are able to see users and groups from your Google domain.

Configuration instructions for Java applications

Most Java-based applications that offer LDAP functionality can be configured to authenticate with client certificates by installing your client certificates in the application’s keystore. The exact configuration files will differ among applications, but the process is generally similar. Setup requires that OpenSSL and a Java Runtime Environment are installed.

Convert the certificate and keys to Java keystore format. You will be prompted for passwords throughout this process. Select a secure password and use the same one through all of the prompts. Assuming your client key file is named ldap-client.key:

If you are in macOS or Linux, use the following commands:

$ openssl pkcs12 -export -out java-application-ldap.pkcs12 -in ldap-client.crt -inkey ldap-client.key

If you are in Windows, use the following commands:

$ certutil -mergepfx ldap-client.crt java-application-ldap.pkcs12

Important: The two files (<CERT_FILE>.crt and <CERT_FILE>.key) must be located in the same directory. Also, make sure both key and crt have an identical name (with the two different extensions). In this example, we use the names ldap-client.crt and ldap-client.key.
Import the certificate into keystore:

$ keytool -v -importkeystore -srckeystore java-application-ldap.pkcs12 -srcstoretype PKCS12 -destkeystore java-application-ldap.jks -deststoretype JKS
Java properties may be configured in different ways depending on the application. Often, you can set them with the -D option on the “java” command line used to start it. Set the Java properties for your application:

javax.net.ssl.keyStore = /<path-to>/java-application-ldap.jks javax.net.ssl.keyStorePassword = <password selected above>
Configure the application’s LDAP connection settings, using the information in Basic configuration instructions.

Optional: Use stunnel as a proxy

For clients that don't offer a way to authenticate to LDAP with a client certificate, use stunnel as a proxy.

Configure stunnel to provide the client certificate to the LDAP server and configure your client to connect to stunnel. Ideally, you'll run stunnel on the same server(s) as your application and only listen locally so that you don't expose your LDAP directory beyond that server.

Follow these steps:

Install stunnel. For example, on Ubuntu:

$ sudo apt-get install stunnel4
Create a configuration file /etc/stunnel/google-ldap.conf with the following contents (assuming ldap-client.crt is the cert, and ldap-client.key is the key):

[ldap]
client = yes
accept = 127.0.0.1:1636
connect = ldap.google.com:636
cert = ldap-client.crt
key = ldap-client.key
To enable stunnel, edit /etc/default/stunnel4 and set ENABLED=1.
Restart stunnel.

$ sudo /etc/init.d/stunnel4 restart
Configure your application to point to ldap://127.0.0.1:1636.

You can replace “1636” with any unused port if you also change the accept line in the configuration file above. You'll need to use plaintext LDAP without StartTLS/SSL/TLS enabled between the client and stunnel, since they are communicating locally.

Note: If you choose to run stunnel on a separate server, you must configure your firewalls so that only the necessary applications can access your stunnel server. You can also configure stunnel to listen with TLS so that data between your application and stunnel servers is encrypted. The details of both of these configurations depend on your environment.

Next steps

After you connect the LDAP client to the Secure LDAP service, you then need to switch the service status to On for the LDAP client.

For your next steps, see 5. Switch LDAP clients to On.

Note: If needed, you can use simple tools like ldapsearch, ADSI, or ldp.exe for troubleshooting if you encounter errors while trying to connect your LDAP client to the service. For instructions, see Connectivity testing and troubleshooting.

Was this helpful?

How can we improve it?

4. Connect LDAP clients to the Secure LDAP service

What's included in this article

Basic configuration instructions

Configuration instructions for specific LDAP clients

Exception logging for LDAP server authentication

Troubleshooting

System requirements

Contents:

Preparation phase

Step 1: Onboard macOS as an LDAP client in the Google Admin console

Step 2: Import the certificate into the system keychain

Step 3: Point the device to Google directory for authentication

Step 4: Create a mobile account (allows offline login)

Step 5: (Optional) Set the login screen preference

Step 6: Reboot and log in to your device

Deployment phase

Step 1: Create a Mac Profile with certificate using Apple Configurator 2

Step 2: Convert Directory config file (plist) to xml

Step 3: Create a python script to automate the configuration on your end-user devices

Step 4: Auto configure end-user devices

Limitations and guidelines

Troubleshooting

Configuration instructions for Java applications

Optional: Use stunnel as a proxy

Next steps

Related articles

Was this helpful?