LDAP Authentication

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).

This plugin is the open-source version of the LDAP Authentication Advanced plugin, which provides additional features 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 authenticate/authorize using a group base DN and specific group member or group name attributes.

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

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

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

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

plugins:
- name: ldap-auth
  route: ROUTE_NAME
  config: 
    hide_credentials: true
    ldap_host: ldap.example.com
    ldap_port: 389
    base_dn: dc=example,dc=com
    attribute: cn
    header_type: ldap

curl -X POST http://localhost: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.base_dn=dc=example,dc=com" \
    --data "config.attribute=cn" \
    --data "config.header_type=ldap"

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
  base_dn: dc=example,dc=com
  attribute: cn
  header_type: ldap
plugin: ldap-auth

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

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

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.

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.

Changelog

Kong Gateway 3.0.x

• The deprecated X-Credential-Username header has been removed.

Kong Gateway 2.5.x

• Added support for setting the ldap_port. Previously, this parameter was documented but did not exist in the plugin.