<span class="nav-link-with-icon">LDAP <img src="https://doc.traefik.io/traefik-hub/img/ps-traefik-hub-logo-light.svg" class="menu-icon" alt="Traefik Hub API Gateway"></span>

Traefik Hub 功能

此中间件仅在 Traefik Hub 中提供。了解更多 Traefik Hub 高级功能。

LDAP 认证中间件将认证委托给外部 LDAP 服务器，从而保护应用。

LDAP 中间件会在每个请求的 Authorization 头中查找用户凭据。凭据必须按以下格式编码：base64(username:password)。

配置示例¶

基本用法

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ldap-auth
  namespace: apps
spec:
  plugin:
    ldap:
      url: ldap://ldap.example.org:636
      baseDN: dc=example,dc=org

需要绑定的基本用法

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ldap-auth
  namespace: apps
spec:
  plugin:
    ldap:
      url: ldap://ldap.example.org:636
      baseDN: dc=example,dc=org
      bindDN: cn=binding_user,dc=example,dc=org
      bindPassword: "urn:k8s:secret:my-secret:bindpassword"

启用搜索、绑定和 WWW-Authenticate 头

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ldap-auth
  namespace: apps
spec:
  plugin:
    ldap:
      url: ldap://ldap.example.org:636
      baseDN: dc=example,dc=org
      searchFilter: (&(objectClass=inetOrgPerson)(gidNumber=500)(uid=%s))
      forwardUsername: true
      forwardUsernameHeader: Custom-Username-Header-Name
      wwwAuthenticateHeader: true
      wwwAuthenticateHeaderRealm: traefikee

配置选项¶

字段	说明	默认值	必填
`url`	LDAP 服务器 URL。使用 `ldaps` 或 `ldap` 协议，并以端口结尾（例如：`ldaps://ldap.example.org:636`）。	""	是
`startTLS`	初始化到 LDAP 服务器的连接时，启用 `StartTLS` 请求。	false	否
`certificateAuthority`	如果连接使用 TLS，但证书由自定义证书颁发机构签署，则使用此 PEM 编码证书与 LDAP 服务器建立连接。	""	否
`insecureSkipVerify`	即使服务端 TLS 连接被认为不安全，也允许继续操作。	false	否
`bindDN`	搜索模式中，为了向 LDAP 服务器认证而绑定的域名。搜索模式中留空表示匿名绑定，而这通常并非预期行为。绑定模式中不使用此选项。	""	否
`bindPassword`	搜索模式中，`bindDN` 向 LDAP 服务器认证时使用的密码。更多信息见此处。	""	否
`connPool`	到 LDAP 服务器的连接池（用于尽量减少对性能的影响）。	None	否
`connPool.size`	可使用 `size` 属性自定义连接池管理的连接数。	10	否
`connPool.burst`	连接池已满时打开的临时连接。连接数一旦超过 `size` + `burst`，就返回 `Too Many Connections` 错误。	5	否
`connPool.ttl`	池中的连接仍应是短生命周期的，因此默认约一分钟后关闭。可使用 `ttl` 属性修改此行为。	60s	否
`baseDN`	绑定和搜索查询应使用的基础域名。	""	是
`attribute`	用于绑定用户的属性。绑定查询采用 `<attr>=<username>,<baseDN>` 模式，其中用户名从请求头提取。	cn	是
`forwardUsername`	通过指定请求头转发用户名，该头由 `forwardUsernameHeader` 选项定义。	""	否
`forwardUsernameHeader`	转发用户名时用于存放用户名的头名称。如果 `forwardUsername` 设为 `false`，则不使用此选项。	Username	是
`forwardAuthorization`	启用后，请求通过中间件批准后会转发其中的认证头。	false	是
`searchFilter`	非空时，中间件在搜索模式下运行，使用给定查询过滤搜索结果。过滤查询可以使用 `%s` 占位符，由请求 `Authorization` 头中提供的用户名替换（例如：`(&(objectClass=inetOrgPerson)(gidNumber=500)(uid=%s))`）。	""	否
`wwwAuthenticateHeader`	允许在 `401 Unauthorized` 响应中设置 `WWW-Authenticate` 头。更多信息参阅 WWW-Authenticate 头文档。可通过 `wwwAuthenticateHeaderRealm` 选项自定义 `WWW-Authenticate` 头的 `realm` 指令。	false	否
`wwwAuthenticateHeaderRealm`	在 `WWW-Authenticate` 头中设置的认证域名称。只有 `wwwAuthenticateHeader` 设为 `true` 时，此选项才生效。	""	否

bindPassword 绑定密码¶

设置 bindPassword 时，可以使用以下 URN 格式引用与 Middleware 位于同一命名空间中的 Kubernetes Secret：

urn:k8s:secret:[secretName]:[key]

绑定模式与搜索模式¶

如果配置中没有指定过滤器，中间件以默认的绑定模式运行，即使用请求头中提供的凭据，尝试向 LDAP 服务器发出绑定请求。绑定成功时，中间件转发请求；否则返回 401 Unauthorized 状态码。

如果中间件配置中指定了过滤查询，并且引用的认证源具有 bindDN 和 bindPassword，则中间件以搜索模式运行。此模式下，在尝试绑定之前，会先使用给定过滤器向 LDAP 服务器发出搜索查询。如果搜索结果仅返回 1 条记录，则尝试使用该记录发出绑定请求；否则终止并返回 401 Unauthorized 状态码。

在生产环境使用 Traefik OSS？

如果你在工作中使用 Traefik，可以考虑为 Traefik OSS 增加企业级 API 网关能力或商业支持。

为 Traefik OSS 增加 API 网关能力快捷且平滑，无需推倒重来，现有配置也会完整保留。请通过这个简短视频了解实际效果。