# LDAP Auth Advanced Configuration

The `ldap-auth-advanced` plugin authenticates clients against LDAP, optionally maps directory users to consumers, and supports LDAP, Basic, StartTLS, and LDAPS.<!-- --> <!-- -->Configuration covers credential fields and route and service fields.

## Parameters[​](#parameters "Direct link to Parameters")

See plugin [common configurations](https://docs.api7.ai/apisix/reference/plugin-common-configurations.md) for configuration options available to all plugins.

This plugin supports gateway references in string-valued configuration fields. Use the `$env://` prefix for environment variables or the `$secret://` prefix for values from a secret manager, such as HashiCorp Vault’s [KV secrets engine](https://developer.hashicorp.com/vault/docs/secrets/kv). The gateway resolves these references at runtime. ADC `${NAME}` interpolation is different because ADC resolves it while loading the configuration file, before synchronization. For more information, see [environment variables in plugin](https://docs.api7.ai/apisix/reference/environment-variables.md#plugins) and [secrets](https://docs.api7.ai/apisix/key-concepts/secrets.md).

### Credentials[​](#credentials "Direct link to Credentials")

The following are plugin attributes available for configurations on [credentials](https://docs.api7.ai/apisix/key-concepts/credentials.md).

* user\_dn

  string

  required

  valid value:

  between 1 and 4096 characters

  ***

  Distinguished name of the directory entry this consumer represents, such as `uid=johndoe,ou=users,dc=example,dc=org`. It has to match the DN the plugin resolves through its directory search.

### Routes or Services[​](#routes-or-services "Direct link to Routes or Services")

The following are plugin attributes available for configurations on [routes](https://docs.api7.ai/apisix/key-concepts/routes.md) or [services](https://docs.api7.ai/apisix/key-concepts/services.md).

* ldap\_uri

  string

  required

  valid value:

  between 1 and 256 characters

  ***

  Address of the LDAP directory, as `host` or `host:port`. When the port is omitted, `636` is used if `use_ldaps` is enabled and `389` otherwise.

* base\_dn

  string

  required

  valid value:

  between 1 and 4096 characters

  ***

  Distinguished name of the subtree the plugin searches to resolve the user, such as `ou=users,dc=example,dc=org`.

* attribute

  string

  default: `cn`

  valid value:

  an RFC 4512 attribute description, at most 256 characters

  ***

  Attribute matched against the user name supplied by the client. The search filter is `(attribute=username)`, so `uid` suits most OpenLDAP directories and `sAMAccountName` suits Active Directory.

* bind\_dn

  string

  valid value:

  between 1 and 4096 characters

  ***

  Distinguished name the plugin binds as to perform the search. When unset, the search is performed anonymously. Setting it requires `ldap_password`.

* ldap\_password

  string

  valid value:

  between 1 and 4096 characters

  ***

  Password for `bind_dn`. Required when `bind_dn` is set. When Data Plane data encryption is enabled, this field is encrypted at rest.

* use\_ldaps

  boolean

  default: `false`

  ***

  If true, connect to the directory over LDAPS. Mutually exclusive with `use_starttls`.

* use\_starttls

  boolean

  default: `false`

  ***

  If true, upgrade a plaintext connection to TLS with StartTLS. Mutually exclusive with `use_ldaps`.

* ssl\_verify

  boolean

  default: `true`

  ***

  If true, verify the directory's TLS certificate when connecting over LDAPS or StartTLS.

* timeout

  integer

  default: `10000`

  valid value:

  between 1 and 60000 inclusive

  ***

  Timeout in milliseconds for the connection to the directory.

* size\_limit

  integer

  default: `2`

  valid value:

  greater than or equal to 2

  ***

  Maximum number of entries the directory returns for the search. The default of `2` is enough to detect an ambiguous user name, which the plugin rejects rather than binding as an arbitrary match.

* time\_limit

  integer

  default: `5`

  valid value:

  greater than or equal to 0

  ***

  Time limit in seconds the directory applies to the search. Set to `0` to use the directory's own default.

* consumer\_required

  boolean

  default: `true`

  ***

  If true, the authenticated user has to map onto a consumer whose credential records their distinguished name, and a user without such a credential is rejected. Set to `false` to authenticate against the directory without involving consumers.

* header\_type

  string

  default: `ldap`

  valid value:

  `ldap` or `basic`

  ***

  Authentication scheme the plugin accepts in the `Authorization` or `Proxy-Authorization` header, and the scheme it names in the `WWW-Authenticate` challenge. In both cases the credential itself is `base64(username:password)`, so `basic` produces an ordinary HTTP Basic exchange.

* hide\_credentials

  boolean

  default: `false`

  ***

  If true, remove the header carrying the directory credentials after authentication so the username and password are not forwarded upstream. Available in API7 Enterprise from version 3.10.6.

* realm

  string

  default: `ldap`

  ***

  Realm reported in the `WWW-Authenticate` header of the challenge returned to unauthenticated clients.

* keepalive

  boolean

  default: `true`

  ***

  If true, keep connections to the directory alive so that they are reused across requests.

* keepalive\_timeout

  integer

  default: `60000`

  valid value:

  greater than or equal to 1000

  ***

  Idle time in milliseconds after which a pooled connection to the directory is closed.

* keepalive\_pool\_size

  integer

  default: `5`

  valid value:

  greater than or equal to 1

  ***

  Maximum number of pooled connections to the directory per worker.

* keepalive\_pool\_name

  string

  valid value:

  between 1 and 256 characters

  ***

  Name of the connection pool. Set it to keep the connections of different plugin configurations in separate pools.
