Skip to main content
RisingWave supports LDAP (Lightweight Directory Access Protocol) authentication, allowing you to authenticate users against an external LDAP directory server. This feature is compatible with PostgreSQL’s LDAP authentication mechanism and supports both simple bind and search+bind authentication modes. LDAP authentication is configured through RisingWave’s Host-Based Authentication (HBA) configuration file. When a user connects, RisingWave validates their credentials against the configured LDAP server before granting access.

​
Authentication modes

RisingWave supports two LDAP authentication modes:

​
Simple bind mode

In simple bind mode, RisingWave constructs the user’s Distinguished Name (DN) directly from the username using a prefix and suffix pattern, then attempts to bind to the LDAP server with this DN and the provided password. Use case: When your LDAP directory has a predictable DN structure (e.g., all users follow the pattern uid=username,ou=people,dc=example,dc=com).

​
Search + bind mode

In search + bind mode, RisingWave first performs an LDAP search to find the user’s DN, then attempts to bind using that DN and the provided password. This mode requires an initial bind (either anonymous or with dedicated credentials) to perform the search. Use case: When user DNs are not predictable or users are spread across multiple organizational units.

​
Configuration

LDAP authentication is configured in the RisingWave configuration file by adding HBA entries. Each entry specifies which users should authenticate via LDAP and the LDAP server details.

​
Configuration parameters

​
Common parameters

ParameterRequiredDescription
ldapserverYesLDAP server hostname or IP address
ldapportNoLDAP server port (Default: 389 for ldap, 636 for ldaps)
ldapschemeNoConnection scheme:ldaporldaps(Default: ldap)
ldaptlsNoEnable STARTTLS on ldap:// connections (Default: false)
ldapurlYesRFC 4516 LDAP URL (alternative to individual parameters)
Either ldapserver or ldapurl is required, but not both.

​
Simple bind mode parameters

ParameterRequiredDescription
ldapprefixNoString to prepend to the username
ldapsuffixNoString to append to the username

​
Search + bind mode parameters

ParameterRequiredDescription
ldapbasednYesBase DN for searching users
ldapsearchattributeNoAttribute to search for username (default: uid)
ldapsearchfilterNoCustom LDAP search filter with$usernameplaceholder
ldapbinddnNoDN to bind as for search operations
ldapbindpasswdNoPassword for bind DN
Simple bind parameters (ldapprefix/ldapsuffix) and search+bind-only parameters (ldapsearchfilter/ldapbinddn/ldapsearchattribute) cannot be mixed in the same configuration.

​
TLS/SSL configuration

RisingWave supports encrypted LDAP connections via:
  • LDAPS (LDAP over SSL): Use ldapscheme = "ldaps" or ldaps:// URL scheme
  • STARTTLS: Use ldaptls = "true" with ldap:// connections

​
TLS environment variables

TLS settings are configured via environment variables and must be set before starting RisingWave:
Environment variableDescription
LDAPTLS_CACERTPath to CA certificate file (required for self-signed certificates)
LDAPTLS_CERTPath to client certificate file (for mutual TLS)
LDAPTLS_KEYPath to client private key file (for mutual TLS)
LDAPTLS_REQCERTCertificate verification policy:never,allow,try, ordemand(default: demand)
Example
export LDAPTLS_CACERT="/path/to/ca.crt"
export LDAPTLS_REQCERT="demand"
If LDAPTLS_CACERT is not set, RisingWave uses the system’s native certificate store.

​
Examples

​
Simple bind with STARTTLS

[[frontend.hba_config.entries]]
connection_type = "Host"
databases = ["all"]
users = ["john", "jane", "alice"]
addresses = ["all"]
auth_method = "ldap"

[frontend.hba_config.entries.auth_options]
ldapserver = "ldap.example.com"
ldapscheme = "ldap"
ldapport = "389"
ldaptls = "true"
ldapprefix = "uid="
ldapsuffix = ",ou=people,dc=example,dc=com"
With this configuration:
  • User john authenticates as DN: uid=john,ou=people,dc=example,dc=com
  • Connection uses STARTTLS encryption
  • Requires LDAPTLS_CACERT environment variable if using self-signed certificates

​
Search + bind with LDAPS

[[frontend.hba_config.entries]]
connection_type = "Host"
databases = ["mydb"]
users = ["all"]
addresses = ["192.168.1.0/24"]
auth_method = "ldap"

[frontend.hba_config.entries.auth_options]
ldapserver = "ldap.example.com"
ldapscheme = "ldaps"
ldapport = "636"
ldapbasedn = "ou=people,dc=example,dc=com"
ldapsearchattribute = "uid"
ldapbinddn = "cn=admin,dc=example,dc=com"
ldapbindpasswd = "admin_password"
With this configuration:
  • RisingWave binds as admin to search for users
  • Searches for (uid=username) under ou=people,dc=example,dc=com
  • Uses LDAPS (port 636) for encrypted connection
  • Only accepts connections from the 192.168.1.0/24 subnet

​
Simple bind using LDAP URL format

[[frontend.hba_config.entries]]
connection_type = "Host"
databases = ["all"]
users = ["testuser1"]
addresses = ["all"]
auth_method = "ldap"

[frontend.hba_config.entries.auth_options]
ldapurl = "ldap://ldap.example.com:389/"
ldaptls = "true"
ldapprefix = "uid="
ldapsuffix = ",ou=people,dc=example,dc=com"

​
Search + bind using LDAP URL format

[[frontend.hba_config.entries]]
connection_type = "Host"
databases = ["all"]
users = ["testuser1"]
addresses = ["all"]
auth_method = "ldap"

[frontend.hba_config.entries.auth_options]
# Format: ldap[s]://host:port/basedn?attributes?scope?filter
ldapurl = "ldaps://ldap.example.com:636/ou=people,dc=example,dc=com?uid"
ldapbinddn = "cn=admin,dc=example,dc=com"
ldapbindpasswd = "admin_password"
The LDAP URL format follows RFC 4516:
  • Scheme: ldap:// or ldaps://
  • Base DN: Specified in the path component
  • Attributes: First attribute is used as search attribute
  • Filter: Optional custom filter (third query component)

​
Custom search filter

[[frontend.hba_config.entries]]
connection_type = "Host"
databases = ["all"]
users = ["all"]
addresses = ["all"]
auth_method = "ldap"

[frontend.hba_config.entries.auth_options]
ldapserver = "ldap.example.com"
ldapscheme = "ldap"
ldaptls = "true"
ldapbasedn = "dc=example,dc=com"
ldapsearchfilter = "(&(objectClass=person)([email protected]))"
ldapbinddn = "cn=admin,dc=example,dc=com"
ldapbindpasswd = "admin_password"
This configuration demonstrates advanced LDAP filtering:
  • Users authenticate using their username prefix (e.g., login as john for email [email protected])
  • The $username placeholder is replaced with the actual username (automatically escaped to prevent LDAP injection)
  • The filter combines two conditions with AND (&): matches person objects where mail attribute equals the constructed email
  • When user “john” logs in, the filter becomes: (&(objectClass=person)([email protected]))
Other filter examples:
  • Search by username OR email: (|(uid=$username)(mail=$username))
  • Restrict to specific group: (&(uid=$username)(memberOf=cn=db-users,ou=groups,dc=example,dc=com))
  • Search by common name: (cn=$username)

​
Connecting with LDAP credentials

After configuring LDAP authentication:
  1. Create the user in RisingWave: 
    CREATE USER john;
GRANT ALL PRIVILEGES ON SCHEMA public TO john;
  2. Users can connect using their LDAP credentials: 
    PGPASSWORD=ldap_password psql -h risingwave_host -U john -d mydb
  3. RisingWave validates credentials against LDAP server before granting access.
Users must exist in both the LDAP directory AND be created in RisingWave. The LDAP server only validates credentials, not user existence or permissions in RisingWave.

​
Security considerations

  1. Encryption: Always use TLS/SSL (LDAPS or STARTTLS) in production to protect credentials in transit.
  2. Certificate verification: Use LDAPTLS_REQCERT="demand" to enforce strict certificate validation.
  3. Bind credentials: Store bind DN passwords securely. Consider using read-only service accounts.
  4. Injection protection: RisingWave automatically escapes usernames to prevent LDAP injection attacks.
  5. Network security: Use HBA addresses field to restrict LDAP authentication to trusted networks.