VALKEY-LDAP(7)

📦 version 9.0.6, in fedora 44

💖 VALKEY-LDAP(7) 💖

okay bestie, pull up a chair, we're doing LDAP today. this is the manual page for valkey-ldap, the Valkey Manual page number 7, and it's all about LDAP Authentication. it's a long one so buckle up 🎀

✨ NAME ✨

valkey-ldap — LDAP Authentication. that's it, that's the name, no notes 💅

🌸 DESCRIPTION 🌸

so here's the tea: Valkey does LDAP auth through the official valkey-ldap module, and it plays nice with Valkey versions 7.2.x and above. to turn this whole thing on, you gotta load the module on your Valkey server. no module, no LDAP, periodt.

what this module does is let Valkey authenticate users against external LDAP-based systems — think Active Directory, the whole corporate vibe. it seamlessly integrates Valkey's authentication with enterprise identity management solutions, so organizations can leverage their existing authentication infrastructure instead of building a whole new thing. iconic behavior honestly 👑

there are two LDAP authentication modes:

  • the bind mode
  • the search+bind mode

Bind mode is the one you use when the username you pass in the Valkey auth(3valkey) command matches a substring of the distinguished name (DN) of user entries in the LDAP directory.

Search+bind mode is the flexible one — it lets the username match any attribute value of an LDAP user entry, which makes it suitable for more complex directory structures. she's adaptable 💁♀️

🦋 Bind Mode Authentication

in bind mode, the module builds the distinguished name (DN) by gluing a configurable prefix and a suffix onto the username. that's literally the whole trick.

typically, the prefix is set to CN= or DOMAIN\ for Active Directory environments, while the suffix defines the rest of the DN in non-Active Directory setups.

here's an example of how to use bind mode for authentication, bestie. consider this LDAP user entry:

dn: uid=ben,ou=engineering,dc=valkey,dc=io
objectclass: person
objectclass: inetOrgPerson
cn: Ben Alex
sn: Alex
uid: ben

in this case the DN is uid=ben,ou=engineering,dc=valkey,dc=io, and the username is ben. so to use bind mode, you set the prefix to uid= and the suffix to ,ou=engineering,dc=valkey,dc=io.

you configure those values with the ldap.bind_dn_prefix and ldap.bind_dn_suffix options. cute, right?

🧚 Search+Bind Authentication

now for the main character mode. in search+bind mode, the module first binds to the LDAP directory using a username and password of an account that has permissions to perform search operations in the LDAP directory. those credentials live in the module configuration — you put the bind DN (Distinguished Name) in ldap.search_bind_dn and the password in ldap.search_bind_passwd.

if no username and password is configured for the search bind account, an anonymous bind will be attempted to the directory.

⚠️ Warning: Anonymous binds can expose sensitive directory information if not properly restricted. Ensure that your LDAP server is configured to limit access for anonymous users to prevent unintended data exposure. like, fr fr, lock that down 🔒

after the binding phase, a search operation runs over the subtree at a configurable base DN string, which is set in the module configuration under the ldap.search_base_dn parameter. the module will then attempt to match the username specified in the AUTH command against the value of a configurable entry attribute — that's the ldap.search_attribute parameter in the configuration.

once the user entry is found, the module retrieves the user's DN from the attribute specified by the ldap.search_dn_attribute configuration option. then it re-binds to the LDAP directory as this user, using the extracted DN and the password provided in the AUTH command, to verify the login credentials. slay 🔥

here's an example of search+bind mode in action. consider this LDAP user entry:

dn: cn=Ben Alex,ou=engineering,dc=valkey,dc=io
objectClass: person
objectClass: inetOrgPerson
entryDN: cn=Ben Alex,ou=engineering,dc=valkey,dc=io
cn: Ben Alex
sn: Alex
uid: ben

in this example, the username ben is stored in the uid attribute, and the user's DN is stored in the entryDN attribute. since it's not possible to construct the DN using the username with a prefix and suffix like in bind mode, you need search+bind mode to locate the user entry and extract its DN. no shortcuts here.

set ldap.search_attribute to uid and ldap.search_dn_attribute to entryDN to match the username and retrieve the DN.

you can also use the ldap.search_filter option to restrict which LDAP objects are included in the search. by default, ldap.search_filter is set to objectClass=*, which matches all objects. (yes, everything. she's not picky by default.)

internally, the module performs an LDAP search with a filter like (&(objectClass=*)(uid=ben)), which matches the entry above. it then extracts the DN from the entryDN attribute and re-binds using this DN and the password provided in the AUTH command to complete authentication. and that's the whole pipeline bestie 🌈

⭐ Comparison with Bind Mode

let's do a vibe check on both, shall we?

bind mode is simpler and faster, because it directly constructs the DN from the username. it's best suited for environments where the directory structure is straightforward and usernames directly correspond to DN components.

search+bind mode, on the other hand, provides greater flexibility — it allows authentication in complex directory structures where usernames may not directly map to DN components.

but (and this is the tradeoff, no cap) that flexibility comes at the cost of additional LDAP requests, making it slightly slower than bind mode. you win some, you wait a few milliseconds some 💅

🎀 Setting Up Valkey Users

important thing: the LDAP server is used solely for authenticating users. authorization rules for each user must be configured in Valkey using either:

which means user accounts must exist in Valkey in order for LDAP authentication to succeed. LDAP handles the who-are-you, Valkey handles the what-can-you-do. got it?

for example, to allow the user bob to authenticate via LDAP, a corresponding user named bob must be present in the Valkey ACL database.

to make sure bob cannot log in using password-based authentication, you can create the Valkey user without specifying a password.

to create a user without a password, simply omit the password when running the ACL SETUSER command and define the appropriate ACL rules. for example:

ACL SETUSER bob on +@hash

after creating the user bob in Valkey, authentication will only be possible through the LDAP module. locked in 🔐

🌈 Setting Up LDAP module

all module configuration options are prefixed with ldap. and can be set using the CONFIG SET command. to view the current values of all module-related options, use:

CONFIG GET ldap.*

after the module is loaded in Valkey, the first thing that is required for LDAP authentication to work is configuring the list of LDAP servers that should be used for the authentication.

the configuration option ldap.servers accepts a space separated list of LDAP URLs of the form ldap[s]://<domain>:<port>.

after setting this option, the module will initialize the connection pools to the configured LDAP servers.

and the authentication mode — bind vs search+bind — is configured using the ldap.auth_mode option. that's your big switch ✨

🫶 TLS Configuration

the LDAP protocol supports two methods for securing connections between the client and the server: LDAPS and STARTTLS. pick your fighter 💖

  • LDAPS (LDAP over SSL): LDAPS secures the connection by establishing an SSL/TLS session as soon as the TCP connection is made, typically on port 636. all communication between the client and server is encrypted from the start. to use LDAPS, specify an LDAP URL with the ldaps:// scheme.
  • STARTTLS: STARTTLS starts with a standard, unencrypted LDAP connection (usually on port 389). the client then issues a STARTTLS command to upgrade the connection to TLS encryption. to enable this method, set the ldap.use_starttls option to yes.

both methods provide strong encryption for LDAP traffic. the choice depends on your environment and security requirements. make sure your LDAP server is configured with valid SSL/TLS certificates to support secure connections. 🔐✨

to verify LDAP server certificates, use the ldap.tls_ca_cert_path option to specify the path to a trusted CA certificate file. if this option is not set, the module will use the system's default trusted CA certificates.

if you need to use client certificates for authentication, configure the ldap.tls_cert_path and ldap.tls_key_path options with the paths to your client certificate and private key.

👑 Monitoring

the module extends the output of the INFO command by adding a new section called ldap_status, which provides status information for each LDAP server configured via the ldap.servers option.

the ldap_status section includes a dictionary entry for each server, with these possible fields:

  • host: the server hostname extracted from the URL specified in the ldap.servers configuration.
  • status: indicates the server's health. possible values are healthy (the server is reachable and responds to LDAP operations) or unhealthy (the server cannot process LDAP operations).
  • ping_time_ms: the round-trip time (RTT) for a simple LDAP operation, in milliseconds. this field is shown only for healthy servers.
  • error: a description of the error that caused the server to be marked as unhealthy. this field is shown only for unhealthy servers.

example output from the INFO command:

# LDAP_STATUS

ldap_server_0:host=<hostname>,status=unhealthy,error=<some error message>
ldap_server_1:host=<hostname>,status=healthy,ping_time_ms=1.645

look at that ping time. 1.645 ms. we love a responsive server 🥰

💜 Advanced Configuration

the LDAP module provides several configuration options to help adapt authentication behavior to your network environment and LDAP server load. aka: the tuning era 🎛️

🍓 LDAP Server Connection Management

because LDAP servers are often shared by multiple applications, it's important to limit the number of connections each application opens to avoid exhausting the server's resources. don't be the app that eats the whole server, bestie, that's not the vibe 🙈

the ldap.connection_pool_size option specifies the maximum number of connections the module will open to each configured LDAP server. set this value based on the expected number of concurrent authentication requests in Valkey and the maximum number of connections your LDAP server can support.

if the number of parallel authentication requests exceeds the configured pool size, authentication latency may increase as requests wait for available connections. so like, plan accordingly 💅

🌸 LDAP Server Failure Detection

the module includes a background process that periodically checks the status of each configured LDAP server. she's keeping an eye on things 👀

the frequency of these checks is controlled by the ldap.failure_detector_interval option, which accepts a value in seconds.

if the failure detector determines that an LDAP server is unreachable or unable to process LDAP operations, it marks the server as "unhealthy" and automatically fails over authentication requests to another available LDAP server. automatic failover? main character energy fr fr 🔥

Okay bestie, one last lil thing before we get to the config menu 🫶 — if the network latency between Valkey and the LDAP server is out here being all over the place 😭, or if the LDAP server is lowkey struggling under heavy load, you can totally adjust the connection and operation timeouts with the ldap.timeout_connection and ldap.timeout_ldap_operation options. Tune away, no cap. 💅

🎀 Configuration Options 🎀

This is the whole config wardrobe, fr fr. Pick your fits. 👑

✨ General Options ✨

  • ldap.auth_mode — type Enum(bind, search+bind), default bind. The authentication method. It's giving "how do we even do auth around here" energy. 🌸
  • ldap.servers — type string, default "". Space-separated list of LDAP URLs in the form ldap[s]://<domain>:<port>. Yes bestie, spaces between them, that's the whole vibe. ✨

🔒 TLS Options 🔒

  • ldap.use_starttls — type boolean, default no. Whether to upgrade to a TLS-encrypted connection using the STARTTLS operation (RFC 4513). Secure the bag. 🔐
  • ldap.tls_ca_cert_path — type string, default "". Filesystem path to the CA certificate for validating the LDAP server certificate. Gotta check that ID before you let it in. 👀
  • ldap.tls_cert_path — type string, default "". Filesystem path to the client certificate for TLS connections to the LDAP server. Your little badge of honor. 🎀
  • ldap.tls_key_path — type string, default "". Filesystem path to the client certificate key for TLS connections to the LDAP server. The key that goes with the badge, keep it secret, keep it safe. 🤫

🪢 Bind Mode Options 🪢

  • ldap.bind_dn_prefix — type string, default "cn=". String to prepend to the username from the AUTH command when forming the DN for LDAP bind. Gluing the front on. 🩹
  • ldap.bind_dn_suffix — type string, default "". String to append to the username from the AUTH command when forming the DN for LDAP bind. Gluing the back on. The username sandwich, if you will. 🥪

🔍 Search+Bind Mode Options 🔍

  • ldap.search_bind_dn — type string, default "". DN of the user account used to perform LDAP searches. The lil scout account. 🧚
  • ldap.search_bind_passwd — type string, default "". Password for the search bind user. The scout's lil password. 🤐
  • ldap.search_base — type string, default "". Base DN where the search for the user entry begins. Where the treasure hunt starts, iykyk. 🗺️
  • ldap.search_filter — type string, default "objectClass=*". LDAP search filter to apply when searching for user entries. Filtering the feed, essentially. ✨
  • ldap.search_attribute — type string, default "uid". LDAP attribute to match against the username provided in the AUTH command. This is the thing we're comparing bestie's username to. 🪪
  • ldap.search_scope — type Enum(base, one, sub), default sub. Scope of the LDAP search. How deep we digging, fr. ⛏️
  • ldap.search_dn_attribute — type string, default "entryDN". Attribute containing the DN of the user entry. The DN lives here, iconic. 👑

🧠 Advanced Options 🧠

  • ldap.connection_pool_size — type number, default 2. Number of connections in each LDAP server’s connection pool. A whole lil squad per server. 💅
  • ldap.failure_detector_interval — type number, default 1. Interval (in seconds) between each failure detector check. It checks in on the vibes every second. 🕵️
  • ldap.timeout_connection — type number, default 10. Number of seconds to wait when connecting to an LDAP server before timing out. Ten seconds of patience, then we move on. ⏳
  • ldap.timeout_ldap_operation — type number, default 10. Number of seconds to wait for an LDAP operation before timing out. Same energy, but for the operation itself. 😤

And that's the whole page, bestie!! 🎉💖✨ This absolute banger of a manpage is from version 9.0.0, dated 2025-10-21, and it goes by VALKEY-LDAP(7) 🦋 — go forth and configure responsibly, mwah 💅🫶

📦 where this page comes from