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:

  • Before you get started
    Before using these instructions, make sure you have already added the client to the Secure LDAP service, configured access permissionsdownloaded a client certificate and key, and optionally created access credentials.
  • Connection testing and troubleshooting
    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 Connectivity testing and troubleshooting
  • 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.
  • 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:

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:

  1. Configure your LDAP client with Cloud Directory as your LDAP server.
  2. 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:

  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, 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:

  1. Click File > New…
  2. Select LDAP Browser > LDAP Connection.
  3. Click Next.
  4. 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.)
     
  5. Click Next.
  6. 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
     
  7. Click Next.
  8. Enter the base DN.
    This is your domain name in DN format (dc=example,dc=com for example.com).
  9. 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.)

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

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

  1. 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:
     
  2. 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

     
  3. 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.
  4. Restart Jira.

    $  /opt/atlassian/jira/bin/stop-jira.sh
    $  /opt/atlassian/jira/bin/start-jira.sh

     
  5. 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.
  6. 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

     

  7. 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:

  1. 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
     
  2. 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.*

     
  3. Enable the LDAP module.

    $  cd /etc/freeradius/3.0/mods-enabled/
    $  ln -s ../mods-available/ldap ldap

     
  4. 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'
  5. ​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:

  1. On your Ivanti Web server, open OpenLDAPAuthentifictionConfiguration.xml or OpenLDAPSSLAuthentifictionConfiguration.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)
     
  2. Update the <Server> value to ldap.google.com.
  3. 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). 
  4. Set the <TestDN> value to your domain name in DN format. (for example, dc=example,dc=com for example.com).
  5. 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" />
     
  6. In the Ivanti Configuration Center, open the required instance.
  7. Adjacent to the Service Desk Framework application, click Edit.
    The Edit Application dialog for the Service Desk Framework appears.
  8. In the Configuration parameters group, select Explicit only in the Logon policy list, then click OK.
  9. Adjacent to the Web Access application, click Edit.
    The Edit Application dialog for Web Access appears.
  10. 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:

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

    DirectoryServiceAuthentifictionConfiguration.xml, OpenLDAPAuthentifictionConfiguration.xml, or OpenLDAPSSLAuthentifictionConfiguration.xml
     
  2. Change the line:

    <ShowExceptions>false</ShowExceptions>
    to 
    <ShowExceptions>true</ShowExceptions>
     
  3. Save the changes.
Ldp.exe (Windows)

Follow these steps:

  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, 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:

  1. 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.
     
  2. Click Search in the upper-right corner of the menu bar, and type Keychain Access.
  3. Open the Keychain Access application, and from the list on the left, click System.
  4. Click the File option in the top-left menu bar and select Import Items.
  5. 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. 
  6. 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.

  7. 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:

  1. 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
     
  2. Copy the LDAP client key and cert files to /etc/openvpn/ldap-client.key and /etc/openvpn/ldap-client.crt.
  3. 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>

     
  4. 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

     
  5. Restart the OpenVPN server.

    $  sudo systemctl restart openvpn@server
     
  6. 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
     
  7. 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 G Suite 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:

  1. Install OpenSSL.
  2. Convert the certificate and key files to one PKCS12 formatted file. At a command prompt:

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

    Enter a password to encrypt the output file.
     
  3. 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.
  4. 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

Follow these steps:

  1. 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.*

     
  2. 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

  3.  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

     
  4. 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

(objectclass=*)

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, dc=example,dc=com for the domain, example.com)

Static group search filter

(objectclass=*)

Group name attribute

cn

Static member attribute

member

 

SSSD

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 to the Secure LDAP service:

  1. Install SSSD version  >= 1.15.2.

    $  sudo apt-get install sssd
     
  2. 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
     

  3. Change ownership and permission of the config file:

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

  4. 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

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.

  1. 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:

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

    $  keytool -v -importkeystore -srckeystore java-application-ldap.pkcs12 -srcstoretype PKCS12 -destkeystore java-application-ldap.jks -deststoretype JKS

     
  2. 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>

     
  3. 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:

  1. Install stunnel. For example, on Ubuntu:

    $  sudo apt-get install stunnel4
     
  2. 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
     
  3. To enable stunnel, edit /etc/default/stunnel4 and set ENABLED=1.
  4. Restart stunnel.

    $  sudo /etc/init.d/stunnel4 restart
     
  5. 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 ldapsearchADSI, 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.

Related articles

Was this helpful?
How can we improve it?