LDAP Authentication

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

Configuration Reference

You can configure this plugin using the Kong Admin API or through declarative configuration, which involves directly editing the Kong configuration file.

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 does not have an Admin API. If using this mode, configure the plugin using declarative configuration.

Enabling the plugin on a Route

$ curl -X POST http://<admin-hostname>: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.ldaps=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"

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

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: <route>
  annotations:
    plugins.konghq.com: <ldap-auth-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

plugins:
- name: ldap-auth
  route: <route>
  config: 
    hide_credentials: true
    ldap_host: ldap.example.com
    ldap_port: 389
    start_tls: false
    ldaps: 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.

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.

$ curl -X POST http://<admin-hostname>: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.ldaps=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"

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

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

Parameters

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

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