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
Example plugin configuration
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.name or service.id
Type: string |
The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
Type: string |
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
enabled
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. If keyring database encryption is enabled, this value will be encrypted. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format. |
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 or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request will fail with an authentication failure |
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. |
config.groups_required
optional Type: array of string elements |
The groups required to be present in the LDAP search result for successful authorization. This config parameter works in both AND / OR cases.
|
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-Consumer-ID
: The ID of the consumer in Kong.X-Consumer-Custom-ID
: Thecustom_id
of the consumer (if set).X-Consumer-Username
: Theusername
of the consumer (if set).X-Credential-Identifier
: The identifier of the credential (only if the consumer is not theanonymous
consumer).X-Anonymous-Consumer
: Is set totrue
if authentication fails, and theanonymous
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 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
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 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 3.0.x
- Added the
groups_required
parameter. - The deprecated
X-Credential-Username
header has been removed. - The character
.
is now allowed in group attributes. - The character
:
is now allowed in the password field.
Kong Gateway 2.8.x
- 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
- Starting with Kong Gateway 2.7.0.0, if keyring encryption is enabled,
the
config.ldap_password
parameter value will be encrypted.
Kong Gateway 2.3.x
- Added the parameter
log_search_results
, which lets the plugin display all the LDAP search results received from the LDAP server. - Added new debug log statements for authenticated groups.