Mashape Kong Upgrade (9.x to 11.x)

LDAP Compatibility

Upgrading Kong

Kong is typically used as a gateway in an API management platform. Whilst it is possible to manage APIs completely inside Kong, we found it easier to manage our APIs externally, synchronising automatically with Kong once APIs were ready to be published. Unfortunately, as the traffic over our gateway increased, performance took a big hit. We identified an issue with Kong 9’s caching, and found that a fix had been implemented in the newer Kong 11 version.

Response Time Improvements

Testing showed up to approximate 5x improvement in our set-up, but the upgrade from 9 to 11 is not entirely straightforward as some important differences between the two are likely to have an impact. Of course, Mashape has documented many of the more important changes:

ACL Plugin

However, during testing we discovered some important changes that we couldn’t immediately find documentation for. This first manifested itself when we were testing the plugin combination ldap-auth + acl. A number of API owners had implemented this combination of plugins with the impression that:

  • the ldap-auth plugin would authenticate a user on the enterprise LDAP server
  • the acl plugin would check if the authenticated user was allowed to access their API

Unfortunately this impression was misguided for two reasons:

  • The acl plugin failed to activate properly in Kong 9 when used in combination with ldap-auth.
  • The ldap-auth plugin is not a typical authentication plugin, as it authenticates users which are never known in Kong. It is thus impossible for the acl plugin to check the user’s permissions.

In Kong 11 the first issue has been solved with improved checks on the authenticated user (pictured above). This meant that all requests with this combination of plugins were suddenly failing (due to the second issue still being present). As such, the combination LDAP (as the only authentication plugin) with ACL should never be used on either version of Kong.

Combined Authentication Plugins

Most authentication plugins in Kong make use of three custom HTTP headers in order to pass the authenticated user’s details to the backend service.

  • X-Consumer-Custom-ID
  • X-Consumer-ID
  • X-Consumer-Username

The exception is ldap-auth, because it has no knowledge of the LDAP users, and therefore can’t determine these 3 values. Instead it uses a completely separate header (X-Credential-Username) to store the values. In previous versions, this meant it was possible to combine ldap-auth with other authentication plugins. For example, the key-auth plugin would populate the X-Consumer-* headers, then the ldap-auth plugin would additionally fill in the X-Credential-* header. In newer implementations the LDAP plugin removes any previously applied X-Consumer-* headers. As a result, any authentication plugins that run before ldap-auth have their information removed.

LDAP Authentication Plugin Clears Headers

In Kong 11 this affects key-auth, oauth2 and jwt. Since we often use LDAP in combination with API keys, this presented a real problem for us. In the end we opted to customise the ldap-auth plugin to never remove headers (removing the responsible code above), which matches closer to previous implementations of the plugin. Of course this introduces a risk that other scenarios stop functioning as expected (presumably when anonymous users are utilised), but for our particular use case no issues were found.