Kong Manager with LDAP

Kong Gateway provides the ability to bind authentication for Kong Manager admins to an organization’s service directory.

LDAP authentication for Kong Manager is enabled and configured entirely through kong.conf, and uses the LDAP Authentication Advanced and Session plugins in the background. You do not need to manually enable either plugin.

Kong Gateway uses the config parameter admin_gui_auth_conf to configure the LDAP plugin, and admin_gui_session_conf to configure Sessions.

To customize examples in this guide, refer to:

• LDAP Authentication Advanced plugin parameter reference
• Session plugin parameter reference

The following examples show you how to enable LDAP auth for Kong Manager.

export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'

curl -Ls get.konghq.com/quickstart | bash -s -- \
  -e "KONG_LICENSE_DATA" \
  -e "KONG_ENFORCE_RBAC=on" \
  -e "KONG_PASSWORD=kong" \
  -e "KONG_ADMIN_GUI_AUTH=ldap-auth-advanced" \
  -e "KONG_ADMIN_GUI_SESSION_CONF={ "secret":"YOUR-SECRET" } \
  -e 'KONG_ADMIN_GUI_AUTH_CONF={ "anonymous":"", "attribute":"YOUR-ATTRIBUTE", "bind_dn":"YOUR-BIND-DN", "base_dn":"YOUR-BASE-DN", "cache_ttl": 2, "consumer_by":["username", "custom_id"], "header_type":"Basic", "keepalive":60000, "ldap_host":"YOUR-LDAP-HOST", "ldap_password":"YOUR-LDAP-PASSWORD", "ldap_port":389, "start_tls":false, "ldaps":false, "timeout":10000, "verify_ldap_host":true }'

enforce_rbac = on
admin_gui_auth = ldap-auth-advanced
admin_gui_session_conf = { "secret":"YOUR-SECRET" }
admin_gui_auth_conf = {
    "anonymous":"",
    "attribute":"YOUR-ATTRIBUTE",
    "bind_dn":"YOUR-BIND-DN",
    "base_dn":"YOUR-BASE-DN",
    "cache_ttl": 2,
    "consumer_by":["username", "custom_id"],
    "header_type":"Basic",
    "keepalive":60000,
    "ldap_host":"YOUR-LDAP-HOST",
    "ldap_password":"YOUR-LDAP-PASSWORD",
    "ldap_port":389,
    "start_tls":false,
    "ldaps":false,
    "timeout":10000,
    "verify_ldap_host":true
}

docker restart kong-quickstart-gateway

kong restart

Next, to start using LDAP auth, set up authenticated group mapping.

Recommendations to enhance session security

When authenticating Kong Manager with LDAP, the Session plugin is used to persist the authorization state. This plugin (configured with admin_gui_session_conf) requires a secret and is configured securely by default.

For enhanced security, we recommend setting a few extra session parameters:

• secret: Set this to a string value. A randomly generated secret will be used if unspecified.
• cookie_secure: Defaults to false. We recommend setting this value to true when using HTTPS.
• cookie_same_site: Consider upgrading this value to Strict when using the same domain for the Admin API and Kong Manager. If using different domains for the Admin API and Kong Manager, cookie_same_site must be set to Lax.

Using Kong’s LDAP Auth Advanced plugin, you can map service directory groups to Kong roles for authentication and authorization.

Here’s how service directory mapping works in Kong Gateway:

• Roles are created in Kong Gateway using the Admin API or Kong Manager.
• Groups are created and roles are associated with the groups.
• When users log in to Kong Manager, they get permissions based on the groups they belong to.

When using LDAP service directory mapping, roles assigned to admins are managed by the service directory. The mapping removes the task of manually managing access in Kong Gateway, because it makes the directory the system of record.

If an admin’s group changes in the directory, their Kong admin account’s associated role also changes in Kong Gateway the next time they log in to Kong Manager. Don’t assign or unassign admin roles in Kong Gateway manually, as any changes will be overwritten by the directory during the next login.

Service directory mapping workflows

The following examples show you how to set up LDAP authenticated group mapping for Kong Manager, then create admins in Kong Manager and map them to service directory groups.

Alternatively, you could also choose one of the following workflows:

• Start Kong Gateway with RBAC turned off, map a group to the Super Admin role, and then create an admin to correspond to a user belonging to that group. This approach ensures that the Super Admin’s privileges are entirely tied to the directory group, whereas bootstrapping a Super Admin only uses the directory for authentication.
• Create all admin accounts for matching directory users first and ensure that their existing groups map to appropriate roles before enforcing RBAC.

Set up authenticated group mapping

Review supported configuration options to customize the configuration stored in admin_gui_auth_conf and admin_gui_session_conf.

echo "
  KONG_ENFORCE_RBAC=on \
  KONG_ADMIN_GUI_AUTH=ldap-auth-advanced \
  KONG_ADMIN_GUI_SESSION_CONF={ "secret":"YOUR-SECRET" } \
  KONG_ADMIN_GUI_AUTH_CONF='{
    \"anonymous\":\"\",
    \"attribute\":\"YOUR-ATTRIBUTE\",
    \"bind_dn\":\"YOUR-BIND-DN\",
    \"base_dn\":\"YOUR-BASE-DN\",
    \"cache_ttl\":2,
    \"header_type\":\"Basic\",
    \"keepalive\":60000,
    \"ldap_host\":\"YOUR-LDAP-HOST\",
    \"ldap_password\":\"YOUR-LDAP-PASSWORD\",
    \"ldap_port\":389,
    \"start_tls\":false,
    \"ldaps\":false,
    \"timeout\":10000,
    \"verify_ldap_host\":true,
    \"consumer_by\":[\"username\",\"custom_id\"],
    \"group_base_dn\":\"YOUR-GROUP-BASE-DN\",
    \"group_name_attribute\":\"YOUR-GROUP-NAME-ATTRIBUTE\",
    \"group_member_attribute\":\"YOUR-GROUP-MEMBER-ATTRIBUTE\"
  }' kong reload exit" | docker exec -i YOUR-KONG-CONTAINER-ID /bin/sh

docker restart kong-quickstart-gateway

Managing admins for LDAP mapping

With LDAP enabled, you now need to define roles in Kong Manager and create admins for user-admin mapping.

For example:

1. Example Corp maps the service directory group, T1-Mgmt, to the Kong role Super Admin.
2. Example Corp maps a service directory user, named example-user, to a Kong admin account with the same name, example-user.
3. The user, example-user, is assigned to the group T1-Mgmt in the LDAP Directory.

Define roles with permissions

Define roles with permissions in Kong Gateway using RBAC. You must manually define which Kong roles correspond to each of the service directory’s groups using either of the following:

• In Kong Manager’s directory mapping section. Find it under Teams > Groups tab.
• With the Admin API’s directory mapping endpoints.

Kong Gateway will not write to the service directory. For example, a Kong Gateway admin can’t create users or groups in the directory. You must create users and groups independently in the service directory before mapping them to Kong Gateway.

Group-role assignment

Using service directory mapping, groups are mapped to roles. When a user logs in, they are identified with their admin username and authenticated with the matching user credentials in the service directory. The groups in the service directory are then automatically matched to the associated roles that the organization has defined.

User-admin mapping

To map a service directory user to a Kong Gateway admin, map the admin’s username or custom ID to the DN value corresponding to the attribute configured in admin_gui_auth_conf. If you already have admins in Kong Manager with assigned roles and want to use LDAP group mapping instead, remove all of their roles first. The service directory will serve as the system of record for user privileges.

For example, let’s assume that:

• LDAP config on Kong side:
  • consumer_by is set to username
  • group_member_attribute is UID
• Service directory user: UID=example-user

In this case, you would match the Kong admin’s username attribute to the UID in the service directory, which is example-user.

We recommend pairing the bootstrapped Super Admin with a directory user as the first Super Admin. Using our example values, that would look like this:

 curl -X PATCH "http://localhost:8001/admins/kong_admin" \
     -H "Content-Type: application/json"\
     -H "Kong-Admin-Token: $RBAC_TOKEN" \
     --json '{
       "username": "example-user"
     }'

After creating this admin, map the super-admin role to a group that example-user is in on the LDAP directory side, then delete the super-admin role from the example-user admin on the Kong Gateway side. The group you pick needs to have “super” privileges in your service directory, otherwise as other admins log in with a generic group, they will also become Super Admins.

Important: If you delete the Super Admin role from your only admin, and have not yet mapped the Super Admin role to a group that admin belongs to, then you won’t be able to log in to Kong Manager.

See Admins for more information on creating admins in Kong Manager.