feat(identity): Principal directory reference by cloudjumpercat · Pull Request #5327 · Kong/developer.konghq.com

cloudjumpercat · 2026-05-21T21:06:14Z

Description

Fixes #5033

Preview Links

https://deploy-preview-5327--kongdeveloper.netlify.app/identity/principals/

TODO:

Checklist

Tested how-to docs. If not, note why here.
All pages contain metadata.
Any new docs link to existing docs.
All autogenerated instructions render correctly (API, decK, Konnect, Kong Manager).
Style guide (capitalized gateway entities, placeholder URLs) implemented correctly.
Every page has a description entry in frontmatter.
Add new pages to the product documentation index (if applicable).

netlify · 2026-05-21T21:06:21Z

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	`98f3ef0`
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/6a2858effef87f0008413ad3
😎 Deploy Preview	https://deploy-preview-5327--kongdeveloper.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

ajessup · 2026-06-02T20:32:05Z

+  - text: "{{site.identity}}"
+    url: /kong-identity/
+  - text: "Centrally-managed Consumers"
+    url: /gateway/entities/consumer/#centrally-managed-consumers


Let's drop this. We'll be pushing most CMS customers to Principals going forward, and starting to hide this.

ajessup · 2026-06-02T20:33:01Z

+
+{{site.identity}} uses principals and directories to unify how Kong products represent the entities they authenticate. 
+
+* **Principal:** Represents an entity that authenticates to a Kong product. 


s/a Kong Product/a Kong Gateway/

(so as to not confuse with Konnect Users or Developer Portal Developers which are different concepts entirely)

ajessup · 2026-06-02T20:33:54Z

+* **Principal:** Represents an entity that authenticates to a Kong product. 
+  The entity can be a human, a workload acting on behalf of a human, or a workload acting on behalf of itself (machine authentication).
+* **Directory:** Regional collection of principals. 
+  Each {{site.konnect_short_name}} organization gets one directory per region.


s/gets one directory per region/can provision up to one directory per region by default/

ajessup · 2026-06-02T20:38:30Z

+  Each {{site.konnect_short_name}} organization gets one directory per region.
+
+Principals can be used for:
+* {{site.base_gateway}} in {{site.konnect_short_name}}: Can both authenticate clients against a principal and look up principal metadata after authentication


I'd suggest something like:

Principals can be used for:

In Kong Gateway in Konnect: Can be used to authenticate an entity for API traffic (using API Keys or Basic Auth usernames and passwords) or can be used to provide metadata about an entity for OAuth-authenticated traffic.

In Event Gateway: Can be used metadata about an authenticated entity

In Developer Portal: Can be used to adjust API Gateway behavior based on the authenticating Developer Portal Application

ajessup · 2026-06-02T20:39:19Z

+  - title: Description
+    key: description
+rows:
+  - usecase: "Authenticate clients at {{site.base_gateway}}"


'clients' is an OAuth term that we also use elsewhere in Kong Identity. Maybe use "authenticate API traffic" instead?

ajessup · 2026-06-02T20:46:35Z

+
+You can use metadata for policy decisions. 
+For example:
+* A rate limiting plugin can filter by `principal.metadata.tier`.


This is a great example, but won't actually be true until 3.16 :(

ajessup · 2026-06-02T20:46:47Z

+For example:
+* A rate limiting plugin can filter by `principal.metadata.tier`.
+* An ACL plugin can allow access only when `principal.metadata.business_unit == "payments"`.
+* A logging plugin can include `principal.metadata.region` in every log line.


This is a great example, but won't actually be true until 3.16 :(

ajessup · 2026-06-02T20:49:17Z

+* An ACL plugin can allow access only when `principal.metadata.business_unit == "payments"`.
+* A logging plugin can include `principal.metadata.region` in every log line.
+
+## Apply plugins to principals


I actually expected this heading to talk about how to configure the api key, basic auth or ODIC plugins. While we obviously don't want a full how-to should we have a section that briefly mentions those?

This is important too but I'd suggest a more specific heading, eg. "Controlling API Gateway Plugin Execution based on Principals"

Yep! I'll add those in an examples section.

ajessup · 2026-06-02T20:50:45Z

+* `principal.metadata.*`: Any metadata key on the principal
+* `principal.identities.*`: Any identity on the principal
+
+## Principal limitations


Should this go at the end?

ajessup · 2026-06-02T20:55:15Z

+* An ACL plugin can allow access only when `principal.metadata.business_unit == "payments"`.
+* A logging plugin can include `principal.metadata.region` in every log line.
+
+## Apply plugins to principals


Where do we talk about configuring event GW virtual cluster authentication or policies?

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

jdemartini81 · 2026-06-04T20:57:20Z

+## Create a directory
+
+{% navtabs "create-directory" %}
+{% navtab "API" %}


A user can provision a directory in the UI as well, so I do think it's worth noting that here. If a user has not created the directory in the API, in the UI, when the user creates their first principal, a default directory is created on their behalf.

@jdemartini81 Happy to add UI instructions for the directory! Could you point me to where in the UI (or Figma mockups) where a user can configure the directory? I couldn't find it in the UI or the Unification Figma mockups.

It automatically is created when a user creates their first principal. My suggestion is to describe this behavior. For instance, if you have not yet created your directory via the API, to create it via the UI, simply create your first principal. We will create a "default" directory on your behalf. (You have a better flair for words than me.)

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

ajessup · 2026-06-11T01:43:13Z

+  - text: "{{site.identity}}"
+    url: /kong-identity/
+  - text: "{{site.konnect_short_name}} control plane resource limits"
+    url: /gateway/control-plane-resource-limits/


Should we link to the Konnect API spec for Kong Identity too?

ajessup · 2026-06-11T01:44:21Z

+
+{{site.identity}} uses principals and directories to unify how Kong products represent the entities they authenticate. 
+
+* **Principal:** Represents an external client or workload (not a human {{site.konnect_short_name}} user or {{site.dev_portal}} developer) that authenticates to a {{site.base_gateway}}.


This is a little misleading. A principal can reprresent a human - but one authenticating to a customer's Gateway. But it is a different entity from a Dev Portal Developer or a Konnect User.

ajessup · 2026-06-11T01:47:24Z

+  Each {{site.konnect_short_name}} organization can provision up to one directory per region by default.
+
+Principals can be used for:
+* {{site.base_gateway}} in {{site.konnect_short_name}}: Can be used to authenticate an entity for API traffic (using API keys or basic auth usernames and passwords) or can be used to provide metadata about an entity for OAuth-authenticated traffic.


entity for OAuth-authenticated traffic

We are going to do this for other authentication schemes too (eg. mTLS) in future releases so it might be worth re-wording this to something like "can be used to provide metadata about an entity already authenticated through another mechanism (such as OAuth)"

ajessup · 2026-06-11T01:48:38Z

+
+Principals can be used for:
+* {{site.base_gateway}} in {{site.konnect_short_name}}: Can be used to authenticate an entity for API traffic (using API keys or basic auth usernames and passwords) or can be used to provide metadata about an entity for OAuth-authenticated traffic.
+* {{site.event_gateway_short}}: Can use metadata about an authenticated entity


Suggest something like "can be used to provide metadata about an entity already authenticated through another mechanism (such as SASL/SCRAM or SASL/OAUTHBEARER)

ajessup · 2026-06-11T01:49:46Z

+  - usecase: "Share identity across Kong products"
+    description: "Define a principal once and use it for {{site.base_gateway}}, {{site.event_gateway_short}}, and {{site.dev_portal}} without manually synchronizing identities."
+  - usecase: "Drive gateway behavior with metadata"
+    description: "Scope rate limits, ACLs, and conditional plugin execution by attributes that the principal carries, such as business unit or tier."


ACLs and rate limits aren't actually coming until 3.16. Conditional plugin execution is there though.

ajessup · 2026-06-11T02:50:21Z

+Metadata is a set of key/value pairs attached to a principal that are made available in the request context of a {{site.base_gateway}} or {{site.event_gateway_short}} after that principal has been authenticated, or looked up, in the request context.
+
+You can use metadata to configure how a gateway behaves when that principal is authenticated to it.
+For example, an ACL plugin can allow access only when `principal.metadata.business_unit == "payments"`.


ACL plugin does not yet explicitly support Principals. However you can add a conditional expression to the Request Termination plugin.

ajessup · 2026-06-11T02:51:31Z

+* **Unify identity across Kong products:** Consumers and applications each represent the same logical entity in different ways, which makes it hard to reason about authentication, policy, and observability together. Principals replace that with one model.
+* **Attach metadata to identity:** Consumers don't support metadata, which forces custom plugins or header-injection workarounds when you want per-entity rate limits, conditional plugin behavior, or richer logs. Principals support metadata natively.
+
+If you have existing Consumers you want to migrate to principals, see [HOW TO PLACEHOLDER](/).


I think we decided this was going to be a fast follow :)

ajessup · 2026-06-11T02:56:27Z

+
+* `principal.id`: The UUID of the principal
+* `principal.metadata.*`: Any metadata key on the principal
+* `principal.identities.*`: Any identity on the principal


Can we double check this is true with @jijiechen ? If so, what is the schema of the different identity objects?

ajessup · 2026-06-11T02:56:41Z

+## Controlling {{site.base_gateway}} plugin execution based on principals
+
+Plugins can read principal attributes from the request context after authentication. 
+The only way to scope plugins to a principal is by using conditional plugin execution on the principal metadata.


Worth linking to the conditional plugin execution docs.

ajessup · 2026-06-11T02:58:49Z

+
+### Link a principal to a Consumer Group
+
+placeholder, need array config


@jijiechen can help here.

cloudjumpercat added the release-docs Docs for release label May 21, 2026

cloudjumpercat added 2 commits May 28, 2026 15:05

First draft of principals reference, it's rough

9e84540

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

revise

52cb7b3

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

cloudjumpercat force-pushed the feat/principal-directory-reference branch from 3994272 to 52cb7b3 Compare May 28, 2026 20:05

cloudjumpercat commented May 28, 2026

View reviewed changes

Comment thread app/kong-identity/principals-and-directories.md Outdated

cloudjumpercat commented May 28, 2026

View reviewed changes

Comment thread app/kong-identity/principals-and-directories.md Outdated

cloudjumpercat added 3 commits May 28, 2026 17:01

fix the failing build

3387f5c

Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

Fixes from spec, other wording and formatting, add API request examples

60ce8af

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

Kong Identity variable

5ebf2d9

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

ajessup reviewed Jun 2, 2026

View reviewed changes

juliamrch mentioned this pull request Jun 3, 2026

Kong Identity: Basic auth support #5037

Open

cloudjumpercat added 3 commits June 3, 2026 16:24

Apply PM feedback, new KEG section, new examples section

edaa54f

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

UI steps draft

5bcc4c1

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

fix broken links

c8b40de

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

jdemartini81 reviewed Jun 4, 2026

View reviewed changes

juliamrch mentioned this pull request Jun 5, 2026

feat(identity): authenticate principals with Basic Auth #5451

Draft

7 tasks

cloudjumpercat added 2 commits June 8, 2026 13:55

Add note about creating a directory in the UI

2fac738

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

Add lookup caching note

98f3ef0

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

ajessup reviewed Jun 11, 2026

View reviewed changes


		{{site.identity}} uses principals and directories to unify how Kong products represent the entities they authenticate.

		* Principal: Represents an entity that authenticates to a Kong product.


		{{site.identity}} uses principals and directories to unify how Kong products represent the entities they authenticate.

		* Principal: Represents an external client or workload (not a human {{site.konnect_short_name}} user or {{site.dev_portal}} developer) that authenticates to a {{site.base_gateway}}.


		### Link a principal to a Consumer Group

		placeholder, need array config

Conversation

cloudjumpercat commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Preview Links

Checklist

Uh oh!

netlify Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for kongdeveloper ready!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cloudjumpercat commented May 21, 2026 •

edited

Loading

netlify Bot commented May 21, 2026 •

edited

Loading