feat(identity): authenticate principals with Basic Auth by juliamrch · Pull Request #5451 · Kong/developer.konghq.com

juliamrch · 2026-06-03T18:17:29Z

Description

closes #5037

This PR contains a new guide for Kong Identity, using Principals and Basic Auth.

Preview Links

https://deploy-preview-5451--kongdeveloper.netlify.app/how-to/authenticate-principals-with-basic-authentication/

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-06-03T18:17:36Z

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	`b395792`
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/6a22d6ceaa20120008a28cef
😎 Deploy Preview	https://deploy-preview-5451--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>

Copilot

Pull request overview

Adds new Kong Identity documentation covering the core concepts of Directories/Principals and a Gateway how-to showing how to authenticate Principals using the Basic Authentication plugin.

Changes:

Introduces a new Kong Identity reference page explaining Principals, Directories, identities, credentials, metadata, and limits.
Adds a new Gateway how-to that creates a Directory + Principal and configures the Basic Auth plugin to authenticate Principals.
Includes validation steps demonstrating unauthorized vs authorized requests.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
app/kong-identity/principals-and-directories.md	New reference page defining Kong Identity Principals/Directories and how they map to Gateway concepts.
app/_how-tos/gateway/authenticate-principals-with-basic-authentication.md	New how-to for configuring Basic Auth to authenticate Kong Identity Principals and validating requests.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Guaris · 2026-06-03T18:49:47Z

+## Create a directory
+
+{% navtabs "create-directory" %}
+{% navtab "UI" %}
+
+UI steps will be added once the feature is available for testing.
+
+{% endnavtab %}
+{% navtab "API" %}
+
+Send a `POST` request to the [`/v2/directories` endpoint](/api/konnect/kong-identity/v2/#/operations/createDirectory):
+
+<!--vale off-->
+{% konnect_api_request %}
+url: /v2/directories
+status_code: 201
+method: POST
+body:
+  name: example-directory
+  description: Example directory for principals
+  allow_all_control_planes: true
+{% endkonnect_api_request %}
+<!--vale on-->
+
+{% endnavtab %}
+{% navtab "Terraform" %}
+
+Terraform steps will be added once the feature is available for testing.
+
+{% endnavtab %}
+{% endnavtabs %}
+
+## Configure a principal
+
+Configuring a principal is a multi-step process. You always create the principal first, then attach identities. Metadata is optional.
+
+{% navtabs "configure-principal" %}
+{% navtab "UI" %}
+
+UI steps will be added once the feature is available for testing.
+
+{% endnavtab %}
+{% navtab "API" %}
+
+1. Create the principal by sending a `POST` request to the [`/v2/directories/{directoryId}/principals` endpoint](/api/konnect/kong-identity/v2/#/operations/createPrincipal):
+{% capture create_principal %}
+<!--vale off-->
+{% konnect_api_request %}
+url: /v2/directories/$DIRECTORY_ID/principals
+status_code: 201
+method: POST
+body:
+  display_name: example-principal
+  description: Example principal
+{% endkonnect_api_request %}
+<!--vale on-->
+{% endcapture %}
+{{ create_principal | indent: 3}}
+
+1. Link an identity to a principal by sending a `POST` request to the [`/v2/directories/{directoryId}/principals/{principalId}/identities` endpoint](/api/konnect/kong-identity/v2/#/operations/createIdentity). In this example, you'll be attaching a `control_plane_consumer` identity to map the principal to a Consumer in a {{site.base_gateway}} control plane:
+{% capture link_identity %}
+<!--vale off-->
+{% konnect_api_request %}
+url: /v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/identities
+status_code: 201
+method: POST
+body:
+  type: control_plane_consumer
+  control_plane_id: $CONTROL_PLANE_ID
+  consumer_id: $CONSUMER_ID
+{% endkonnect_api_request %}
+<!--vale on-->
+{% endcapture %}
+{{ link_identity | indent: 3}}
+
+   For other identity types and the fields each one accepts, see [Identities](#identities).
+
+   {:.info}
+   > If you want to authenticate clients against this principal using basic auth or an API key, you also need to add the credentials in separate API calls:
+   > * **Basic auth:** `POST` to [`/v2/directories/{directoryId}/principals/{principalId}/basic-auths`](/api/konnect/kong-identity/v2/#/operations/createBasicAuth) to create the basic auth entry, then `POST` to [`/v2/directories/{directoryId}/principals/{principalId}/basic-auths/{basicAuthId}/passwords`](/api/konnect/kong-identity/v2/#/operations/createPassword) to set a password.
+   > * **API key:** `POST` to [`/v2/directories/{directoryId}/principals/{principalId}/api-keys`](/api/konnect/kong-identity/v2/#/operations/createKey).
+
+1. (Optional) Add or update metadata on the principal by sending a `PATCH` request to the [`/v2/directories/{directoryId}/principals/{principalId}` endpoint](/api/konnect/kong-identity/v2/#/operations/updatePrincipal):
+{% capture update_metadata %}
+<!--vale off-->
+{% konnect_api_request %}
+url: /v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID
+status_code: 200
+method: PATCH
+body:
+  metadata:
+    business_unit: payments
+    tier: gold
+{% endkonnect_api_request %}
+<!--vale on-->
+{% endcapture %}
+{{ update_metadata | indent: 3}}
+
+{% endnavtab %}
+{% navtab "Terraform" %}
+
+Terraform steps will be added once the feature is available for testing.
+
+{% endnavtab %}
+{% endnavtabs %}


Should this go in a how-to?

Not sure, it's more a tutorial that @cloudjumpercat included in a reference page (this page comes from a cherry-pick from her branch) than a how-to .

Is this a core workflow for identity? If so why not have it as a how to?

@Guaris This content will be in the various how tos since creating a principal and directory are required for those flows. It also exists on the Principals reference page (work in progress, PR is here if you want to check it out) similar to what we have for Gateway entities, like Set up a Consumer. That way information about the entity + general steps of how to configure it using various tools are in one space. We'll have links to the how tos on the reference page as well for users who want the more opinionated how to flows.

juliamrch added 2 commits June 3, 2026 15:40

feat(identity): duplicate guide

e9c14a2

feat(identity): write guide

3ce4f87

juliamrch self-assigned this Jun 3, 2026

juliamrch added release-docs Docs for release product:kong-identity labels Jun 3, 2026

juliamrch added this to the Kong Identity M0 and M1.1 milestone Jun 3, 2026

juliamrch changed the base branch from main to release/kong-identity-m0 June 3, 2026 18:18

cloudjumpercat and others added 6 commits June 3, 2026 20:24

First draft of principals reference, it's rough

0aa3fe6

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

revise

2800d1a

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

fix the failing build

a950917

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

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

1a15fc4

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

Kong Identity variable

f14c9bd

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

feat(identity): add links + fix syntax

329dace

juliamrch marked this pull request as ready for review June 3, 2026 18:25

juliamrch requested a review from a team as a code owner June 3, 2026 18:25

Copilot AI review requested due to automatic review settings June 3, 2026 18:25

Copilot started reviewing on behalf of juliamrch June 3, 2026 18:25 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

juliamrch and others added 6 commits June 3, 2026 20:37

Potential fix for pull request finding

e977c0f

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

3a08f20

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

9acd4fb

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

afd5aff

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

af254d0

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

feat(identity): add to index

87f9df9

Guaris reviewed Jun 3, 2026

View reviewed changes

juliamrch added 2 commits June 5, 2026 11:41

Merge branch 'release/kong-identity-m0' into iss5037

ac9d028

styles: add datetimes to dictionary

b395792

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat(identity): authenticate principals with Basic Auth#5451
juliamrch wants to merge 16 commits into
release/kong-identity-m0from
iss5037

juliamrch commented Jun 3, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jun 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Guaris Jun 3, 2026

Uh oh!

juliamrch Jun 5, 2026

Uh oh!

Guaris Jun 5, 2026

Uh oh!

cloudjumpercat Jun 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

juliamrch commented Jun 3, 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 Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for kongdeveloper ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Guaris Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

juliamrch Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Guaris Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

cloudjumpercat Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

juliamrch commented Jun 3, 2026 •

edited

Loading

netlify Bot commented Jun 3, 2026 •

edited

Loading