Mastering Google Workspace Secure LDAP Service: A Comprehensive Guide for Administrators

Introduction

The Google Workspace Secure LDAP service offers a streamlined and secure method to integrate your LDAP-based applications and services with Cloud Identity or Google Workspace. This guide provides comprehensive information for Google Workspace administrators to understand, set up, manage, and troubleshoot the Secure LDAP service, leveraging Cloud Directory as a robust cloud-based LDAP server for authentication, authorization, and directory lookups.

By utilizing Secure LDAP, organizations can minimize their reliance on traditional, on-premise directory servers, consolidating authentication and directory services within Google's cloud infrastructure. This service supports various LDAP-based applications and IT infrastructure, whether they are on-premise or hosted on Infrastructure-as-a-Service (IaaS) platforms like Google Compute Engine, AWS, or Azure.

Key Benefits

Centralized Directory: Use Google Cloud Directory as a single source of truth for user and group information for LDAP-based applications.
Enhanced Security: Secure communication using TLS client certificates as the primary authentication mechanism, with optional access credentials for clients requiring them.
Simplified Management: Manage LDAP clients and permissions directly from the Google Admin console.
Reduced Infrastructure: Decrease the footprint of traditional directory servers by pointing applications directly to Secure LDAP.
Comprehensive Logging: Access detailed audit logs for LDAP operations to monitor and investigate security events.

Supported Editions

The Secure LDAP service is available for various Google Workspace and Cloud Identity editions, including Frontline Standard and Plus, Business Plus, Enterprise Standard and Plus, Education Fundamentals, Standard and Plus, and Enterprise Essentials Plus.

Understanding the Secure LDAP Service

How it Works

The Secure LDAP service facilitates communication between your LDAP-based applications and Google Cloud Directory. It acts as a cloud-based LDAP server, allowing applications to query user and group information and authenticate users securely. The core of this service relies on TLS client certificates for authentication, with an optional username and password (access credentials) for clients that require them.

When a user account is suspended in Google Workspace or Cloud Identity, it cannot sign in to any associated applications, including LDAP applications. While suspended accounts cannot verify passwords via LDAP, their information can still be retrieved through an LDAP search by a client service.

It is important to note that configuring a third-party Identity Provider (IdP) or Single Sign-On (SSO) provider in Google Workspace or Cloud Identity does not impact the Secure LDAP service. Third-party IdPs only affect HTTP-based transactions (e.g., SAML-based authentication). For Secure LDAP connected applications, users must use their Google username and password for authentication, not their third-party IdP credentials.

Secure LDAP Schema

The Secure LDAP service exposes Google Cloud Directory objects to LDAP clients following a specific hierarchy and set of attributes.

Sample Hierarchy

The directory structure in Secure LDAP mirrors the organizational unit (OU) tree configured in your Google Admin console. Below is a sample hierarchy:

<root>
  cn=subschema
  dc=example,dc=com
    ou=Users
      ou=Sales
        uid=lisasmith
        uid=jimsmith
    ou=Groups
      cn=group1
      cn=group2

Key Attributes

Root: Contains server metadata, supported LDAP versions (currently LDAPv3), supported SASL mechanisms (EXTERNAL, PLAIN), and extensions like StartTLS.
Subschema: Provides a machine-readable definition of the LDAP server schema, including object classes, attribute types, and matching rules.
Domain: Represents your Google Workspace or Cloud Identity Premium domain (e.g., dc=example,dc=com). It contains subdomains, users, groups, and organizational units.
- objectClass: top, domain, dcObject
- dc: Domain component name
- hasSubordinates: TRUE
Organizational Unit (OU): An organizational unit within the directory tree, mirroring the structure in the Google Admin console. It can contain other OUs, users, and groups.
- objectClass: top, organizationalUnit
- ou: Name of the organizational unit
- description: Human-readable description
- hasSubordinates: TRUE
Person (User): Represents a user in the domain, appearing under their respective organizational units. Key attributes include:
- objectClass: top, person, organizationalPerson, inetOrgPerson, posixAccount
- uid: User's username (portion of email address)
- googleUid: Same as uid, for unambiguous distinction from posixUid
- posixUid: User's username or POSIX username if set
- cn: Common name (username and display name)
- sn: Surname
- givenName: Given name
- displayName: Full name
- mail: Email address
- memberOf: List of fully qualified group names
- title: User's title
- employeeNumber: User's employee ID
- employeeType: User's role
- departmentNumber: Department name
- physicalDeliveryOfficeName: Location/address
- jpegPhoto: User's profile photo (returned only when explicitly requested)
- entryUuid: Universally unique stable identifier (returned only when explicitly requested)
- objectSid: Windows-compatible security identifier (returned only when explicitly requested)
- uidNumber: POSIX UID number (searchable if set via Admin SDK API along with posixAccount systemId)
- gidNumber: POSIX GID number for primary group (searchable if set via Admin SDK API along with posixAccount systemId)
- homeDirectory: POSIX home directory (defaults to /home/<username>)
- loginShell: POSIX login shell (defaults to /bin/bash)
- gecos: GECOS (historical) attributes
- hasSubordinates: FALSE
Group: Represents a group within the domain.
- objectClass: top, groupOfNames, posixGroup
- cn: Group's domain-unique name
- displayName: Human-readable display name
- description: Longer human-readable description
- gidNumber: POSIX GID number (stable unique ID, but not efficiently searchable)
- entryUuid: Universally unique stable identifier
- objectSid: Windows-compatible security identifier
- member: List of fully qualified names of group members
- memberUid: List of usernames of group members
- googleAdminCreated: True if the group was created by an administrator
- hasSubordinates: FALSE

Setting Up the Secure LDAP Service

Setting up the Secure LDAP service involves a series of steps in the Google Admin console and on your LDAP clients.

Overview of Setup Steps

The general process for setting up the Secure LDAP service is as follows:

Add LDAP clients: Define the applications or services that will connect to Secure LDAP.
Configure access permissions: Specify which users and groups the LDAP client can access.
Download the generated certificate: Obtain the TLS client certificate and key for authentication.
Connect LDAP clients to the Secure LDAP service: Configure your applications to use the Secure LDAP service.
Switch LDAP clients to On: Activate the Secure LDAP service for the configured client.

Add LDAP Clients

First, you need to register your LDAP-based applications or services as "LDAP clients" within the Google Admin console. This step is the initial configuration before setting up access permissions or connecting the clients.

Configure Access Permissions

After adding an LDAP client, you must configure its access permissions. This involves specifying which organizational units (OUs) or groups the client can verify credentials for, read user information from, and read group information from. For example, if an LDAP client performs user lookups during authentication (like Atlassian Jira or SSSD), you need to enable "Read user information" for the relevant OUs.

Download the Generated Certificate and Key

The Secure LDAP service primarily uses TLS client certificates for authentication. After configuring an LDAP client, you will download a unique client certificate and key pair from the Google Admin console. This certificate must then be uploaded to your LDAP client to establish a secure connection.

Connect LDAP Clients to the Secure LDAP Service

Connecting your LDAP client involves configuring its settings to point to ldap.google.com and installing the downloaded client certificate. The specific steps vary significantly depending on the type of LDAP client you are using. It is crucial to consult your vendor's documentation in addition to the generic instructions provided.

General Configuration Instructions

For most LDAP clients, you will need the following 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 (e.g., dc=example,dc=com for example.com).
Username and Password (Access Credentials): Some clients require these in addition to the certificate. You can generate these in the Google Admin console. They do not confer access on their own but are needed by certain clients.
Client Certificate and Key Files: Use the files downloaded from the Google Admin console (ldap-client.crt and ldap-client.key are common filenames).

Specific Client Configurations

The guide provides detailed instructions for various clients, including but not limited to:

ADSI Edit (Windows): Involves installing client certificates and configuring connection settings with SSL encryption.
Apache Directory Studio: Requires using stunnel as a proxy due to lack of direct digital certificate support.
Atlassian Jira: Involves copying certificate/key, converting to Java keystore format, and configuring Jira's user directory settings. Requires "Read user information" and "Read group information" to be enabled in Admin console.
FreeRadius: Requires installing freeradius-ldap, copying certificate/key, enabling the LDAP module, and editing configuration files.
Ivanti / LanDesk: Requires updating XML configuration files with server, port, and TestDN values, and enabling explicit logon policy.
Ldp.exe (Windows): Requires converting certificate/key to PKCS12 format and importing into the Windows certificate store.
Netgate / pfSense: Refers to external documentation for detailed setup.
OpenLDAP / ldapsearch (Linux/macOS): Involves setting environment variables (LDAPTLS_CERT, LDAPTLS_KEY, LDAPTLS_IDENTITY for macOS) and running ldapsearch commands. For macOS, importing into Keychain Access and setting up Access Control is necessary.
OpenVPN (community version): Requires installing openvpn-auth-ldap, copying certificate/key, and configuring auth-ldap.conf and server.conf.
PaperCut MF and NG: Refers to external documentation for setup.
Splunk: Requires Splunk version 8.1.4 or later, copying certificate/key, consolidating into a .pem file, and configuring ldap.conf and the Splunk web UI.
SSSD (Red Hat Enterprise, CentOS, other Linux distributions): Requires installing sssd-ldap, copying certificate/key, creating sssd.conf, and setting permissions. Requires "Read user information" and "Read group information" to be enabled in Admin console.
macOS: Involves onboarding macOS as an LDAP client, importing the certificate into the system keychain, pointing the device to Google directory for authentication, and optionally creating mobile accounts for offline login.

Using stunnel as a proxy

For LDAP clients that do not inherently support authentication with TLS client certificates, stunnel can be used as a proxy. stunnel provides the client certificate to the Secure LDAP server, while your application connects to stunnel using plain LDAP without StartTLS/SSL/TLS. It is recommended to run stunnel on the same server as your application and listen locally to avoid exposing your LDAP directory.

Switch LDAP Clients to On

After connecting your LDAP client and verifying its configuration, the final step in the setup process is to switch the service status to "On" for the LDAP client in the Google Admin console.

Managing and Monitoring Secure LDAP

Secure LDAP Log Events

As an administrator, you can review and take action on Secure LDAP log events to monitor usage and security. These events are accessible through the Audit and investigation tool or, for supported editions, the Security investigation tool.

Admin Log Events

These logs provide information about administrative actions related to the Secure LDAP service.

LDAP Log Events

These logs detail the operations performed by LDAP clients connecting to the Secure LDAP service. Examples include Bind Failed, Search Successful, or Unbind.

Running a Search for Log Events

The ability to search depends on your Google Workspace edition, administrative privileges, and the data source.

Audit and investigation tool:
1. Sign in to the Google Admin console.
2. Navigate to Reporting > Audit and investigation > Secure LDAP log events.
3. Add filters based on attributes (e.g., Actor Email, Application ID, Event, IP address).
4. Click Search.
Security investigation tool: (Available in Frontline Standard and Plus, Enterprise Standard and Plus, Education Standard and Plus, Enterprise Essentials Plus, Cloud Identity Premium)
1. Sign in to the Google Admin console.
2. Go to Menu > Security > Security center > Investigation tool.
3. Select Secure LDAP log events as the data source.
4. Add conditions (attribute, operator, value) for your search.
5. Click Search.

Managing Log Event Data

You can manage the display and export of search results:

Manage search results column data: Customize which columns appear in the results table.
Export search result data: Export data to Google Sheets or a CSV file. Export limits are 100,000 rows for the Audit and investigation tool and 30 million rows for the Security investigation tool.

Creating Activity Rules and Alerts

You can set up alerts based on log event data using reporting rules or create activity rules in the security investigation tool to automate actions and alerts.

Troubleshooting Secure LDAP Service

If you encounter issues with the Secure LDAP service, several troubleshooting steps can help identify and resolve the problem.

Common Errors and Solutions

The Secure LDAP service returns specific error codes when issues occur during connection or subsequent LDAP queries. These errors are also visible in audit logs.

PROTOCOL_ERROR (2):
- Cause: Unsupported LDAP version (only LDAPv3 supported), unsupported action (only Abandon, Bind, Extended (for StartTLS), Search, Unbind are supported), or unsupported Oid for Extended request.
- Solution: Ensure your client uses LDAPv3 and supported actions.
AUTH_METHOD_NOT_SUPPORTED (7):
- Cause: Bind request specifies an unsupported authentication method (Google supports SIMPLE, SASL PLAIN, SASL EXTERNAL).
- Solution: Configure your client to use a supported authentication method.
ADMIN_LIMIT_EXCEEDED (11):
- Cause: Exceeding Secure LDAP service quotas for bind (4 QPS per customer) or search requests. Common with WiFi authentication using RADIUS.
- Solution: Reduce the frequency of bind or search operations. Optimize LDAP queries to use a more specific search base (e.g., ou=Groups,dc=example,dc=com instead of dc=example,dc=com if only groups are needed). Ensure Splunk version 8.1.4 or later is used to avoid excessive queries.
CONFIDENTIALITY_REQUIRED (13):
- Cause: SASL Bind request or Search request for non-server attributes issued over an unsecured connection.
- Solution: Ensure all sensitive LDAP communications are over a secure connection (TLS/SSL).
NO_SUCH_OBJECT (32):
- Cause: Searching for a non-existent object (user, group, OU) or a user ID not in the directory.
- Solution: Verify the existence and correct spelling of the object.
INVALID_DN_SYNTAX (34):
- Cause: Malformed Distinguished Name or non-String attribute value in DN.
- Solution: Correct the DN syntax and ensure attribute values are strings.
INAPPROPRIATE_AUTHENTICATION (48):
- Cause: Malformed, expired, or invalid client certificate in Bind request; or malformed/missing credentials in SASL PLAIN Bind request.
- Solution: Verify certificate validity, ensure it's correctly uploaded, and check access credentials.
INSUFFICIENT_ACCESS_RIGHTS (50):
- Cause: Secure LDAP service is "Off" for the client, customer or user is not licensed for Secure LDAP, disabled user, or user not in an enabled OU for authentication.
- Solution: Ensure the service is "On", licenses are assigned, and the user is in an allowed OU.
UNWILLING_TO_PERFORM (53):
- Cause: SIMPLE Bind request with no credentials (unauthenticated).
- Solution: Provide credentials for SIMPLE Bind.
OTHER (80):
- Cause: Unexpected result, likely a bug.
- Solution: Contact Google Workspace Support.
CANCELED (118):
- Cause: An Abandon request aborted an LDAP operation.

Secure LDAP Connectivity Testing

Before contacting Google Support, perform basic connectivity tests using simple tools.

Verify Connectivity and Run an LDAP Query:
- ldapsearch (Linux/macOS): Use this utility to make a basic LDAP query. A successful result indicates that the LDAP client, TLS session, and TCP connection are working. bash 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 with your .crt file, .key file, domain components (e.g., dc=example,dc=com), and a user's primary email.
  - Possible Error: SASL/EXTERNAL authentication started, ldap_sasl_interactive_bind_s: Unknown authentication method (-6) additional info: SASL(-4): no mechanism available. This often indicates the OpenLDAP client/library is compiled without SNI support. Check for OU=No SNI provided; please fix your client. in ldapsearch -d5 output.
  - Possible Error: ldapsearch returns success (status 0) but no users. This can happen if -x (use SASL authentication) is used with client certificates; remove -x.
- ADSI Edit (Windows): After installing client certificates, connect to ldap.google.com (Port 636, Use SSL-based Encryption checked) and specify your Base DN. Optionally, provide access credential username/password.
- ldp.exe (Windows): Convert your certificate and key to PKCS12 format, import into the Windows certificate store, then run ldp.exe and connect to ldap.google.com:636 with SSL checked. View the tree with your Base DN.
Basic Connectivity Testing (if LDAP query fails):
- OpenSSL client: Verify network layers and TLS negotiation. bash openssl s_client -connect ldap.google.com:636 Look for Verify return code: 0 (ok) at the end of the output. If Verify return code: 18 (self signed certificate) or depth=0 OU = "No SNI provided; please fix your client.", CN = invalid2.invalid appears, your TLS client might not support SNI.
- nc (netcat) or telnet (macOS): Verify TCP connectivity. bash nc -zv ldap.google.com 636 If you get "Connection refused", it might indicate a firewall issue. Use tcptraceroute ldap.google.com 636 to investigate.
- Verify directory objects (macOS): In Directory Utility, check the Directory Editor tab for the /LDAPv3/ldap.google.com node to see if users and groups from your Google domain are visible.

Frequently Asked Questions (FAQs)

What happens if I suspend the Cloud Identity or Google Workspace user account? Suspended accounts cannot sign in to any applications linked to Cloud Identity/Google Workspace, including LDAP applications. However, client services can still look up suspended accounts via an LDAP search.
What happens if I configure a third-party identity provider / SSO provider in Google Workspace or Cloud Identity? There is no impact on the Secure LDAP service. Third-party identity providers affect only HTTP-based transactions (e.g., SAML-based authentication). Users must use their Google username and password to authenticate with Secure LDAP connected applications.
Why do I need both a certificate and access credentials to authenticate LDAP clients? Only the certificate authenticates the LDAP client itself. Access credentials are only required if the client explicitly mandates a username and password. On their own, access credentials do not grant access to the LDAP server or user data but should be kept secret.
If my LDAP application does not support TLS certificates, is there any alternative? Yes, you can use stunnel as a proxy between your application and Secure LDAP. stunnel will handle the TLS certificate authentication with Google, while your application connects to stunnel without certificate support.
I generated access credentials in the past and now I don't remember the password. Can I generate another set? As an administrator, you can generate another set of access credentials. You can have a maximum of two active credentials simultaneously. If a credential is compromised or no longer in use, you can delete it.
If I suspect a security issue with an LDAP client, how can I immediately disable it? The most immediate way to disable an LDAP client is to delete all digital certificates associated with it. This takes effect faster than simply turning the service status to "Off" in the Admin console, which can take up to 24 hours.
My Linux computers on Google Compute Engine do not have external IP addresses. Can I still connect to the Secure LDAP service? Yes, if you are 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 (Private Google Access).