Add LDAP Bind Authentication with username and password protection. The plugin
checks for valid credentials in the Proxy-Authorization
and Authorization
headers
(in that order).
The LDAP Authentication Advanced plugin provides features not available in the open-source LDAP Authentication plugin, such as 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 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.
Configuration Reference
This plugin is compatible with DB-less mode.
In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:
- Setting a target's health status in the load balancer
- Validating configurations against schemas
- Uploading the declarative configuration using the
/config
endpoint
Enable the plugin on a service
Enable the plugin on a route
Enable the plugin globally
A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter | Description |
---|---|
name
required Type: string |
The name of the plugin, in this case ldap-auth-advanced . |
service.id
Type: string |
The ID of the Service the plugin targets. |
route.id
Type: string |
The ID of the Route the plugin targets. |
enabled
required Type: boolean Default value: true |
Whether this plugin will be applied. |
config.ldap_host
required Type: string |
Host on which the LDAP server is running. |
config.ldap_port
required Type: number Default value: 389
|
TCP port where the LDAP server is listening. 389 is the default
port for non-SSL LDAP and AD. 636 is the port required for SSL LDAP and AD. If |
config.ldap_password
Type: string |
The password to the LDAP server. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format. If keyring database encryption is enabled, this value will be encrypted. |
config.start_tls
required Type: boolean Default value: false
|
Set it to |
config.ldaps
required Type: boolean Default value: false
|
Set it to |
config.base_dn
required Type: string |
Base DN as the starting point for the search; e.g., “dc=example,dc=com”. |
config.verify_ldap_host
required Type: boolean Default value: false
|
Set to |
config.attribute
required Type: string |
Attribute to be used to search the user; e.g., “cn”. |
config.cache_ttl
required Type: number Default value: 60
|
Cache expiry time in seconds. |
config.timeout
optional Type: number Default value: 10000
|
An optional timeout in milliseconds when waiting for connection with LDAP server. |
config.keepalive
optional Type: number Default value: 60000
|
An optional value in milliseconds that defines how long an idle connection to LDAP server will live before being closed. |
config.anonymous
optional Type: string |
An optional string (consumer UUID) value to use as an “anonymous” consumer if authentication fails. If empty (default), the
request will fail with an authentication failure Note: The value must refer to the Consumer |
config.header_type
optional Type: string Default value: ldap
|
An optional string to use as part of the Authorization header. By default, a valid Authorization header looks like this:
|
config.consumer_optional
optional Type: boolean Default value: false
|
Whether consumer mapping is optional. If To prevent access from LDAP users that are not associated with consumers, set |
config.consumer_by
optional Type: array of string elements Default value: [ "username", "custom_id" ]
|
Whether to authenticate consumers based on |
config.hide_credentials
required Type: boolean Default value: false
|
An optional boolean value telling the plugin to hide the credential to the upstream server. It will be removed by Kong before proxying the request. |
config.bind_dn
optional Type: string |
The DN to bind to. Used to perform LDAP search of user. This This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format. |
config.group_base_dn
Type: string Default value: matches conf.base_dn
|
Sets a distinguished name (DN) for the entry where LDAP searches for groups begin. This field is case-insensitive. |
config.group_name_attribute
Type: string Default value: matches conf.attribute
|
Sets the attribute holding the name of a group, typically
called |
config.group_member_attribute
Type: string Default value: memberOf
|
Sets the attribute holding the members of the LDAP group. This field is case-sensitive. |
config.log_search_results
optional Type: boolean Default value: false
|
Displays all the LDAP search results received from the LDAP server for debugging purposes. Not recommended to be enabled in a production environment. |
Usage
To authenticate a user, the client must set credentials in either the
Proxy-Authorization
or 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
config.cache_ttl
.
You can set the header type ldap
to any string (such as basic
) using
config.header_type
.
Upstream Headers
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-Credential-Username
, theusername
of the Credential (only if the consumer is not the ‘anonymous’ consumer)X-Anonymous-Consumer
, will be set totrue
when authentication failed, and the ‘anonymous’ consumer was set instead.X-Consumer-ID
, the ID of the ‘anonymous’ consumer on Kong (only if authentication failed and ‘anonymous’ was set)X-Consumer-Custom-ID
, thecustom_id
of the ‘anonymous’ consumer (only if authentication failed and ‘anonymous’ was set)X-Consumer-Username
, theusername
of the ‘anonymous’ consumer (only if authentication failed and ‘anonymous’ was set)
LDAP Search and config.bind_dn
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
search uses scope="sub"
, filter="<config.attribute>=<username>"
, and
base_dn=<config.base_dn>
. Here is an example of how it performs the search
using the ldapsearch
command line utility:
$ ldapsearch -x -h "<config.ldap_host>" -D "<config.bind_dn>" -b
"<config.attribute>=<username><config.base_dn>" -w "<config.ldap_password>"
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>' \
--user <LDAP_USERNAME>:<LDAP_PASSWORD>
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.
Notes
config.group_base_dn
and 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, x-authenticated-groups
,
to the request before proxying to the upstream. This is useful for Kong Manager role
mapping.
Changelog
Kong Gateway 2.8.x (plugin version 1.3.0)
- The
ldap_password
andbind_dn
configuration fields are now marked as referenceable, which means they can be securely stored as secrets in a vault. References must follow a specific format.
Kong Gateway 2.7.x (plugin version 1.2.0)
- Starting with Kong Gateway 2.7.0.0, if keyring encryption is enabled,
the
config.ldap_password
parameter value will be encrypted.