LDAP Auth Advanced Configuration
Configuration reference for the LDAP Auth Advanced plugin (`ldap-auth-advanced`): the parameters on credentials and routes or services, each attribute with its type, whether it is required, its default and its accepted values.
Parameters
See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.
This plugin supports referencing sensitive parameter values from environment variables using the env:// prefix, or from a secret manager, such as HashiCorp Vault’s KV secrets engine, using the secret:// prefix. For more information, see environment variables in plugin (opens in Apache APISIX docs) and secrets (opens in Apache APISIX docs).
Credentials
The following are plugin attributes available for configurations on credentials (opens in Apache APISIX docs).
user_dn — string · required · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: 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
The following are plugin attributes available for configurations on routes (opens in Apache APISIX docs) or services (opens in Apache APISIX docs).
ldap_uri — string · required · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: 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 · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: 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 · optional · default: cn · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: 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 · optional · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: 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 · optional · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: 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 · optional · default: false · since APISIX 3.18.0 · API7 Gateway 3.10.5
If true, connect to the directory over LDAPS. Mutually exclusive with use_starttls.
use_starttls — boolean · optional · default: false · since APISIX 3.18.0 · API7 Gateway 3.10.5
If true, upgrade a plaintext connection to TLS with StartTLS. Mutually exclusive with use_ldaps.
ssl_verify — boolean · optional · default: true · since APISIX 3.18.0 · API7 Gateway 3.10.5
If true, verify the directory's TLS certificate when connecting over LDAPS or StartTLS.
timeout — integer · optional · default: 10000 · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: between 1 and 60000 inclusive
Timeout in milliseconds for the connection to the directory.
size_limit — integer · optional · default: 2 · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: 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 · optional · default: 5 · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: 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 · optional · default: true · since APISIX 3.18.0 · API7 Gateway 3.10.5
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 · optional · default: ldap · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: 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 · optional · default: false · since API7 Gateway 3.10.6
If true, remove the header carrying the directory credentials once the client has been authenticated, so the username and password are not forwarded to the upstream. Available in API7 Enterprise from version 3.10.6.
realm — string · optional · default: ldap · since APISIX 3.18.0 · API7 Gateway 3.10.5
Realm reported in the WWW-Authenticate header of the challenge returned to unauthenticated clients.
keepalive — boolean · optional · default: true · since APISIX 3.18.0 · API7 Gateway 3.10.5
If true, keep connections to the directory alive so that they are reused across requests.
keepalive_timeout — integer · optional · default: 60000 · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: greater than or equal to 1000
Idle time in milliseconds after which a pooled connection to the directory is closed.
keepalive_pool_size — integer · optional · default: 5 · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: greater than or equal to 1
Maximum number of pooled connections to the directory per worker.
keepalive_pool_name — string · optional · since APISIX 3.18.0 · API7 Gateway 3.10.5
Valid values: between 1 and 256 characters
Name of the connection pool. Set it to keep the connections of different plugin configurations in separate pools.