Valkey 通过官方的 valkey-ldap 模块支持 LDAP 认证,兼容 Valkey 7.2.x 及以上版本。要启用此功能,您必须在 Valkey 服务器上加载此模块。
该模块允许 Valkey 使用基于 LDAP 的外部系统(如 Active Directory)对用户进行认证。它将 Valkey 的认证与企业身份管理解决方案无缝集成,使组织能够利用其现有的认证基础设施。
此模块支持两种 LDAP 认证模式:bind
模式和 search+bind
模式。
当 Valkey AUTH
命令中提供的用户名与 LDAP 目录中用户条目的专有名称(DN)的子字符串匹配时,使用 bind
模式。search+bind
模式提供了更大的灵活性,允许用户名匹配 LDAP 用户条目的任何属性值,使其适用于更复杂的目录结构。
Bind 模式认证
在 bind
模式下,模块通过在用户名中添加可配置的前缀和后缀来构建专有名称(DN)。
通常,在 Active Directory 环境中,前缀设置为 CN=
或 DOMAIN\
,而在非 Active Directory 设置中,后缀定义了 DN 的其余部分。
以下是使用 bind
模式进行认证的示例。
考虑以下 LDAP 用户条目
dn: uid=ben,ou=engineering,dc=valkey,dc=io
objectclass: person
objectclass: inetOrgPerson
cn: Ben Alex
sn: Alex
uid: ben
在这种情况下,DN 是 uid=ben,ou=engineering,dc=valkey,dc=io
,用户名是 ben
。要使用 bind
模式,请将前缀设置为 uid=
,将后缀设置为 ,ou=engineering,dc=valkey,dc=io
。
您可以使用 ldap.bind_dn_prefix
和 ldap.bind_dn_suffix
选项配置这些值。
Search+Bind 认证
在 search+bind
模式下,模块首先使用具有在 LDAP 目录中执行搜索操作权限的帐户的用户名和密码绑定到 LDAP 目录。这些凭据存储在模块配置中,您需要在 ldap.search_bind_dn
中指定绑定 DN(专有名称),在 ldap.search_bind_passwd
中指定密码。
如果未配置搜索绑定帐户的用户名和密码,将尝试对目录进行匿名绑定。警告:如果未适当限制,匿名绑定可能会暴露敏感目录信息。请确保您的 LDAP 服务器配置为限制匿名用户的访问,以防止意外的数据泄露。
绑定阶段完成后,将对可配置的基准 DN 字符串下的子树执行搜索操作,该字符串在模块配置中的 ldap.search_base_dn
参数下设置。然后,模块将尝试将 AUTH
命令中指定的用户名与可配置条目属性的值进行匹配,该属性由配置中的 ldap.search_attribute
参数定义。
找到用户条目后,模块会从 ldap.search_dn_attribute
配置选项指定的属性中检索用户的 DN。然后,它使用提取的 DN 和 AUTH
命令中提供的密码,以该用户的身份重新绑定到 LDAP 目录,以验证登录凭据。
以下是使用 search+bind
模式进行认证的示例。
考虑以下 LDAP 用户条目
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
在此示例中,用户名 ben
存储在 uid
属性中,用户的 DN 存储在 entryDN
属性中。由于无法像 bind
模式那样通过使用前缀和后缀来构建 DN,因此您需要使用 search+bind
模式来定位用户条目并提取其 DN。
设置 ldap.search_attribute
为 uid
,ldap.search_dn_attribute
为 entryDN
以匹配用户名并检索 DN。
您还可以使用 ldap.search_filter
选项来限制搜索中包含哪些 LDAP 对象。默认情况下,ldap.search_filter
设置为 objectClass=*
,这会匹配所有对象。
在内部,模块执行一个 LDAP 搜索,其过滤器类似于 (&(objectClass=*)(uid=ben))
,它会匹配上面的条目。然后它从 entryDN
属性中提取 DN,并使用此 DN 和 AUTH
命令中提供的密码重新绑定以完成认证。
与 Bind 模式的比较
尽管 bind
模式更简单、更快,因为它直接从用户名构建 DN,但它最适合目录结构简单且用户名直接对应 DN 组件的环境。
另一方面,search+bind
模式提供了更大的灵活性,允许在用户名可能不直接映射到 DN 组件的复杂目录结构中进行认证。
然而,这种灵活性以额外的 LDAP 请求为代价,使其比 bind
模式稍慢。
设置 Valkey 用户
LDAP 服务器仅用于认证用户。每个用户的授权规则必须在 Valkey 中通过 ACL SETUSER
命令、valkey.conf
中的条目或使用 ACL 文件进行配置。这意味着用户帐户必须在 Valkey 中存在,LDAP 认证才能成功。
例如,要允许用户 bob
通过 LDAP 认证,Valkey ACL 数据库中必须存在一个名为 bob
的对应用户。
为确保 bob
无法使用基于密码的认证登录,您可以在创建 Valkey 用户时省略指定密码。
要创建不带密码的用户,只需在运行 ACL SETUSER
命令时省略密码并定义适当的 ACL 规则即可。例如:
ACL SETUSER bob on +@hash
在 Valkey 中创建用户 bob
后,认证将只能通过 LDAP 模块进行。
设置 LDAP 模块
所有模块配置选项都以 ldap.
为前缀,并可以使用 CONFIG SET
命令进行设置。要查看所有模块相关选项的当前值,请使用命令 CONFIG GET ldap.*
。
在 Valkey 中加载模块后,LDAP 认证要正常工作的第一件事是配置用于认证的 LDAP 服务器列表。
配置选项 ldap.servers
接受一个以空格分隔的 LDAP URL 列表,格式为 ldap[s]://<domain>:<port>
。
设置此选项后,模块将初始化到配置的 LDAP 服务器的连接池。
认证模式(bind
vs search+bind
)通过 ldap.auth_mode
选项配置。
TLS 配置
LDAP 协议支持两种安全客户端和服务器之间连接的方法:LDAPS 和 STARTTLS。
-
LDAPS (LDAP over SSL)
LDAPS 通过在建立 TCP 连接(通常在端口 636 上)后立即建立 SSL/TLS 会话来保护连接。客户端和服务器之间的所有通信从一开始就经过加密。要使用 LDAPS,请指定一个带有ldaps://
方案的 LDAP URL。 -
STARTTLS
STARTTLS 从标准的、未加密的 LDAP 连接开始(通常在端口 389 上)。客户端然后发出 STARTTLS 命令,将连接升级到 TLS 加密。要启用此方法,请将ldap.use_starttls
选项设置为yes
。
两种方法都为 LDAP 流量提供强大的加密。选择取决于您的环境和安全要求。请确保您的 LDAP 服务器配置了有效的 SSL/TLS 证书以支持安全连接。
要验证 LDAP 服务器证书,请使用 ldap.tls_ca_cert_path
选项指定受信任的 CA 证书文件的路径。如果未设置此选项,模块将使用系统的默认受信任 CA 证书。
如果您需要使用客户端证书进行认证,请使用客户端证书和私钥的路径配置 ldap.tls_cert_path
和 ldap.tls_key_path
选项。
监控
该模块通过添加一个名为 ldap_status
的新部分来扩展 INFO
命令的输出,该部分提供通过 ldap.servers
选项配置的每个 LDAP 服务器的状态信息。
ldap_status
部分包含每个服务器的字典条目,具有以下可能的字段:
host
:从ldap.servers
配置中指定的 URL 中提取的服务器主机名。status
:指示服务器的健康状况。可能的值为healthy
(服务器可达并响应 LDAP 操作)或unhealthy
(服务器无法处理 LDAP 操作)。ping_time_ms
:简单 LDAP 操作的往返时间(RTT),以毫秒为单位。此字段仅针对healthy
服务器显示。error
:导致服务器被标记为unhealthy
的错误的描述。此字段仅针对unhealthy
服务器显示。
INFO
命令的示例输出
# 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
高级配置
LDAP 模块提供了几个配置选项,以帮助根据您的网络环境和 LDAP 服务器负载调整认证行为。
LDAP 服务器连接管理
由于 LDAP 服务器通常由多个应用程序共享,因此限制每个应用程序打开的连接数以避免耗尽服务器资源非常重要。
ldap.connection_pool_size
选项指定模块将为每个配置的 LDAP 服务器打开的最大连接数。根据 Valkey 中预期的并发认证请求数量和您的 LDAP 服务器可以支持的最大连接数来设置此值。
如果并行认证请求的数量超过配置的连接池大小,认证延迟可能会增加,因为请求需要等待可用连接。
LDAP 服务器故障检测
该模块包含一个后台进程,定期检查每个配置的 LDAP 服务器的状态。
这些检查的频率由 ldap.failure_detector_interval
选项控制,该选项接受以秒为单位的值。
如果故障检测器确定 LDAP 服务器不可达或无法处理 LDAP 操作,它会将服务器标记为“不健康”,并自动将认证请求故障转移到另一个可用的 LDAP 服务器。
如果 Valkey 和 LDAP 服务器之间的网络延迟可变,或者 LDAP 服务器负载较重,您可以使用 ldap.timeout_connection
和 ldap.timeout_ldap_operation
选项调整连接和操作超时。
配置选项
通用选项
配置名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
ldap.auth_mode | 枚举(bind , search+bind ) | bind | 认证方法。 |
ldap.servers | 字符串 | "" | 以空格分隔的 LDAP URL 列表,格式为 ldap[s]://<domain>:<port> 。 |
TLS 选项
配置名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
ldap.use_starttls | 布尔值 | no | 是否使用 STARTTLS 操作(RFC 4513)升级到 TLS 加密连接。 |
ldap.tls_ca_cert_path | 字符串 | "" | CA 证书的文件系统路径,用于验证 LDAP 服务器证书。 |
ldap.tls_cert_path | 字符串 | "" | 客户端证书的文件系统路径,用于与 LDAP 服务器的 TLS 连接。 |
ldap.tls_key_path | 字符串 | "" | 客户端证书私钥的文件系统路径,用于与 LDAP 服务器的 TLS 连接。 |
Bind 模式选项
配置名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
ldap.bind_dn_prefix | 字符串 | "cn=" | 在为 LDAP 绑定形成 DN 时,添加到 AUTH 命令中用户名前的字符串。 |
ldap.bind_dn_suffix | 字符串 | "" | 在为 LDAP 绑定形成 DN 时,添加到 AUTH 命令中用户名后的字符串。 |
Search+Bind 模式选项
配置名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
ldap.search_bind_dn | 字符串 | "" | 用于执行 LDAP 搜索的用户帐户的 DN。 |
ldap.search_bind_passwd | 字符串 | "" | 搜索绑定用户的密码。 |
ldap.search_base | 字符串 | "" | 用户条目搜索开始的基准 DN。 |
ldap.search_filter | 字符串 | "objectClass=*" | 在搜索用户条目时应用的 LDAP 搜索过滤器。 |
ldap.search_attribute | 字符串 | "uid" | 用于与 AUTH 命令中提供的用户名匹配的 LDAP 属性。 |
ldap.search_scope | 枚举(base , one , sub ) | sub | LDAP 搜索范围。 |
ldap.search_dn_attribute | 字符串 | "entryDN" | 包含用户条目 DN 的属性。 |
高级选项
配置名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
ldap.connection_pool_size | 数字 | 2 | 每个 LDAP 服务器连接池中的连接数。 |
ldap.failure_detector_interval | 数字 | 1 | 每次故障检测器检查之间的间隔(秒)。 |
ldap.timeout_connection | 数字 | 10 | 连接到 LDAP 服务器时的等待秒数,超时后停止连接。 |
ldap.timeout_ldap_operation | 数字 | 10 | LDAP 操作的等待秒数,超时后停止操作。 |