Traefik Hub LDAP 认证中间件使用外部 LDAP 服务器保护你的应用【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik导读本文讲解 Traefik Hub API Gateway 提供的 LDAP Authentication 中间件它将 HTTP 请求的用户认证委托给外部 LDAP 服务器从而为无自建认证体系的应用加上基于企业目录的访问控制。读完本文你将掌握该中间件的原理、完整配置示例、全部可配置项语义以及 bind 模式与 search 模式两种工作流的区别与选择依据并了解配置中如何安全引用 Kubernetes Secret 存放绑定密码。功能归属说明按官方文档声明本中间件仅在 Traefik HubAPI Gateway中可用属于基于 Traefik 插件体系配置中以spec.plugin.ldap声明的商用高级能力它不同于 Traefik 开源内置的 basicauth、forwardauth 等认证中间件。本文以仓库内 ldap.md 文档 为准进行展开并结合仓库内 Kubernetes CRD Provider 源码佐证其 Secret 引用机制。认证协议与工作原理LDAP Authentication 中间件的作用是把“验证请求方身份是否合法”这件事委托给一个外部 LDAP 服务器。它本身不保存任何用户凭据仅充当客户端身份与企业目录之间的桥梁。对每个进入中间件的请求其处理流程如下从请求头Authorization中取出用户凭据将凭据按base64(username:password)格式解码还原出用户名与密码使用解码后的凭据配合当前运行的认证模式详见下文“Bind Mode vs Search Mode”向 LDAP 服务器发起认证认证通过则放行请求并交给后续中间件/路由认证失败则直接向客户端返回401 Unauthorized。这意味着被保护的应用本身无需实现登录页与密码校验只需“相信”网关已完成的认证结果即可。一个最精简的、可运行的最小配置如下对应官方文档 Basic usage 示例apiVersion: traefik.io/v1alpha1 kind: Middleware metadata: name: test-ldap-auth namespace: apps spec: plugin: ldap: url: ldap://ldap.example.org:636 baseDN: dcexample,dcorgurl指向 LDAP 服务器baseDN是查询/绑定的基准 DN。上述配置运行在默认的bind 模式下直接用请求头中的用户名密码向服务器发起 bind。三种典型配置示例除最简配置外官方文档还给出了两种更具实战价值的形态。需要服务账号bind account才能查询的场景部分 LDAP 服务器不允许匿名搜索。此时需要为中间件配置一个“绑定账号”bindDN/bindPassword中间件先以该账号登录服务器再执行后续的搜索与绑定操作apiVersion: traefik.io/v1alpha1 kind: Middleware metadata: name: test-ldap-auth namespace: apps spec: plugin: ldap: url: ldap://ldap.example.org:636 baseDN: dcexample,dcorg bindDN: cnbinding_user,dcexample,dcorg bindPassword: urn:k8s:secret:my-secret:bindpassword注意bindPassword以urn:k8s:secret:...URN 形式引用了 Kubernetes Secret 中的某个键值而不是直接把明文密码写在配置里详见下文“bindPassword 与 Kubernetes Secret 引用”。开启搜索 用户信息转发 WWW-Authenticate当目录中的用户对象不足以直接用于 bind例如需要按组 ID 等额外条件过滤、需要把已认证用户名透传给上游应用、或希望浏览器弹出原生登录框时可以组合使用如下配置apiVersion: traefik.io/v1alpha1 kind: Middleware metadata: name: test-ldap-auth namespace: apps spec: plugin: ldap: url: ldap://ldap.example.org:636 baseDN: dcexample,dcorg searchFilter: ((objectClassinetOrgPerson)(gidNumber500)(uid%s)) forwardUsername: true forwardUsernameHeader: Custom-Username-Header-Name wwwAuthenticateHeader: true wwwAuthenticateHeaderRealm: traefikee该配置中searchFilter一旦非空中间件即切换到search 模式先用筛选条件定位用户条目再以该条目与请求密码完成绑定。%s占位符会在运行时被替换成请求中解码得到的用户名。配置选项全解析下表完整继承官方文档中的全部字段包含默认值与是否必填字段说明默认值必填urlLDAP 服务器地址。协议必须是ldaps://或ldap://且必须以端口结尾例如ldaps://ldap.example.org:636。是startTLS在与 LDAP 服务器建立连接时是否发起StartTLS请求RFC 4511 4.14 节定义的 TLS 扩展操作。false否certificateAuthority当连接使用 TLS、且服务器证书由自定义 CA 签发时用于建立 TLS 连接的 PEM 编码 CA 证书。否insecureSkipVerify是否允许在服务器 TLS 连接“否则会被判定为不安全”的情况下继续操作。仅建议在测试等受控环境开启生产环境应避免。false否bindDNsearch 模式下用于向 LDAP 服务器认证的绑定 DN。若 search 模式下留空则绑定是匿名的——这通常不是期望行为。bind 模式下不使用该字段。否bindPasswordsearch 模式下bindDN认证使用的密码。可通过 Kubernetes Secret URN 引用见下文。否connPool与 LDAP 服务器之间的连接池用于降低频繁建连对 LDAP 服务器性能的冲击。无否connPool.size连接池管理的常驻连接数。10否connPool.burst当连接池已满时额外打开的临时连接。当连接总数超过size burst时返回Too Many Connections错误。5否connPool.ttl池化连接仍是“短生命周期”设计默认约 1 分钟后被关闭可用该字段修改存活时长。60s否baseDNbind 与 search 查询使用的基准域名。是attribute用于绑定用户的属性名。bind 查询遵循attrusername,baseDN模式其中的用户名取自请求头解码结果。cn是forwardUsername是否把用户名放入指定请求头名称由forwardUsernameHeader定义转发给上游。否forwardUsernameHeader转发用户名时使用的请求头名称。forwardUsername关闭时该字段无效。Username是forwardAuthorization认证通过后是否把原始Authorization请求头一并转发给上游而不是由中间件剥离。false是searchFilter若非空中间件进入 search 模式按给定查询过滤搜索结果。过滤查询可用%s占位符运行时替换为请求Authorization头中的用户名例如((objectClassinetOrgPerson)(gidNumber500)(uid%s))。否wwwAuthenticateHeader是否在401 Unauthorized响应中写入WWW-Authenticate响应头HTTP 标准用于告知客户端应使用 Basic 认证并触发浏览器/客户端弹出凭据框。false否wwwAuthenticateHeaderRealm写入WWW-Authenticate头中的realm指令值。仅当wwwAuthenticateHeader为true时生效。否关于必填字段的补充说明表中个别字段如attribute、forwardUsernameHeader、forwardAuthorization在官方文档的“Required”列标记为“是”这是因为它们都有非空默认值分别是cn、Username、false在 YAML 中即便不书写也会以默认语义生效。真正在“不填会报错/无意义”层面必填的字段是url与baseDN。分组理解连接与传输安全url、startTLS、certificateAuthority、insecureSkipVerify控制与 LDAP 服务器建连的协议、端口和 TLS 校验策略。若目录服务器证书由企业私有 CA 签发必须通过certificateAuthority注入该 CA否则应保持insecureSkipVerify: false拒绝不安全连接。绑定账号与查询范围bindDN、bindPassword、baseDN、attribute共同决定“以谁的身份、在哪个子树、按什么属性”去定位/认证用户。连接池connPool.size/burst/ttl三个子项用于调节高并发下与 LDAP 服务器之间的连接复用缓解目录服务器的连接压力。请求头行为forwardUsername、forwardUsernameHeader、forwardAuthorization决定认证通过后向上游传递哪些身份信息。失败响应wwwAuthenticateHeader与wwwAuthenticateHeaderRealm用于优化 401 响应让标准 HTTP 客户端能够自动弹出认证提示。bindPassword 与 Kubernetes Secret 引用直接在中间件配置中写明文密码既不安全也不利于密钥轮换。因此该中间件与其他 Traefik Hub 认证中间件一致支持用 URN 引用与 Middleware同命名空间下的 Kubernetes Secreturn:k8s:secret:[secretName]:[key]其中[secretName]是 Secret 名称[key]是 Secret 内数据的键名。部署时只需保证该 Secret 存在且包含对应键即可apiVersion: v1 kind: Secret metadata: name: my-secret namespace: apps data: bindpassword: base64 编码后的 LDAP 绑定密码仓库源码中的解析实现该 URN 机制并非 LDAP 插件私有而是由 Traefik Kubernetes CRD Provider 统一实现的“插件配置密钥加载”能力。在 pkg/provider/kubernetes/crd/kubernetes.go 中createPluginMiddleware会把 CRD 中spec.plugin.*下的整棵配置树交给loadSecretKeysloadSecretKeys递归遍历字符串 / 数组 / 字典节点凡是命中urn:k8s:secret:前缀的字符串就调用getSecretValue解析getSecretValuekubernetes.go按:切分 URN期望恰好 5 段形如urn:k8s:secret:名称:键随后从 Middleware 所在命名空间读取 Secret 并返回对应键值若 URN 格式非法、Secret 不存在或键不存在都会返回明确错误。仓库中 with_plugin_read_secret.yml 这一 CRD Provider 测试夹具也印证了用法apiVersion: v1 kind: Secret metadata: name: name namespace: default data: key: dGhpc19pc190aGVfc2VjcmV0 # base64(this_is_the_secret) --- apiVersion: traefik.io/v1alpha1 kind: Middleware metadata: name: test-secret namespace: default spec: plugin: test-secret: user: admin secret: urn:k8s:secret:name:key同样的urn:k8s:secret:引用方式也出现在仓库文档目录下的 apikey.md、jwt.md、oidc.md 等 Hub 认证中间件文档中可以相互印证这一通用惯例。Bind Mode vs Search Mode中间件存在两种认证工作流由是否配置searchFilter决定Bind 模式默认当未配置任何过滤查询时中间件运行在默认的 bind 模式解码请求头中的base64(username:password)直接以该用户名按attribute与baseDN拼出绑定 DN和密码向 LDAP 服务器发起一次 bind 请求bind 成功 → 放行请求bind 失败 → 返回401 Unauthorized。bind 模式实现最简单、对 LDAP 服务器请求数最少适合用户名即目录条目、无需额外条件判断的场景。该模式不使用bindDN/bindPassword也无需searchFilter。Search 模式当配置了过滤查询且bindDN与bindPassword均已提供时中间件进入 search 模式先以bindDN/bindPassword向 LDAP 服务器认证必要时可结合startTLS、私有 CA 等安全配置以baseDN为基准、用searchFilter执行一次目录搜索其中%s会被替换为请求中解码出的用户名若搜索结果恰好只有 1 条记录则用该记录条目 DN 请求中的密码发起最终 bindbind 成功即放行若搜索结果不是恰好 1 条0 条或多条或最终 bind 失败则中止并返回401 Unauthorized。Search 模式的价值在于可以把“用户在目录中的可接受性”交由服务器端过滤表达式判断例如示例中的((objectClassinetOrgPerson)(gidNumber500)(uid%s))要求用户是 inetOrgPerson、gid 为 500而不是仅凭用户名密码成功绑定就放行。代价是多一次目录查询往返且必须妥善保管bindDN/bindPassword。两种模式的判定在官方文档中表述为过滤查询非空 认证源配置了bindDN/bindPassword→ search 模式否则为 bind 模式。文档同时提醒在 search 模式下若留空bindDN绑定时会退化为匿名绑定这通常不是期望行为生产环境务必显式配置绑定账号。落地建议与注意事项凭据传输url使用ldaps://LDAP over TLS或startTLS: true避免用户名密码以明文在网络上传输ldap://明文仅适合隔离测试网络。私有 CA企业内网目录服务器多用自签/内网 CA 证书记得通过certificateAuthority注入 CA而不是图省事开启insecureSkipVerify。密码保护bindPassword一律通过urn:k8s:secret:...引用同命名空间 Secret配合密钥轮换。上游信任链认证通过后若需把用户名带给上游应用使用forwardUsername: true 自定义forwardUsernameHeader默认头名为Username是否继续转发原始Authorization由forwardAuthorization控制默认不转发更安全。浏览器体验开启wwwAuthenticateHeader: true并设置realm可使标准 HTTP 客户端在收到401时弹出原生的用户名密码输入框。性能调优高并发场景下通过connPool复用连接注意size burst上限触发时中间件会返回Too Many Connections可按需调大size或放宽ttl。延伸阅读认证中间件纵览了解各类认证方式的定位差异同类 Hub 认证中间件JWT、OIDC、HMAC、OAuth2 Token Introspection用于比较“目录认证 vs 令牌认证”的选型若需了解中间件如何挂载到路由参考路由与中间件关联的 参考文档。注仓库内中间件文档统一位于 routing-configuration/http/middlewares 目录下LDAP 文档主体见 ldap.md。【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考