Skip to main content
API7.ai Logo

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

    vaild vaule:

    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

    vaild vaule:

    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

    vaild vaule:

    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

    vaild vaule:

    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

    vaild vaule:

    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

    vaild vaule:

    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

    vaild vaule:

    between 1 and 60000 inclusive

    Timeout in milliseconds for the connection to the directory.

  • size_limit

    integer

    default: 2

    vaild vaule:

    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

    vaild vaule:

    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

    vaild vaule:

    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 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

    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

    vaild vaule:

    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

    vaild vaule:

    greater than or equal to 1

    Maximum number of pooled connections to the directory per worker.

  • keepalive_pool_name

    string

    vaild vaule:

    between 1 and 256 characters

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