Did you know that you can try this plugin without talking to anyone with a free
trial of Kong Konnect? Get started in under 5 minutes.
Looking for the plugin's configuration parameters? You can find them in the LDAP Authentication Advanced configuration reference doc.
Add LDAP Bind Authentication with username and password protection. The plugin
checks for valid credentials in the
in that order.
The LDAP Authentication Advanced plugin
provides features not available in the open-source LDAP Authentication plugin,
- LDAP searches for group and consumer mapping
- Ability to authenticate based on username or custom ID
- The ability to bind to an enterprise LDAP directory with a password
- The ability to authenticate/authorize using a group base DN and specific group member or group name attributes
- The ability to obtain LDAP groups and set them in a header to the request before proxying to the upstream.
This is useful for Kong Manager role mapping.
To authenticate a user, the client must set credentials in either the
Authorization header in the following format:
credentials := [ldap | LDAP] base64(username:password)
The Authorization header would look something like:
Authorization: ldap dGxibGVzc2luZzpLMG5nU3RyMG5n
The plugin validates the user against the LDAP server and caches the
credentials for future requests for the duration specified in
You can set the header type
ldap to any string (such as
When a client has been authenticated, the plugin appends some headers to
the request before proxying it to the upstream service, so that you
can identify the consumer in your code:
X-Consumer-ID: The ID of the consumer in Kong.
custom_id of the consumer (if set).
username of the consumer (if set).
X-Credential-Identifier: The identifier of the credential (only if the consumer is not the
X-Anonymous-Consumer: Is set to
true if authentication fails, and the
anonymous consumer is set instead.
You can use this information on your side to implement additional logic.
You can use the
X-Consumer-ID value to query the Kong Admin API and retrieve
more information about the consumer.
LDAP Search and
LDAP directory searching is performed during the request/plugin lifecycle. It is
used to retrieve the fully qualified DN of the user so a bind
request can be performed with a user’s given LDAP username and password. The
search for the user being authenticated uses the
config.bind_dn property. The
base_dn=<config.base_dn>. Here is an example of how it performs the search
ldapsearch command line utility:
ldapsearch -x \
-h "<config.ldap_host>" \
-D "<config.bind_dn>" \
-b "<config.attribute>=<username><config.base_dn>" \
Using Service Directory Mapping on the CLI
When using only RBAC Token authorization, Service Directory Mapping to Kong Roles does not take effect. If you need to use CLI access with your Service Directory mapping, you can use the same authentication mechanism that Kong Manager uses to secure browser sessions.
Authenticate User Session
Retrieve a secure cookie session with the authorized LDAP user credentials:
$ curl -c /tmp/cookie http://localhost:8001/auth \
-H 'Kong-Admin-User: <LDAP_USERNAME>' \
Now the cookie is stored at
/tmp/cookie and can be read for future requests:
$ curl -c /tmp/cookie -b /tmp/cookie http://localhost:8001/consumers \
-H 'Kong-Admin-User: <LDAP_USERNAME>'
Because Kong Manager is a browser application, if any HTTP responses see the
Set-Cookie header, then it will automatically attach it to future requests. This is why it is helpful to utilize cURL’s cookie engine or HTTPie sessions. If storing the session is not desired, then the
Set-Cookie header value can be copied directly from the
/auth response and used with subsequent requests.
config.base_dn do not accept an array and
it has to fully match the full DN the group is in - it won’t work if it
is specified a more generic DN, therefore it needs to be specific. For
example, considering a case where there are nested
"OU's". If a
top-level DN such as
"ou=dev,o=company" is specified instead of
"ou=role,ou=groups,ou=dev,o=company", the authentication will fail.
Referrals are not supported in the plugin. A workaround is
to hit the LDAP Global Catalog instead, which is usually listening on a
different port than the default
389. That way, referrals don’t get sent
back to the plugin.
The plugin doesn’t authenticate users (allow/deny requests) based on group
membership. For example:
- If the user is a member of an LDAP group, the request is allowed.
- if the user is not a member of an LDAP group, the request is still allowed.
The plugin obtains LDAP groups and sets them in a header,
to the request before proxying to the upstream. This is useful for Kong Manager role