LDAP Authentication Advanced

Add LDAP Bind Authentication to a Route using username and password credentials.
The plugin validates credentials by checking the Proxy-Authorization header first, followed by the Authorization header.

The LDAP Authentication Advanced plugin provides features not available in the LDAP Authentication plugin, including:

• LDAP searches for group and Consumer mapping
• Authentication of Consumers based on username or custom ID
• Binding to an enterprise LDAP directory with a password
• Authentication/authorization using a group base DN and specific group member or group name attributes
• Obtaining LDAP groups and setting them in a request header before proxying to the upstream. This is useful for Kong Manager role mapping.

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 like this:

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 Gateway.
• 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 Admin API and retrieve more information about the Consumer.

LDAP search and config.bind_dn

LDAP directory searching is performed during the request and plugin lifecycle to retrieve the fully qualified DN of the user. This allows the plugin to bind using the user’s LDAP username and password. The search uses:

• scope="sub"

• filter="<attribute>=<username>"

• base_dn=<base_dn> Here is an example of how it performs the search using the ldapsearch command line utility:

ldapsearch -x \
  -h "$LDAP_HOST" \
  -D "$BIND_DN" \
  -b "$ATTRIBUTE=$USERNAME,$BASE_DN" \
  -w "$LDAP_PASSWORD"

Using service directory mapping on the CLI

When using only RBAC Token authorization, service directory mapping to Kong Gateway roles doesn’t 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-USER:$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’s helpful to use cURL’s cookie engine or HTTPie sessions. If you don’t want to store the session, then the Set-Cookie header value can be copied directly from the /auth response and used with subsequent requests.

The plugin obtains LDAP groups and sets them in the x-authenticated-groups request header before proxying to the upstream. This is useful for Kong Manager role mapping.

The plugin doesn’t authenticate users based on group membership. If the user is not a member of an LDAP group, the request is still allowed.

• The config.group_base_dn and config.base_dn parameters have to fully match the exact DN of the group, a generic DN won’t work. For example, consider a case where there are nested organizational units. 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 aren’t 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.