Skip to content
|
search
Plugin Hub
header icon

LDAP Authentication Advanced

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

The following examples provide some typical configurations for enabling the ldap-auth-advanced plugin on a service.

Make the following request:

curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
    --data "name=ldap-auth-advanced"  \
    --data "config.ldap_host=ldap.example.com" \
    --data "config.ldap_port=389" \
    --data "config.start_tls=true" \
    --data "config.base_dn=dc=example,dc=com" \
    --data "config.verify_ldap_host=false" \
    --data "config.attribute=cn" \
    --data "config.cache_ttl=60" \
    --data "config.header_type=ldap"

Replace SERVICE_NAME|SERVICE_ID with the id or name of the service that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: ldap-auth-advanced-example
config: 
  ldap_host: ldap.example.com
  ldap_port: 389
  start_tls: true
  base_dn: dc=example,dc=com
  verify_ldap_host: false
  attribute: cn
  cache_ttl: 60
  header_type: ldap
plugin: ldap-auth-advanced

Next, apply the KongPlugin resource to a service by annotating the service as follows:

apiVersion: v1
kind: Service
metadata:
  name: SERVICE_NAME|SERVICE_ID
  labels:
    app: SERVICE_NAME|SERVICE_ID
  annotations:
    konghq.com/plugins: ldap-auth-advanced-example
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: SERVICE_NAME|SERVICE_ID
  selector:
    app: SERVICE_NAME|SERVICE_ID

Replace SERVICE_NAME|SERVICE_ID with the id or name of the service that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

Add this section to your declarative configuration file:

plugins:
- name: ldap-auth-advanced
  service: SERVICE_NAME|SERVICE_ID
  config: 
    ldap_host: ldap.example.com
    ldap_port: 389
    start_tls: true
    base_dn: dc=example,dc=com
    verify_ldap_host: false
    attribute: cn
    cache_ttl: 60
    header_type: ldap

Replace SERVICE_NAME|SERVICE_ID with the id or name of the service that this plugin configuration will target.

You can configure this plugin through the Konnect UI.

From the servicehub icon Service Hub, select a service version, then set up the plugin:

  1. In the Plugins section, click Add Plugin.
  2. Find and select the LDAP Authentication Advanced plugin.

  3. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Ldap Host: ldap.example.com
    • Config.Ldap Port: 389
    • Config.Start Tls: select checkbox
    • Config.Base Dn: dc=example,dc=com
    • Config.Verify Ldap Host: clear checkbox
    • Config.Attribute: cn
    • Config.Cache Ttl: 60
  4. Click Create.

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. From the Services section, click View for the service row.
  3. From the plugin section, click Add Plugin.
  4. Find and select the LDAP Authentication Advanced plugin.
    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, select Scoped.
  6. Add the service name and ID to the Service field if it is not already pre-filled.

  7. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Ldap Host: ldap.example.com
    • Config.Ldap Port: 389
    • Config.Start Tls: select checkbox
    • Config.Base Dn: dc=example,dc=com
    • Config.Verify Ldap Host: clear checkbox
    • Config.Attribute: cn
    • Config.Cache Ttl: 60
  8. Click Create.

The following examples provide some typical configurations for enabling the ldap-auth-advanced plugin on a route.

Make the following request:

curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
  --data "name=ldap-auth-advanced"  \
    --data "config.ldap_host=ldap.example.com" \
    --data "config.ldap_port=389" \
    --data "config.start_tls=true" \
    --data "config.base_dn=dc=example,dc=com" \
    --data "config.verify_ldap_host=false" \
    --data "config.attribute=cn" \
    --data "config.cache_ttl=60" \
    --data "config.header_type=ldap"

Replace ROUTE_NAME|ROUTE_ID with the id or name of the route that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: ldap-auth-advanced-example
config: 
  ldap_host: ldap.example.com
  ldap_port: 389
  start_tls: true
  base_dn: dc=example,dc=com
  verify_ldap_host: false
  attribute: cn
  cache_ttl: 60
  header_type: ldap
plugin: ldap-auth-advanced

Then, apply it to an ingress (route or routes) by annotating the ingress as follows:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ROUTE_NAME|ROUTE_ID
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: ldap-auth-advanced-example
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          service:
            name: echo
            port:
              number: 80

Replace ROUTE_NAME|ROUTE_ID with the id or name of the route that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

Add this section to your declarative configuration file:

plugins:
- name: ldap-auth-advanced
  route: ROUTE_NAME
  config: 
    ldap_host: ldap.example.com
    ldap_port: 389
    start_tls: true
    base_dn: dc=example,dc=com
    verify_ldap_host: false
    attribute: cn
    cache_ttl: 60
    header_type: ldap

Replace ROUTE_NAME|ROUTE_ID with the id or name of the route that this plugin configuration will target.

You can configure this plugin through the Konnect UI.

From the servicehub icon Service Hub, select a service version, then set up the plugin:

  1. Select a route.
  2. In the Plugins section, click Add Plugin.
  3. Find and select the LDAP Authentication Advanced plugin.

  4. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Ldap Host: ldap.example.com
    • Config.Ldap Port: 389
    • Config.Start Tls: select checkbox
    • Config.Base Dn: dc=example,dc=com
    • Config.Verify Ldap Host: clear checkbox
    • Config.Attribute: cn
    • Config.Cache Ttl: 60
  5. Click Create.

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. Open Routes from the menu, then click View for the route row.
  3. From the plugin section, click Add Plugin.
  4. Find and select the LDAP Authentication Advanced plugin.
    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, select Scoped.
  6. Add the route ID if it is not already prefilled.

  7. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Ldap Host: ldap.example.com
    • Config.Ldap Port: 389
    • Config.Start Tls: select checkbox
    • Config.Base Dn: dc=example,dc=com
    • Config.Verify Ldap Host: clear checkbox
    • Config.Attribute: cn
    • Config.Cache Ttl: 60
  8. Click Create.

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.

The following examples provide some typical configurations for enabling the ldap-auth-advanced plugin globally.

Make the following request:

curl -X POST http://localhost:8001/plugins/ \
  --data "name=ldap-auth-advanced"  \
    --data "config.ldap_host=ldap.example.com" \
    --data "config.ldap_port=389" \
    --data "config.start_tls=true" \
    --data "config.base_dn=dc=example,dc=com" \
    --data "config.verify_ldap_host=false" \
    --data "config.attribute=cn" \
    --data "config.cache_ttl=60" \
    --data "config.header_type=ldap"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-ldap-auth-advanced>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  ldap_host: ldap.example.com
  ldap_port: 389
  start_tls: true
  base_dn: dc=example,dc=com
  verify_ldap_host: false
  attribute: cn
  cache_ttl: 60
  header_type: ldap
plugin: ldap-auth-advanced

Add a plugins entry in the declarative configuration file:

plugins:
- name: ldap-auth-advanced
  config: 
    ldap_host: ldap.example.com
    ldap_port: 389
    start_tls: true
    base_dn: dc=example,dc=com
    verify_ldap_host: false
    attribute: cn
    cache_ttl: 60
    header_type: ldap

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. Open Plugins from the menu, then click New Plugin.
  3. Find and select the LDAP Authentication Advanced plugin.
    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  4. If the option is available, set the plugin scope to Global.

  5. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Ldap Host: ldap.example.com
    • Config.Ldap Port: 389
    • Config.Start Tls: select checkbox
    • Config.Base Dn: dc=example,dc=com
    • Config.Verify Ldap Host: clear checkbox
    • Config.Attribute: cn
    • Config.Cache Ttl: 60
  6. Click Create.

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 ldaps is configured, you must use port 636.
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 true to issue StartTLS (Transport Layer Security) extended operation over ldap connection. If the start_tls setting is enabled, ensure the ldaps setting is disabled.
config.ldaps
required

Type: boolean

Default value: false

Set it to true to use ldaps, a secure protocol (that can be configured to TLS) to connect to the LDAP server. When ldaps is configured, you must use port 636. If the ldap setting is enabled, ensure the start_tls setting is disabled.
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 true to authenticate LDAP server. The server certificate will be verified according to the CA certificates specified by the lua_ssl_trusted_certificate directive.
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 4xx. Note that this value must refer to the consumer id or username attribute, and not its custom_id.
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: Authorization: ldap base64(username:password). If header_type is set to “basic”, then the Authorization header would be Authorization: basic base64(username:password). Note that header_type can take any string, not just "ldap" and "basic".
config.consumer_optional
optional

Type: boolean

Default value: false

Whether consumer mapping is optional. If consumer_optional=true, the plugin will not attempt to associate a consumer with the LDAP authenticated user. If consumer_optional=false, LDAP authenticated users can still access upstream resources.

To prevent access from LDAP users that are not associated with consumers, set consumer_optional=false, set the anonymous field to an existing consumer_id, then use the Request Termination plugin to deny any requests from the anonymous consumer.
config.consumer_by
optional

Type: array of string elements

Default value: [ "username", "custom_id" ]

Whether to authenticate consumers based on username, custom_id, or both.
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 bind_dn should have permissions to search for the user being authenticated.

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 name (in Active Directory) or cn (in OpenLDAP). This field is case-insensitive.
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.

  • When ["group1 group2"] are in the same array indices, both group1 AND group2 need to be present in the LDAP search result.
  • When ["group1", "group2"] are in different array indices, either group1 OR group2 need to be present in the LDAP search result.

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: The custom_id of the consumer (if set).
  • X-Consumer-Username: The username of the consumer (if set).
  • X-Credential-Identifier: The identifier of the credential (only if the consumer is not the anonymous consumer).
  • 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 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 and bind_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.