Directories

Uses: Kong Identity Konnect Platform

Control plane access

You can either:

List the control planes that can authenticate against the directory in allowed_control_planes. You can specify a maximum of 32 control planes.
Set allow_all_control_planes to true to allow every control plane in your organization to make authentication requests. This overrides the allowed_control_planes list.

Lookup caching

Kong Identity caches principals on the data plane so that repeated lookups don’t require a connection to Konnect. You can tune the following settings on a directory:

Setting	Description
`ttl_secs`	How long a gateway caches a principal after it authenticates successfully from this directory. Defaults to 600 seconds (10 minutes). Minimum is 300 seconds, maximum is 86400 seconds (24 hours).
`negative_ttl_secs`	How long a gateway waits before it looks up a principal again when the principal doesn’t exist in the directory or the credentials are invalid. Defaults to 600 seconds (10 minutes). Minimum is 300 seconds, maximum is 86400 seconds (24 hours).

For Kong Gateway, the effective cache lifetime is the smallest of the directory TTL, the TTL set on a credential, and the db_cache_ttl configured on the gateway.

Create a directory

Send a POST request to the /v2/directories endpoint:

curl -X POST "https://us.api.konghq.com/v2/directories" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "example-directory",
       "description": "Example directory for principals",
       "allow_all_control_planes": true
     }'

Copied!

Directory limitations

The following are default limits for directories:

1 directory per region. Contact Kong Support if you need more than one directory.
100,000 principals per directory. Contact Kong Support if you need higher limits.
Limit of 100 authentication or principal lookup requests per second per directory, not counting cached requests
Maximum of 32 allowed control planes per directory

Directories

Control plane access

Lookup caching

Create a directory

Directory limitations

Help us make these docs great!

Still need help?