# LDAP Auth Advanced 配置选项

ldap-auth-advanced 插件通过 LDAP 对客户端进行身份认证，可选择将目录用户映射为消费者，并支持 LDAP、Basic、StartTLS 和 LDAPS。<!-- --> <!-- -->配置涵盖凭据字段和路由和服务字段。

## 参数[​](#参数 "参数的直接链接")

请参阅 [插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md) 了解所有插件可用的配置选项。

该插件支持在字符串类型的配置字段中使用网关引用。使用 `$env://` 前缀引用环境变量中的值，或使用 `$secret://` 前缀引用密钥管理器中的值，例如 HashiCorp Vault 的 [KV 密钥引擎](https://developer.hashicorp.com/vault/docs/secrets/kv)。网关在运行时解析这些引用。ADC 的 `${NAME}` 插值有所不同：ADC 在同步前加载配置文件时解析插值。有关更多信息，请参阅[插件中的环境变量](https://docs.apiseven.com/apisix/reference/environment-variables.md#plugins)和[密钥](https://docs.apiseven.com/apisix/key-concepts/secrets.md)。

### 凭据[​](#凭据 "凭据的直接链接")

以下是可在[凭据](https://docs.apiseven.com/apisix/key-concepts/credentials.md)上配置的插件属性。

* user\_dn

  string

  必填

  有效值：

  1 到 4096 个字符

  ***

  该消费者所代表的目录条目的可分辨名称（DN），例如 `uid=johndoe,ou=users,dc=example,dc=org`。它必须与插件通过目录检索解析出来的 DN 一致。

### 路由或服务[​](#路由或服务 "路由或服务的直接链接")

以下是可用于 [路由 (Routes)](https://docs.apiseven.com/apisix/key-concepts/routes.md) 或 [服务 (Services)](https://docs.apiseven.com/apisix/key-concepts/services.md) 配置的插件属性。

* ldap\_uri

  string

  必填

  有效值：

  1 到 256 个字符

  ***

  LDAP 目录的地址，格式为 `host` 或 `host:port`。省略端口时，启用 `use_ldaps` 使用 `636`，否则使用 `389`。

* base\_dn

  string

  必填

  有效值：

  1 到 4096 个字符

  ***

  插件检索用户时所在子树的可分辨名称，例如 `ou=users,dc=example,dc=org`。

* attribute

  string

  默认值：`cn`

  有效值：

  符合 `RFC 4512` 的属性描述，最多 256 个字符

  ***

  用于与客户端提供的用户名匹配的属性。检索过滤器为 `(attribute=username)`，因此大多数 OpenLDAP 目录适合使用 `uid`，Active Directory 适合使用 `sAMAccountName`。

* bind\_dn

  string

  有效值：

  1 到 4096 个字符

  ***

  插件执行检索时所绑定的可分辨名称。未设置时以匿名方式检索。设置该字段时必须同时设置 `ldap_password`。

* ldap\_password

  string

  有效值：

  1 到 4096 个字符

  ***

  `bind_dn` 对应的密码。设置 `bind_dn` 时必填。启用数据面数据加密时，该字段会落盘加密。

* use\_ldaps

  boolean

  默认值：`false`

  ***

  如果为 true，则通过 LDAPS 连接目录。与 `use_starttls` 互斥。

* use\_starttls

  boolean

  默认值：`false`

  ***

  如果为 true，则通过 StartTLS 把明文连接升级为 TLS。与 `use_ldaps` 互斥。

* ssl\_verify

  boolean

  默认值：`true`

  ***

  如果为 true，则在通过 LDAPS 或 StartTLS 连接时校验目录的 TLS 证书。

* timeout

  integer

  默认值：`10000`

  有效值：

  1 到 60000 之间（含）

  ***

  与目录建立连接的超时时间，单位为毫秒。

* size\_limit

  integer

  默认值：`2`

  有效值：

  大于或等于 2

  ***

  目录为本次检索返回的最大条目数。默认值 `2` 足以发现用户名存在歧义的情况；此时插件会拒绝请求，而不是绑定到其中任意一条匹配。

* time\_limit

  integer

  默认值：`5`

  有效值：

  大于或等于 0

  ***

  目录对本次检索施加的时间上限，单位为秒。设为 `0` 表示使用目录自身的默认值。

* consumer\_required

  boolean

  默认值：`true`

  ***

  如果为 true，则认证成功的用户还必须能映射到某个凭据中记录了其可分辨名称的消费者，否则请求被拒绝。设为 `false` 表示只对接目录完成认证，不涉及消费者。

* header\_type

  string

  默认值：`ldap`

  有效值：

  `ldap` 或 `basic`

  ***

  插件在 `Authorization` 或 `Proxy-Authorization` 请求头中接受的认证方案，同时也是 `WWW-Authenticate` 挑战头中声明的方案。两种取值下凭据本身都是 `base64(username:password)`，因此 `basic` 对应标准的 HTTP Basic 交互。

* hide\_credentials

  boolean

  默认值：`false`

  ***

  如果为 true，则在认证后移除携带目录凭据的请求头，使用户名和密码不会被转发到上游。在 API7 企业版中自 3.10.6 起可用。

* realm

  string

  默认值：`ldap`

  ***

  返回给未认证客户端的 `WWW-Authenticate` 响应头中声明的 realm。

* keepalive

  boolean

  默认值：`true`

  ***

  如果为 true，则保持与目录的连接存活，使其在请求之间复用。

* keepalive\_timeout

  integer

  默认值：`60000`

  有效值：

  大于或等于 1000

  ***

  连接池中与目录的连接在空闲多久后被关闭，单位为毫秒。

* keepalive\_pool\_size

  integer

  默认值：`5`

  有效值：

  大于或等于 1

  ***

  每个 worker 与目录之间连接池的最大连接数。

* keepalive\_pool\_name

  string

  有效值：

  1 到 256 个字符

  ***

  连接池的名称。设置该字段可以把不同插件配置的连接隔离到各自的连接池中。
