Add LDAP Bind Authentication to a Route with username and password protection. The plugin
checks for valid credentials in the Proxy-Authorization
and Authorization
headers
(in that order).
Configuration Reference
This plugin is compatible with requests with the following protocols:
http
https
gprc
grpcs
This plugin is compatible with DB-less mode.
In DB-less mode, Kong Gateway does not have an Admin API. If using this mode, configure the plugin using declarative configuration.
Enabling the plugin on a Route
<route>
is the id
or name
of the Route that this plugin configuration
will target.
Enabling 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
Type: string |
The name of the plugin to use, in this case ldap-auth . |
route.id
Type: string |
The ID of the Route the plugin targets. |
enabled
Type: boolean Default value: true |
Whether this plugin will be applied. |
config.hide_credentials
optional 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.ldap_host
required |
Host on which the LDAP server is running. |
config.ldap_port
required 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.start_tls
required Default value: false |
Set it to |
config.ldaps
required Default value: false |
Set to |
config.base_dn
required |
Base DN as the starting point for the search; e.g., “dc=example,dc=com”. |
config.verify_ldap_host
required Default value: false |
Set to |
config.attribute
required |
Attribute to be used to search the user; e.g., “cn”. |
config.cache_ttl
required Default value: 60 |
Cache expiry time in seconds. |
config.timeout
optional Default value: 10000 |
An optional timeout in milliseconds when waiting for connection with LDAP server. |
config.keepalive
optional 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 |
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 |
config.header_type
optional Default value: ldap |
An optional string to use as part of the Authorization header. By default, a valid Authorization header looks like this: |
config.header_type
option was introduced in Kong 0.12.0. Previous versions of this plugin behave as if ldap
was set for this value. 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-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)X-Credential-Identifier
, the identifier of the Credential (only if the consumer is not the ‘anonymous’ consumer)
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.