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	`c8b40de`
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/6a21b376dbb1bf000832c5e5
😎 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.)

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

Open

7 tasks


		{{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.

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!

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