LDAP Auth Advanced Configuration

Parameters

See plugin common configurations 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 and secrets.

Credentials

The following are plugin attributes available for configurations on credentials.

• user_dn — string · required

  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 or services.

• ldap_uri — string · required

  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

  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

  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

  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

  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

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

• use_starttls — boolean · optional · default: false

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

• ssl_verify — boolean · optional · default: true

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

• timeout — integer · optional · default: 10000

  Valid values: between 1 and 60000 inclusive

  Timeout in milliseconds for the connection to the directory.

• size_limit — integer · optional · default: 2

  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

  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

  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

  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

  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

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

• keepalive — boolean · optional · default: true

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

• keepalive_timeout — integer · optional · default: 60000

  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

  Valid values: greater than or equal to 1

  Maximum number of pooled connections to the directory per worker.

• keepalive_pool_name — string · optional

  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.