feat(identity): migrate from OAuth 2.0 plugin to Kong Identity authorization servers and OIDC

[juliamrch]

Description

This PR provides instructions for migrating from the legacy OAuth 2.0 plugin to Kong Identity + OIDC plugin on an Enterprise setup.

• Test on-prem
• Run the workflow
• Write the page
• Add versioning warnings and options
• Create on-prem setup scripts for reviewers

closes #3462

Preview Links

https://deploy-preview-6483--kongdeveloper.netlify.app/identity/migrate-oauth-to-identity

Testing Instructions

The following scripts set up a stack that a user following this guide is expected to have.

You need a valid Kong license saved as KONG_LICENSE_DATA. Then run the following scripts (for example: ./00-reviewer-bootstrap.sh):

0. Before migrating a single or multiple Consumers to a single or all services:
   00-reviewer-bootstrap.sh

1. Cleanup Identity resources between tests:
   01-cleanup-identity.sh

Troubleshooting tests

To test the sanitizing and de-hashing scripts
2. Migrate a hashed credential:
02-add-hashed-consumer.sh
3. Migrate a malformed client_id:
03-add-malformed-client-id.sh

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	e766efb
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/6a75e300b37d7e0008bf90d5
😎 Deploy Preview	https://deploy-preview-6483--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.

[Copilot]

Pull request overview

Adds a new Kong Identity reference page to guide users migrating from the legacy Kong Gateway OAuth 2.0 plugin to Kong Identity (client credentials flow), plus a small Vale dictionary update to support the new terminology.

Changes:

• Added a new migration reference doc under app/kong-identity/ describing the end-to-end migration workflow (credential extraction, auth server/client setup, Consumer mapping, OIDC plugin configuration, and verification).
• Updated the Vale dictionary to accept the term “unhashed”.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
app/kong-identity/migrate-oauth-to-identity.md	New migration reference doc for moving from OAuth 2.0 plugin to Kong Identity + OIDC validation.
.github/styles/base/Dictionary.txt	Adds “unhashed” to prevent style/spellcheck false positives in the new doc.

Suppressed comments (2)

app/kong-identity/migrate-oauth-to-identity.md:317

• This sentence suggests configuring OAuth 2.0 Introspection as an alternative, but the rest of the guide only documents the OIDC plugin; either add Introspection steps or remove the mention here to match the actual workflow.

Your current setup with the OAuth 2.0 plugin still maps the old Consumer. To finish the migration, configure the OIDC or OAuth 2.0 Introspection plugin to start using tokens issued by the {{site.identity}} authorization server.

app/kong-identity/migrate-oauth-to-identity.md:513

• The verification step says to check X-Consumer-* response headers, but the example pipes the response body to jq and doesn't print headers; use -D - (or -i) so readers can actually see the headers and status code.

curl -sk $KONG_PROXY_URL${ROUTE_PATH} \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq