feat(identity): Kong Identity + OIDC

[juliamrch]

Description

closes #5048

Preview Links

Plugin config examples:

• Authorization code flow
• Client credentials grant in header
• Introspection authentication
• JWT access token authentication
• Password grant
• Refresh token grant
• Session authentication
• User info authentication

New shared includes (rendered into the pages above)

• app/_includes/plugins/oidc/identity-server-intro.md
• app/_includes/plugins/oidc/idp-requirement.md

To do

• Set compatibility with on-prem for:

  • Introspection authentication
  • User info authentication
  • Client credentials grant in header
  • JWT access token authentication

• Set incompatibility with on-prem for:

  • Authorization code flow
  • Password grant](https://deploy-preview-5687--kongdeveloper.netlify.app/plugins/openid-connect/examples/password/)
  • Session 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]

✅ Deploy Preview for kongdeveloper ready!

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

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
3 out of 4 committers have signed the CLA.

✅ cloudjumpercat
✅ Guaris
✅ juliamrch
❌ kong-documentation-app[bot]
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Copilot]

Pull request overview

This PR updates the OpenID Connect plugin example configs to enable Principal authentication (via config.principals) and introduces shared includes and a new how-to stub intended to document Principal authentication with OIDC.

Changes:

• Enable Principals lookup/authentication in multiple OpenID Connect plugin config examples.
• Add shared include snippets to standardize the “Kong Identity auth server” intro/requirements copy.
• Add a new how-to page for “Authenticate Principals with the OpenID Connect plugin” (currently frontmatter-only).

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
app/_kong_plugins/openid-connect/examples/user-info-auth.yaml	Adds shared intro/requirement includes and config.principals + directory variable.
app/_kong_plugins/openid-connect/examples/session-auth.yaml	Adds shared intro/requirement includes and config.principals + directory variable.
app/_kong_plugins/openid-connect/examples/refresh-token.yaml	Adds shared intro/requirement includes and config.principals + directory variable.
app/_kong_plugins/openid-connect/examples/password.yaml	Adds shared intro/requirement includes and config.principals + directory variable.
app/_kong_plugins/openid-connect/examples/jwt-access-token.yaml	Adds shared intro/requirement includes and config.principals + directory variable.
app/_kong_plugins/openid-connect/examples/introspection-auth.yaml	Adds shared intro/requirement includes and config.principals + directory variable.
app/_kong_plugins/openid-connect/examples/client-credentials.yaml	Adds shared intro/requirement includes and config.principals + directory variable.
app/_kong_plugins/openid-connect/examples/authorization-code.yaml	Adds shared intro/requirement includes, config.principals, and an additional embedded {% entity_example %} block in extended_description.
app/_includes/plugins/oidc/idp-requirement.md	New include for the “IdP requirement” bullet (link target needs adjustment).
app/_includes/plugins/oidc/identity-server-intro.md	New include describing the Kong Identity auth server context for examples.
app/_how-tos/gateway/authenticate-principals-with-oidc.md	New how-to page (currently only frontmatter; needs content + validation and frontmatter fixes).

Comments suppressed due to low confidence (1)

app/_how-tos/gateway/authenticate-principals-with-oidc.md:61

• This how-to currently has frontmatter only and no steps/validation section after the ---; our how-to convention is an end-to-end tutorial that ends with a validation step users can run.

---

[cloudjumpercat]

TL;DR:

• Apply wording suggestions from the first plugin example to all examples.
• Double check if we should update the example for Kong OAuth token authentication (currently it wasn't updated)
• Update the OIDC plugin overview with info about Kong Identity/principals similar to what you did with other plugin overviews
• Check with Jessup if we'd rather create separate Kong Identity examples instead of overwriting the existing ones.

Longer description:
I've tested all the plugin configs (just checked to see if they ran, didn't run any validations if they could actually authenticate) and I left a few wording suggestions on the first one that would apply to all of them.

I also noticed that all the authentication flow ones were changed to Kong Identity except "Kong OAuth token authentication" wasn't sure if this was intentional or not.

You'll also need to update the OIDC plugin overview with information about Kong Identity/principals (similar to what you did with the other plugins).

Check with Jessup if we'd rather create separate Kong Identity examples instead of overwriting the existing ones.
This one is a can of worms... My recommendation is that we create a new section of plugin examples for Kong Identity, create new plugin example files with the Kong Identity updates you've made and leave the existing examples as-is (ex. create identity-client-credentials.yaml with your updates and leave client-credentials.yaml as it originally was).

Why?

• If we replace the current examples with Kong Identity, we'll need to change the version to 3.15. This will be confusing if it's the only example since users will wonder if they can't do these configurations in pre-3.15 versions (they can, just not with Kong Identity).
• We'd also need to remove - admin-api from supported tools since I'm 90% certain we don't have everything in place to use Kong Identity with on-prem.

The dev team wants to replace Keycloak stuff with Kong Identity, but this is a bigger discussion because to do so, we'd be abandoning on-prem users.