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

Enable the plugin on a service

curl -X POST http://{HOST}:8001/services/{SERVICE}/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.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" \
    --data "config.hide_credentials=false"

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

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <ldap-auth-advanced-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    app: {SERVICE}

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

Enable the plugin on a route

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/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.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" \
    --data "config.hide_credentials=false"

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

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

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

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.

$ curl -X POST http://{HOST}: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.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" \
    --data "config.hide_credentials=false"

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

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

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

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

config.group_base_dn and config.base_dn do not accept an array and it has to fully match the full DN the group is in - it won’t work if it is specified a more generic DN, therefore it needs to be specific. For example, considering a case where there are nested "OU's". If a top-level DN such as "ou=dev,o=company" is specified instead of "ou=role,ou=groups,ou=dev,o=company", the authentication will fail.

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 doesn’t authenticate users (allow/deny requests) based on group membership. For example:

• If the user is a member of an LDAP group, the request is allowed.
• if the user is not a member of an LDAP group, the request is still allowed.

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 2.8.x (plugin version 1.3.0)

• 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 (plugin version 1.2.0)

• Starting with Kong Gateway 2.7.0.0, if keyring encryption is enabled, the config.ldap_password parameter value will be encrypted.