Skip to content
Kong Gateway 2.8 Increases Security and Simplifies API Management.  —Learn More →
|
search
Plugin Hub
header icon

LDAP Authentication

You are browsing documentation for an outdated plugin version. See the latest documentation here.

Add LDAP Bind Authentication to a Route (or the deprecated API entity) with username and password protection. The plugin will check for valid credentials in the Proxy-Authorization and Authorization header (in this order).

Note: The functionality of this plugin as bundled with versions of Kong Gateway (OSS) prior to 0.14.1 and Kong Gateway prior to 0.34 differs from what is documented herein. Refer to the CHANGELOG for details.

Configuration Reference

Enable the plugin on a route

For example, configure this plugin on a route with:

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=ldap-auth"  \
    --data "config.hide_credentials=true" \
    --data "config.ldap_host=ldap.example.com" \
    --data "config.ldap_port=389" \
    --data "config.start_tls=false" \
    --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"

ROUTE is 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-example>
config: 
  hide_credentials: true
  ldap_host: ldap.example.com
  ldap_port: 389
  start_tls: false
  base_dn: dc=example,dc=com
  verify_ldap_host: false
  attribute: cn
  cache_ttl: 60
  header_type: ldap
plugin: ldap-auth

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

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <ldap-auth-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

ROUTE is 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.

For example, configure this plugin on a route by adding this section to your declarative configuration file:

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

ROUTE is the id or name of the route that this plugin configuration will target.

Configure this plugin on a route:

  1. In Konnect Cloud, select the service from the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Select the route.
  4. Scroll down to Plugins and click Add Plugin.
  5. Find and select the LDAP Authentication plugin.

  6. Enter the following parameters, updating the default or sample values as needed:

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

Configure this plugin on a route:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Routes in the left navigation.
  3. Click View for the route row.
  4. Scroll down to plugins and click Add Plugin.

  5. Find and select the LDAP Authentication plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  6. If the option is available, select Scoped.
  7. Add the Route ID if it is not already prefilled.

  8. Enter the following parameters, updating the default or sample values as needed:

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

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.

For example, configure this plugin globally with:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=ldap-auth"  \
    --data "config.hide_credentials=true" \
    --data "config.ldap_host=ldap.example.com" \
    --data "config.ldap_port=389" \
    --data "config.start_tls=false" \
    --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>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  hide_credentials: true
  ldap_host: ldap.example.com
  ldap_port: 389
  start_tls: false
  base_dn: dc=example,dc=com
  verify_ldap_host: false
  attribute: cn
  cache_ttl: 60
  header_type: ldap
plugin: ldap-auth

For example, configure this plugin using the plugins: entry in the declarative configuration file:

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

Configure this plugin globally:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Plugins in the left navigation.
  3. Click New Plugin.

  4. Find and select the LDAP Authentication 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, set the plugin scope to Global.

  6. Enter the following parameters, updating the default/sample values as needed:

    • Config.Ldap Host: ldap.example.com
    • Config.Ldap Port: 389
    • Config.Start Tls: clear checkbox
    • Config.Base Dn: dc=example,dc=com
    • Config.Verify Ldap Host: clear checkbox
    • Config.Attribute: cn
    • Config.Cache Ttl: 60
  7. 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.
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.
api_id

Type: string		 The ID of the API the plugin targets.

Note: The API Entity is deprecated in favor of Services since CE 0.13.0 and EE 0.32.
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

TCP port where the LDAP server is listening.
config.start_tls
required

Default value: false

Set it to true to issue StartTLS (Transport Layer Security) extended operation over ldap connection.
config.base_dn
required

Base DN as the starting point for the search.
config.verify_ldap_host
required

Default value: false

Set it 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

Attribute to be used to search the user.
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 for 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 4xx. Please note that this value must refer to the Consumer id attribute which is internal to Kong, and not its custom_id.
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: 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".
Note: The 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

In order to authenticate the user, client must set credentials in Proxy-Authorization or Authorization header in following format

credentials := [ldap | LDAP] base64(username:password)

The plugin will validate the user against the LDAP server and cache the credential for future requests for the duration specified in config.cache_ttl.

Upstream Headers

When a client has been authenticated, the plugin will append 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, the username of the Credential (only if the consumer is not the ‘anonymous’ consumer)
  • X-Anonymous-Consumer, will be set to true 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, the custom_id of the ‘anonymous’ consumer (only if authentication failed and ‘anonymous’ was set)
  • X-Consumer-Username, the username of the ‘anonymous’ consumer (only if authentication failed and ‘anonymous’ was set)