LDAP Auth in Kong

LDAP Authentication lets Kong validate a username and password directly against a corporate directory. The backend does not receive those credentials and does not need to implement LDAP.

This article explains how the authentication header is built, how Kong locates the user in the directory, and how to protect /ldap-auth through Kong Ingress Controller.

1. What is LDAP Authentication?

LDAP, or Lightweight Directory Access Protocol, allows applications to query and authenticate identities stored in a directory service.

Each entry is identified by a Distinguished Name, or DN. In the lab directory, user riemann is located at:

uid=riemann,dc=example,dc=com

The plugin configuration tells Kong how to build that lookup:

• base_dn: dc=example,dc=com sets the starting point.
• attribute: uid identifies the username attribute.
• ldap_host and ldap_port identify the server.

The client combines the username and password:

riemann:password

It Base64-encodes the string and sends it with the configured scheme:

Authorization: ldap cmllbWFubjpwYXNzd29yZA==

LDAP Auth does not automatically use the Basic syntax generated by curl -u. Although the encoded content also has username:password form, this lab uses the ldap scheme, not Basic.

Base64 does not encrypt credentials. In a real environment, clients must reach Kong over HTTPS and Kong must connect to the directory through LDAPS or StartTLS.

2. How does LDAP Auth work in Kong Gateway?

Kong implements this mechanism through the official ldap-auth plugin. It supports traditional, hybrid, and DB-less topologies.

This lab applies it only to /ldap-auth.

When a request matches the Route, Kong:

1. Looks for credentials first in Proxy-Authorization and then in Authorization.
2. Checks that the header uses the scheme configured in header_type.
3. Decodes the username and password.
4. Builds the DN from attribute and base_dn.
5. Attempts to authenticate that user against LDAP.
6. Temporarily caches the result.
7. On success, removes the credential and forwards the request upstream.

The following diagram shows that the password is not checked against a local Kong credential. The plugin builds the DN and binds against the LDAP directory. Only a successful bind allows the request to continue.

The resulting behavior is:

• A missing header returns 401 Unauthorized.
• An unknown user or incorrect password returns 401 Unauthorized.
• An unreachable directory prevents authentication.
• Valid credentials allow the request to continue upstream.
• Rejected requests never reach echo.

The plugin’s default cache TTL is 60 seconds. This reduces directory load but can delay the effect of some credential changes for that period.

3. LDAP identity and Kong Consumers

In this lab, identity lives in LDAP. We do not create a password Secret or one KongConsumer per user.

The minimal relationship is:

Client
    |
    +-- username and password
            |
            v
          Kong
            |
            +-- LDAP bind
                    |
                    v
              LDAP directory

This differs from Basic Auth, Key Auth, or JWT, where lab credentials are declared as Kubernetes resources and attached to local Consumers.

For advanced identity features, group authorization, or custom mappings, consider LDAP Authentication Advanced or another identity integration.

4. Configuring LDAP Auth with KIC

We protect /ldap-auth on the echo Service. Only a KongPlugin and an HTTPRoute are required.

4.1. Relationship between Kubernetes and Kong resources

The LDAP directory remains outside Kubernetes and must be reachable from the Kong pods.

4.2. Create the ldap-auth plugin

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: ldap-auth
  namespace: javier
plugin: ldap-auth
config:
  ldap_host: ldap.forumsys.com
  ldap_port: 389
  start_tls: false
  ldaps: false
  base_dn: dc=example,dc=com
  attribute: uid
  header_type: ldap
  hide_credentials: true
  verify_ldap_host: false

This configuration reproduces the public example but is not secure for production:

• ldap_port: 389 uses the conventional LDAP port.
• start_tls: false and ldaps: false leave the connection unencrypted.
• verify_ldap_host: false does not verify the server identity.

Production must use one of:

• LDAPS with ldaps: true, port 636, and start_tls: false.
• StartTLS with start_tls: true, port 389, and ldaps: false.

Both require verify_ldap_host: true and the CA that signed the directory certificate to be configured in Kong.

4.3. Create the HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ldap-auth
  namespace: javier
  annotations:
    konghq.com/plugins: ldap-auth
spec:
  parentRefs:
    - name: kong
      namespace: kong
  hostnames:
    - echo.javiercd.es
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /ldap-auth
      backendRefs:
        - name: echo
          port: 80

4.4. Apply the manifests

sudo kubectl apply -f 18-ldap-plugin.yaml
sudo kubectl apply -f 18-ldap-httproute.yaml

Check their status:

sudo kubectl get kongplugin ldap-auth -n javier
sudo kubectl get httproute ldap-auth -n javier
sudo kubectl describe httproute ldap-auth -n javier

5. Testing LDAP Authentication

The following responses were captured directly against the public directory configured in the manifest.

5.1. Request without credentials

curl -i http://echo.javiercd.es/ldap-auth

Kong responds before contacting the upstream:

HTTP/1.1 401 Unauthorized
Date: Sun, 26 Jul 2026 09:02:10 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
WWW-Authenticate: LDAP
Content-Length: 81
X-Kong-Response-Latency: 0
Server: kong/3.10.0.16-enterprise-edition
X-Kong-Request-Id: 3769cd619434626c22b565380a256e2d

{
  "message":"Unauthorized",
  "request_id":"3769cd619434626c22b565380a256e2d"
}

5.2. Incorrect credentials

Encode an invalid password:

LDAP_AUTH="$(echo -n 'riemann:incorrecta' | base64 -w0)"

curl -i \
  -H "Authorization: ldap ${LDAP_AUTH}" \
  http://echo.javiercd.es/ldap-auth

The LDAP bind fails and Kong returns:

HTTP/1.1 401 Unauthorized
Date: Sun, 26 Jul 2026 09:02:10 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
WWW-Authenticate: LDAP
Content-Length: 81
X-Kong-Response-Latency: 237
Server: kong/3.10.0.16-enterprise-edition
X-Kong-Request-Id: f33c617286ceea737759642809623960

{
  "message":"Unauthorized",
  "request_id":"f33c617286ceea737759642809623960"
}

5.3. Correct credentials

Forum Systems’ public accounts use password password:

LDAP_AUTH="$(echo -n 'riemann:password' | base64 -w0)"

curl -i \
  -H "Authorization: ldap ${LDAP_AUTH}" \
  http://echo.javiercd.es/ldap-auth

If the public server is available, Kong validates the user and reaches the upstream:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 28
Connection: keep-alive
X-App-Name: http-echo
X-App-Version: 1.0.0
Date: Sun, 26 Jul 2026 09:02:10 GMT
Server: kong/3.10.0.16-enterprise-edition
X-Kong-Upstream-Latency: 1
X-Kong-Proxy-Latency: 119
Via: 1.1 kong/3.10.0.16-enterprise-edition
X-Kong-Request-Id: 18e15316718e36359b76c9698390f16f

Hola desde Kong Gateway KIC

5.4. Diagnose the LDAP connection

If valid credentials fail, inspect Kong’s logs:

sudo kubectl logs -n kong deployment/kong-gateway --tail=100

Common causes include:

• The LDAP host does not resolve from the pod.
• The port is blocked.
• base_dn or attribute does not match the directory.
• LDAPS and StartTLS were enabled at the same time.
• Kong cannot validate the certificate with its configured CAs.

These errors occur between Kong and LDAP and do not appear in echo.

Official sources

• LDAP Authentication plugin
• LDAP Authentication configuration reference
• LDAP Authentication changelog
• LDAP Authentication Advanced
• Forum Systems LDAP test server