From f578ea7c389a60e1c981fb35c3f1e1a71780a225 Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Wed, 24 Jun 2026 11:59:17 +0200
Subject: [PATCH 01/13] feat(identity): draft metadata

---
 .../authenticate-principals-with-oidc.md      | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 app/_how-tos/gateway/authenticate-principals-with-oidc.md

diff --git a/app/_how-tos/gateway/authenticate-principals-with-oidc.md b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
new file mode 100644
index 00000000000..994bd4b2d29
--- /dev/null
+++ b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
@@ -0,0 +1,60 @@
+---
+title: Authenticate Principals with the OIDC plugin
+permalink: /how-to/authenticate-principals-with-oidc/
+content_type: how_to
+breadcrumbs:
+  - /identity/
+related_resources:
+  - text: Authentication
+    url: /gateway/authentication/
+
+description: Use the OIDC plugin to allow Principals to authenticate.
+products:
+    - gateway
+    - identity
+
+plugins:
+  - key-auth
+works_on:
+    - on-prem
+    - konnect
+
+min_version:
+  gateway: '3.15'
+entities: 
+  - plugin
+  - service
+  - route
+  - principal
+
+tags:
+    - authentication
+
+tools:
+    - deck
+
+tldr:
+  q: How do I authenticate Principals with OIDC?
+  a: |
+    SUMMARY HERE
+
+prereqs:
+  entities:
+    services:
+        - example-service
+    routes:
+        - example-route
+  inline:
+    - title: Kong Identity directory
+      include_content: prereqs/kong-identity-directory
+      icon_url: /assets/icons/identity.svg
+
+cleanup:
+  inline:
+    - title: Clean up Konnect environment
+      include_content: cleanup/platform/konnect
+      icon_url: /assets/icons/gateway.svg
+    - title: Destroy the {{site.base_gateway}} container
+      include_content: cleanup/products/gateway
+      icon_url: /assets/icons/gateway.svg
+---

From 47e1cb6574d41f0738cc6fc9c80e40fb9d3e8e73 Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Wed, 24 Jun 2026 12:09:54 +0200
Subject: [PATCH 02/13] feat(identity): replace OIDC with OpenId Connect

---
 app/_how-tos/gateway/authenticate-principals-with-oidc.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/app/_how-tos/gateway/authenticate-principals-with-oidc.md b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
index 994bd4b2d29..306acbc55d1 100644
--- a/app/_how-tos/gateway/authenticate-principals-with-oidc.md
+++ b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
@@ -1,5 +1,5 @@
 ---
-title: Authenticate Principals with the OIDC plugin
+title: Authenticate Principals with the OpenID Connect plugin
 permalink: /how-to/authenticate-principals-with-oidc/
 content_type: how_to
 breadcrumbs:
@@ -8,7 +8,7 @@ related_resources:
   - text: Authentication
     url: /gateway/authentication/
 
-description: Use the OIDC plugin to allow Principals to authenticate.
+description: Use the OpenID Connect plugin to allow Principals to authenticate.
 products:
     - gateway
     - identity
@@ -34,7 +34,7 @@ tools:
     - deck
 
 tldr:
-  q: How do I authenticate Principals with OIDC?
+  q: How do I authenticate Principals with OpenID Connect?
   a: |
     SUMMARY HERE
 

From 3a22cd39e248cb68e8f2ff1ee5e31c906fbcf367 Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Wed, 24 Jun 2026 15:44:17 +0200
Subject: [PATCH 03/13] feat(identity): authorization-code-example

---
 .../examples/authorization-code.yaml          | 39 +++++++++++++++++--
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/app/_kong_plugins/openid-connect/examples/authorization-code.yaml b/app/_kong_plugins/openid-connect/examples/authorization-code.yaml
index 6c7a79cdaf2..5a270a25f08 100644
--- a/app/_kong_plugins/openid-connect/examples/authorization-code.yaml
+++ b/app/_kong_plugins/openid-connect/examples/authorization-code.yaml
@@ -9,11 +9,38 @@ extended_description: |
 
   {% include_cached plugins/oidc/diagrams/auth-code.md %}
 
-  For a full example that shows you how to set up the authorization code flow with Keycloak, 
+  You can use either:
+  
+  - An {{ site.identity }} authorization server hosted on {{ site.konnect_short_name }}.
+  - An external authorization server like Keycloak. For a full example that shows you how to set up the authorization code flow with Keycloak,
   see [Configure OpenID Connect with the auth code flow](/how-to/configure-oidc-with-auth-code-flow/).
 
   {% include_cached plugins/oidc/client-auth.md %}
 
+  {% entity_example %}
+  type: plugin
+  data:
+    name: openid-connect
+    config:
+      issuer: ${issuer}
+      client_id:
+        - ${client-id}
+      client_secret:
+        - ${client-secret}
+      client_auth:
+        - client_secret_post
+      auth_methods:
+        - authorization_code
+        - session
+      response_mode: form_post
+      preserve_query_args: true
+      login_action: redirect
+      login_tokens: null
+      principals:
+        enabled: true
+        directory: ${directory-name}
+  {% endentity_example %}
+
 weight: 900
 
 requirements:
@@ -30,23 +57,29 @@ config:
   auth_methods:
     - authorization_code
     - session
+  
   response_mode: form_post
   preserve_query_args: true
   login_action: redirect
   login_tokens: null
+  principals:
+    enabled: true
+    directory: ${directory-name}
 
 variables:
   issuer:
     value: $ISSUER
     description: |
-      The issuer authentication URL for your IdP. 
-      For example, if you're using Keycloak as your IdP, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
+      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`. If you're using Keycloak, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
   client-id:
     value: $CLIENT_ID
     description: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
   client-secret:
     value: $CLIENT_SECRET
     description: The client secret needed to connect to your IdP.
+  directory-name:
+    value: $DIRECTORY_NAME
+    description: When using {{ site.identity }} as your IdP, the name of the directory used for principals lookup.
 
 tools:
   - deck

From 71204cb47b83a4227c8d7ef44954ade22b1de60c Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Wed, 24 Jun 2026 17:14:02 +0200
Subject: [PATCH 04/13] feat(identity): update relevant plugin examples to
 enable principals

---
 .../plugins/oidc/identity-server-intro.md         |  1 +
 app/_includes/plugins/oidc/idp-requirement.md     |  1 +
 .../examples/authorization-code.yaml              | 12 +++++-------
 .../examples/client-credentials.yaml              | 15 +++++++++++----
 .../examples/introspection-auth.yaml              | 15 +++++++++++----
 .../openid-connect/examples/jwt-access-token.yaml | 15 +++++++++++----
 .../openid-connect/examples/password.yaml         | 15 +++++++++++----
 .../openid-connect/examples/refresh-token.yaml    | 15 +++++++++++----
 .../openid-connect/examples/session-auth.yaml     | 15 +++++++++++----
 .../openid-connect/examples/user-info-auth.yaml   | 15 +++++++++++----
 10 files changed, 84 insertions(+), 35 deletions(-)
 create mode 100644 app/_includes/plugins/oidc/identity-server-intro.md
 create mode 100644 app/_includes/plugins/oidc/idp-requirement.md

diff --git a/app/_includes/plugins/oidc/identity-server-intro.md b/app/_includes/plugins/oidc/identity-server-intro.md
new file mode 100644
index 00000000000..30f3c20883f
--- /dev/null
+++ b/app/_includes/plugins/oidc/identity-server-intro.md
@@ -0,0 +1 @@
+This example uses a {{ site.identity }} authorization server hosted on {{ site.konnect_short_name }}.
\ No newline at end of file
diff --git a/app/_includes/plugins/oidc/idp-requirement.md b/app/_includes/plugins/oidc/idp-requirement.md
new file mode 100644
index 00000000000..b8ad74b5809
--- /dev/null
+++ b/app/_includes/plugins/oidc/idp-requirement.md
@@ -0,0 +1 @@
+A {{ site.identity }} [authorization server](/identity/principals/)
\ No newline at end of file
diff --git a/app/_kong_plugins/openid-connect/examples/authorization-code.yaml b/app/_kong_plugins/openid-connect/examples/authorization-code.yaml
index 5a270a25f08..9c94118510a 100644
--- a/app/_kong_plugins/openid-connect/examples/authorization-code.yaml
+++ b/app/_kong_plugins/openid-connect/examples/authorization-code.yaml
@@ -9,10 +9,8 @@ extended_description: |
 
   {% include_cached plugins/oidc/diagrams/auth-code.md %}
 
-  You can use either:
-  
-  - An {{ site.identity }} authorization server hosted on {{ site.konnect_short_name }}.
-  - An external authorization server like Keycloak. For a full example that shows you how to set up the authorization code flow with Keycloak,
+  {% include_cached plugins/oidc/identity-server-intro.md %}
+  To use an external authorization server like Keycloak,
   see [Configure OpenID Connect with the auth code flow](/how-to/configure-oidc-with-auth-code-flow/).
 
   {% include_cached plugins/oidc/client-auth.md %}
@@ -44,7 +42,7 @@ extended_description: |
 weight: 900
 
 requirements:
-  - A configured identity provider (IdP)
+  - "{% include_cached plugins/oidc/idp-requirement.md %}"
 
 config:
   issuer: ${issuer}
@@ -70,7 +68,7 @@ variables:
   issuer:
     value: $ISSUER
     description: |
-      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`. If you're using Keycloak, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
+      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`.
   client-id:
     value: $CLIENT_ID
     description: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
@@ -79,7 +77,7 @@ variables:
     description: The client secret needed to connect to your IdP.
   directory-name:
     value: $DIRECTORY_NAME
-    description: When using {{ site.identity }} as your IdP, the name of the directory used for principals lookup.
+    description: The name of the {{ site.identity }} directory used for principals lookup.
 
 tools:
   - deck
diff --git a/app/_kong_plugins/openid-connect/examples/client-credentials.yaml b/app/_kong_plugins/openid-connect/examples/client-credentials.yaml
index 4ff1fd27abc..45b7df16865 100644
--- a/app/_kong_plugins/openid-connect/examples/client-credentials.yaml
+++ b/app/_kong_plugins/openid-connect/examples/client-credentials.yaml
@@ -11,14 +11,16 @@ extended_description: |
   In this example, the plugin will only accept client credentials sent in a header, 
   but you can also set the `client_credentials_param_type` parameter to `body`, `query`, or any combination of these values.
 
-  For a complete example of authenticating with client credentials using Keycloak, see the tutorial for [configuring OpenID Connect with the client credentials grant](/how-to/configure-oidc-with-client-credentials/).
+  {% include_cached plugins/oidc/identity-server-intro.md %}
+  To use an external authorization server like Keycloak,
+  see [configuring OpenID Connect with the client credentials grant](/how-to/configure-oidc-with-client-credentials/).
 
   {% include_cached plugins/oidc/client-auth.md %}
 
 weight: 899
 
 requirements:
-  - A configured identity provider (IdP)
+  - "{% include_cached plugins/oidc/idp-requirement.md %}"
 
 config:
   issuer: ${issuer}
@@ -32,19 +34,24 @@ config:
     - client_credentials
   client_credentials_param_type:
     - header
+  principals:
+    enabled: true
+    directory: ${directory-name}
 
 variables:
   issuer:
     value: $ISSUER
     description: |
-      The issuer authentication URL for your IdP. 
-      For example, if you're using Keycloak as your IdP, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
+      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`.
   client-id:
     value: $CLIENT_ID
     description: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
   client-secret:
     value: $CLIENT_SECRET
     description: The client secret needed to connect to your IdP.
+  directory-name:
+    value: $DIRECTORY_NAME
+    description: The name of the {{ site.identity }} directory used for principals lookup.
 
 tools:
   - deck
diff --git a/app/_kong_plugins/openid-connect/examples/introspection-auth.yaml b/app/_kong_plugins/openid-connect/examples/introspection-auth.yaml
index 5567d131dc3..6be29c63b46 100644
--- a/app/_kong_plugins/openid-connect/examples/introspection-auth.yaml
+++ b/app/_kong_plugins/openid-connect/examples/introspection-auth.yaml
@@ -11,14 +11,16 @@ extended_description: |
   In this example, the plugin will only accept a bearer token sent in a header, 
   but you can also set the `bearer_token_param_type` parameter to `body`, `query`, or any combination of these values.
   
-  For a complete example of authenticating with a token retrieved through Keycloak's introspection endpoint, see the tutorial for [configuring OpenID Connect with introspection](/how-to/configure-oidc-with-introspection/).
+  {% include_cached plugins/oidc/identity-server-intro.md %}
+  To use an external authorization server like Keycloak,
+  see [configuring OpenID Connect with introspection](/how-to/configure-oidc-with-introspection/).
   
   {% include_cached plugins/oidc/client-auth.md %}
 
 weight: 898
 
 requirements:
-  - A configured identity provider (IdP)
+  - "{% include_cached plugins/oidc/idp-requirement.md %}"
 
 config:
   issuer: ${issuer}
@@ -32,19 +34,24 @@ config:
     - introspection
   bearer_token_param_type:
     - header
+  principals:
+    enabled: true
+    directory: ${directory-name}
 
 variables:
   issuer:
     value: $ISSUER
     description: |
-      The issuer authentication URL for your IdP. 
-      For example, if you're using Keycloak as your IdP, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
+      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`.
   client-id:
     value: $CLIENT_ID
     description: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
   client-secret:
     value: $CLIENT_SECRET
     description: The client secret needed to connect to your IdP.
+  directory-name:
+    value: $DIRECTORY_NAME
+    description: The name of the {{ site.identity }} directory used for principals lookup.
 
 tools:
   - deck
diff --git a/app/_kong_plugins/openid-connect/examples/jwt-access-token.yaml b/app/_kong_plugins/openid-connect/examples/jwt-access-token.yaml
index 0d3c67a9266..dfff3c76506 100644
--- a/app/_kong_plugins/openid-connect/examples/jwt-access-token.yaml
+++ b/app/_kong_plugins/openid-connect/examples/jwt-access-token.yaml
@@ -11,14 +11,16 @@ extended_description: |
   In this example, the plugin will only accept a bearer token sent in a query string, 
   but you can also set the `bearer_token_param_type` parameter to `body`, `header`, or any combination of these values.
   
-  For a complete example of authenticating with a JWT access token using Keycloak, see the tutorial for [configuring OpenID Connect with JWT authentication](/how-to/configure-oidc-with-jwt-auth/).
+  {% include_cached plugins/oidc/identity-server-intro.md %}
+  To use an external authorization server like Keycloak,
+  see [configuring OpenID Connect with JWT authentication](/how-to/configure-oidc-with-jwt-auth/).
   
   {% include_cached plugins/oidc/client-auth.md %}
 
 weight: 897
 
 requirements:
-  - A configured identity provider (IdP)
+  - "{% include_cached plugins/oidc/idp-requirement.md %}"
 
 config:
   issuer: ${issuer}
@@ -32,19 +34,24 @@ config:
     - bearer
   bearer_token_param_type:
     - query
+  principals:
+    enabled: true
+    directory: ${directory-name}
 
 variables:
   issuer:
     value: $ISSUER
     description: |
-      The issuer authentication URL for your IdP. 
-      For example, if you're using Keycloak as your IdP, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
+      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`.
   client-id:
     value: $CLIENT_ID
     description: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
   client-secret:
     value: $CLIENT_SECRET
     description: The client secret needed to connect to your IdP.
+  directory-name:
+    value: $DIRECTORY_NAME
+    description: The name of the {{ site.identity }} directory used for principals lookup.
 
 
 tools:
diff --git a/app/_kong_plugins/openid-connect/examples/password.yaml b/app/_kong_plugins/openid-connect/examples/password.yaml
index 6863bba7f4c..db3383ab476 100644
--- a/app/_kong_plugins/openid-connect/examples/password.yaml
+++ b/app/_kong_plugins/openid-connect/examples/password.yaml
@@ -18,14 +18,16 @@ extended_description: |
   We're also passing the client secret in the body of the request. 
   You can pass the secret in more secure ways by using a different [`config.client_auth`](/plugins/openid-connect/reference/#schema--config-client-auth) option.
 
-  For a complete example of authenticating with a username and password pair using Keycloak, see the tutorial for [configuring OpenID Connect with the password grant](/how-to/configure-oidc-with-password-grant/).
+  {% include_cached plugins/oidc/identity-server-intro.md %}
+  To use an external authorization server like Keycloak,
+  see [configuring OpenID Connect with the password grant](/how-to/configure-oidc-with-password-grant/).
   
   {% include_cached plugins/oidc/client-auth.md %}
 
 weight: 895
 
 requirements:
-  - A configured identity provider (IdP)
+  - "{% include_cached plugins/oidc/idp-requirement.md %}"
 
 config:
   issuer: ${issuer}
@@ -39,19 +41,24 @@ config:
     - password
   password_param_type:
     - header
+  principals:
+    enabled: true
+    directory: ${directory-name}
 
 variables:
   issuer:
     value: $ISSUER
     description: |
-      The issuer authentication URL for your IdP. 
-      For example, if you're using Keycloak as your IdP, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
+      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`.
   client-id:
     value: $CLIENT_ID
     description: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
   client-secret:
     value: $CLIENT_SECRET
     description: The client secret needed to connect to your IdP.
+  directory-name:
+    value: $DIRECTORY_NAME
+    description: The name of the {{ site.identity }} directory used for principals lookup.
 
 tools:
   - deck
diff --git a/app/_kong_plugins/openid-connect/examples/refresh-token.yaml b/app/_kong_plugins/openid-connect/examples/refresh-token.yaml
index faa9b8dff21..97f8f8b1da4 100644
--- a/app/_kong_plugins/openid-connect/examples/refresh-token.yaml
+++ b/app/_kong_plugins/openid-connect/examples/refresh-token.yaml
@@ -12,14 +12,16 @@ extended_description: |
   In this example, the OpenID Connect plugin will only accept refresh tokens sent in a header, 
   but you can also set the `refresh_token_param_type` parameter to `body`, `query`, or any combination of these values.
 
-  For a complete example of authenticating with a refresh token using Keycloak, see the tutorial for [configuring OpenID Connect with the refresh token grant](/how-to/configure-oidc-with-refresh-token/).
+  {% include_cached plugins/oidc/identity-server-intro.md %}
+  To use an external authorization server like Keycloak,
+  see [configuring OpenID Connect with the refresh token grant](/how-to/configure-oidc-with-refresh-token/).
   
   {% include_cached plugins/oidc/client-auth.md %}
 
 weight: 894
 
 requirements:
-  - A configured identity provider (IdP)
+  - "{% include_cached plugins/oidc/idp-requirement.md %}"
 
 config:
   issuer: ${issuer}
@@ -35,19 +37,24 @@ config:
     - header
   refresh_token_param_name: refresh_token
   upstream_refresh_token_header: refresh_token
+  principals:
+    enabled: true
+    directory: ${directory-name}
 
 variables:
   issuer:
     value: $ISSUER
     description: |
-      The issuer authentication URL for your IdP. 
-      For example, if you're using Keycloak as your IdP, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
+      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`.
   client-id:
     value: $CLIENT_ID
     description: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
   client-secret:
     value: $CLIENT_SECRET
     description: The client secret needed to connect to your IdP.
+  directory-name:
+    value: $DIRECTORY_NAME
+    description: The name of the {{ site.identity }} directory used for principals lookup.
 
 tools:
   - deck
diff --git a/app/_kong_plugins/openid-connect/examples/session-auth.yaml b/app/_kong_plugins/openid-connect/examples/session-auth.yaml
index 8328dc46005..b5ac4982b41 100644
--- a/app/_kong_plugins/openid-connect/examples/session-auth.yaml
+++ b/app/_kong_plugins/openid-connect/examples/session-auth.yaml
@@ -8,14 +8,16 @@ extended_description: |
 
   {% include_cached plugins/oidc/diagrams/session.md %}
 
-  For a complete example of retrieving, storing, and using session cookies for authentication with Keycloak, see the tutorial for [configuring OpenID Connect with session authentication](/how-to/configure-oidc-with-session-auth/).
+  {% include_cached plugins/oidc/identity-server-intro.md %}
+  To use an external authorization server like Keycloak,
+  see [configuring OpenID Connect with session authentication](/how-to/configure-oidc-with-session-auth/).
   
   {% include_cached plugins/oidc/client-auth.md %}
 
 weight: 893
 
 requirements:
-  - A configured identity provider (IdP)
+  - "{% include_cached plugins/oidc/idp-requirement.md %}"
 
 config:
   issuer: ${issuer}
@@ -27,19 +29,24 @@ config:
     - client_secret_post
   auth_methods:
     - session
+  principals:
+    enabled: true
+    directory: ${directory-name}
 
 variables:
   issuer:
     value: $ISSUER
     description: |
-      The issuer authentication URL for your IdP. 
-      For example, if you're using Keycloak as your IdP, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
+      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`.
   client-id:
     value: $CLIENT_ID
     description: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
   client-secret:
     value: $CLIENT_SECRET
     description: The client secret needed to connect to your IdP.
+  directory-name:
+    value: $DIRECTORY_NAME
+    description: The name of the {{ site.identity }} directory used for principals lookup.
 
 tools:
   - deck
diff --git a/app/_kong_plugins/openid-connect/examples/user-info-auth.yaml b/app/_kong_plugins/openid-connect/examples/user-info-auth.yaml
index 59dc520ca23..04f16ab6899 100644
--- a/app/_kong_plugins/openid-connect/examples/user-info-auth.yaml
+++ b/app/_kong_plugins/openid-connect/examples/user-info-auth.yaml
@@ -12,14 +12,16 @@ extended_description: |
   In this example, the OpenID Connect plugin will only accept bearer tokens sent in a header, 
   but you can also set the `bearer_token_param_type` parameter to `body`, `query`, or any combination of these values.
 
-  For a complete example of authenticating with a token retrieved through Keycloak's user info endpoint, see the tutorial for [configuring OpenID Connect with user info](/how-to/configure-oidc-with-user-info-auth/).
+  {% include_cached plugins/oidc/identity-server-intro.md %}
+  To use an external authorization server like Keycloak,
+  see [configuring OpenID Connect with user info](/how-to/configure-oidc-with-user-info-auth/).
   
   {% include_cached plugins/oidc/client-auth.md %}
 
 weight: 892
 
 requirements:
-  - A configured identity provider (IdP)
+  - "{% include_cached plugins/oidc/idp-requirement.md %}"
 
 config:
   issuer: ${issuer}
@@ -33,19 +35,24 @@ config:
     - userinfo
   bearer_token_param_type:
     - header
+  principals:
+    enabled: true
+    directory: ${directory-name}
 
 variables:
   issuer:
     value: $ISSUER
     description: |
-      The issuer authentication URL for your IdP. 
-      For example, if you're using Keycloak as your IdP, the issuer URL looks like this: `http://localhost:8080/realms/example-realm`
+      The issuer authentication URL for your IdP. As this example uses Kong Identity as the IdP, the issuer URL should look like `https://xxx.<region>.identity.konghq.tech/auth`.
   client-id:
     value: $CLIENT_ID
     description: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
   client-secret:
     value: $CLIENT_SECRET
     description: The client secret needed to connect to your IdP.
+  directory-name:
+    value: $DIRECTORY_NAME
+    description: The name of the {{ site.identity }} directory used for principals lookup.
 
 
 tools:

From f3b836369306c85277ac4f2375f4bbf1ec7da0c5 Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Wed, 24 Jun 2026 19:37:58 +0200
Subject: [PATCH 05/13] feat(identity): create server and principal

---
 .../authenticate-principals-with-oidc.md      | 36 ++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/app/_how-tos/gateway/authenticate-principals-with-oidc.md b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
index 306acbc55d1..5c4eca677b2 100644
--- a/app/_how-tos/gateway/authenticate-principals-with-oidc.md
+++ b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
@@ -16,7 +16,6 @@ products:
 plugins:
   - key-auth
 works_on:
-    - on-prem
     - konnect
 
 min_version:
@@ -58,3 +57,38 @@ cleanup:
       include_content: cleanup/products/gateway
       icon_url: /assets/icons/gateway.svg
 ---
+
+## Create an auth server in {{site.identity}}
+
+Before you can configure the OpenID Connect plugin, you must first create an auth server in {{site.identity}}. We recommend creating different auth servers for different environments or subsidiaries. The auth server name is unique per each organization and each {{site.konnect_short_name}} region.
+
+Create an auth server using the [`/v1/auth-servers` endpoint](/api/konnect/kong-identity/v1/#/operations/createAuthServer):
+
+<!--vale off-->
+{% konnect_api_request %}
+url: /v1/auth-servers
+status_code: 201
+method: POST
+headers:
+  - 'Content-Type: application/json'
+body:
+  name: "example-auth-server"
+  description: "Example auth server"
+  audience: "orders-api"
+extract_body:
+  - name: 'id'
+    variable: AUTH_SERVER_ID
+  - name: 'issuer'
+    variable: ISSUER_URL
+capture:
+  - variable: AUTH_SERVER_ID
+    jq: ".id"
+  - variable: ISSUER_URL
+    jq: ".issuer"
+{% endkonnect_api_request %}
+<!--vale on-->
+
+## Create a Principal
+
+{% include /how-tos/steps/principal.md %}
+

From ab9417624a25ab22666a86f8482c1ba89df5448f Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Wed, 24 Jun 2026 21:48:25 +0200
Subject: [PATCH 06/13] finish draft

---
 .../authenticate-principals-with-oidc.md      | 148 +++++++++++++++++-
 1 file changed, 146 insertions(+), 2 deletions(-)

diff --git a/app/_how-tos/gateway/authenticate-principals-with-oidc.md b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
index 5c4eca677b2..faa03fd4521 100644
--- a/app/_how-tos/gateway/authenticate-principals-with-oidc.md
+++ b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
@@ -1,5 +1,5 @@
 ---
-title: Authenticate Principals with the OpenID Connect plugin
+title: Authenticate principals with the OpenID Connect plugin
 permalink: /how-to/authenticate-principals-with-oidc/
 content_type: how_to
 breadcrumbs:
@@ -88,7 +88,151 @@ capture:
 {% endkonnect_api_request %}
 <!--vale on-->
 
-## Create a Principal
+## Create a client
+
+The client is the machine-to-machine credential that the OpenID Connect plugin uses to authenticate. {{site.konnect_short_name}} autogenerates the client ID and secret.
+
+Create a client using the [`/v1/auth-servers/$AUTH_SERVER_ID/clients` endpoint](/api/konnect/kong-identity/v1/#/operations/createAuthServerClient):
+
+<!--vale off-->
+{% konnect_api_request %}
+url: /v1/auth-servers/$AUTH_SERVER_ID/clients
+status_code: 201
+method: POST
+headers:
+  - 'Content-Type: application/json'
+  - 'Authorization: Bearer $KONNECT_TOKEN'
+body:
+  name: "example-client"
+  allow_all_scopes: true
+  allow_scopes: []
+  access_token_duration: 300
+  grant_types:
+    - client_credentials
+  response_types:
+    - token
+  redirect_uris: []
+  login_uri: ""
+extract_body:
+  - name: 'client_secret'
+    variable: CLIENT_SECRET
+  - name: 'id'
+    variable: CLIENT_ID
+capture:
+  - variable: CLIENT_ID
+    jq: ".id"
+  - variable: CLIENT_SECRET
+    jq: ".client_secret"
+{% endkonnect_api_request %}
+<!--vale on-->
+
+## Create a principal
 
 {% include /how-tos/steps/principal.md %}
 
+## Link the auth server client to the principal
+
+Link the {{site.identity}} auth server client to the principal so that {{site.identity}} can map the OAuth tokens it issues to this principal. Because {{site.identity}} issues the tokens, you reference the auth server and client you created earlier instead of an external issuer and claim.
+
+Add the identity using the `/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/identities` endpoint:
+
+<!--vale off-->
+{% konnect_api_request %}
+url: /v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/identities
+status_code: 201
+method: POST
+headers:
+  - 'Content-Type: application/json'
+  - 'Authorization: Bearer $KONNECT_TOKEN'
+body:
+  type: auth_server_client
+  auth_server_id: $AUTH_SERVER_ID
+  client_id: $CLIENT_ID
+{% endkonnect_api_request %}
+<!--vale on-->
+
+## Get the directory name
+
+To configure the OpenID Connect plugin, you need the name of the directory you created. Store it as `DECK_DIRECTORY_NAME` so decK can read it during sync:
+
+{% include /how-tos/steps/get-directory-name.md %}
+
+## Generate a salt token
+
+{% include how-tos/steps/deck-salt-token.md %}
+
+## Configure the OpenID Connect plugin
+
+Export the variables to decK:
+
+```bash
+export DECK_ISSUER_URL=$ISSUER_URL
+export DECK_CLIENT_ID=$CLIENT_ID
+export DECK_CLIENT_SECRET=$CLIENT_SECRET
+```
+
+Configure the [OpenID Connect plugin](/plugins/openid-connect/) to use {{site.identity}} as the identity provider and look up principals in your directory. Setting `principals.enabled` to `true` maps the authenticated token to a principal in the directory. This example applies the plugin to the `example-service` you created in the prerequisites.
+
+{% entity_examples %}
+entities:
+  plugins:
+    - name: openid-connect
+      service: example-service
+      config:
+        issuer: ${issuer}
+        client_id:
+        - ${client-id}
+        client_secret:
+        - ${client-secret}
+        client_auth:
+        - client_secret_post
+        auth_methods:
+        - client_credentials
+        client_credentials_param_type:
+        - header
+        principals:
+          enabled: true
+          directory: ${directory_name}
+        cache_tokens_salt: ${salt-token}
+variables:
+  issuer:
+    value: $ISSUER_URL
+  client-id:
+    value: $CLIENT_ID
+  client-secret:
+    value: $CLIENT_SECRET
+  directory_name:
+    value: $DIRECTORY_NAME
+  salt-token:
+    value: $TOKEN_SALT
+formats:
+  - deck
+{% endentity_examples %}
+
+## Validate
+
+Base64-encode the client ID and secret for the `Authorization` header:
+
+<!--vale off-->
+```bash
+export CLIENT_CREDENTIALS=$(printf '%s' "$CLIENT_ID:$CLIENT_SECRET" | base64)
+```
+<!--vale on-->
+
+Send a request to the protected Gateway Service with the client credentials. The OpenID Connect plugin exchanges them for a token with {{site.identity}}, validates it, and maps it to your principal. The request should succeed with a `200` status code:
+
+{% validation request-check %}
+url: '/anything'
+display_headers: true
+status_code: 200
+headers:
+  - 'Authorization: Basic $CLIENT_CREDENTIALS'
+{% endvalidation %}
+
+Send a request without credentials. {{site.identity}} rejects it because the request can't be mapped to a principal:
+
+{% validation unauthorized-check %}
+url: /anything
+{% endvalidation %}
+
+

From 4a519496dab5ea360d9499b0c6b9e5493f5a61fe Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Wed, 24 Jun 2026 22:18:24 +0200
Subject: [PATCH 07/13] feat(identity): finish guide and test

---
 .../authenticate-principals-with-oidc.md      | 22 +++++++++----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/app/_how-tos/gateway/authenticate-principals-with-oidc.md b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
index faa03fd4521..43357a3985b 100644
--- a/app/_how-tos/gateway/authenticate-principals-with-oidc.md
+++ b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
@@ -1,5 +1,5 @@
 ---
-title: Authenticate principals with the OpenID Connect plugin
+title: Authenticate OAuth clients with a Kong Identity authorization server
 permalink: /how-to/authenticate-principals-with-oidc/
 content_type: how_to
 breadcrumbs:
@@ -8,13 +8,13 @@ related_resources:
   - text: Authentication
     url: /gateway/authentication/
 
-description: Use the OpenID Connect plugin to allow Principals to authenticate.
+description: Use the OpenID Connect plugin to map authenticated OAuth clients to Kong Identity principals.
 products:
     - gateway
     - identity
 
 plugins:
-  - key-auth
+  - openid-connect
 works_on:
     - konnect
 
@@ -33,9 +33,9 @@ tools:
     - deck
 
 tldr:
-  q: How do I authenticate Principals with OpenID Connect?
+  q: How do I map OAuth clients to  principals with OpenID Connect?
   a: |
-    SUMMARY HERE
+    Create a {{site.identity}} authorization server and OAuth client, create a principal, and link the client to the principal with an `auth_server_client` identity. Configure the OpenID Connect plugin with `principals.enabled` set to `true` to use {{site.identity}} as your IdP , then send a request with the client credentials in an `Authorization: Basic` header to a protected Gateway Service.
 
 prereqs:
   entities:
@@ -58,11 +58,11 @@ cleanup:
       icon_url: /assets/icons/gateway.svg
 ---
 
-## Create an auth server in {{site.identity}}
+## Create an authorization server in {{site.identity}}
 
-Before you can configure the OpenID Connect plugin, you must first create an auth server in {{site.identity}}. We recommend creating different auth servers for different environments or subsidiaries. The auth server name is unique per each organization and each {{site.konnect_short_name}} region.
+An authorization server in {{site.identity}} issues the OAuth tokens that clients present to authenticate to your service.
 
-Create an auth server using the [`/v1/auth-servers` endpoint](/api/konnect/kong-identity/v1/#/operations/createAuthServer):
+Create an authorization server using the [`/v1/auth-servers` endpoint](/api/konnect/kong-identity/v1/#/operations/createAuthServer):
 
 <!--vale off-->
 {% konnect_api_request %}
@@ -90,7 +90,7 @@ capture:
 
 ## Create a client
 
-The client is the machine-to-machine credential that the OpenID Connect plugin uses to authenticate. {{site.konnect_short_name}} autogenerates the client ID and secret.
+The client is the credential that the OpenID Connect plugin uses to authenticate. {{site.konnect_short_name}} autogenerates the client ID and secret.
 
 Create a client using the [`/v1/auth-servers/$AUTH_SERVER_ID/clients` endpoint](/api/konnect/kong-identity/v1/#/operations/createAuthServerClient):
 
@@ -130,9 +130,9 @@ capture:
 
 {% include /how-tos/steps/principal.md %}
 
-## Link the auth server client to the principal
+## Link the client to the principal
 
-Link the {{site.identity}} auth server client to the principal so that {{site.identity}} can map the OAuth tokens it issues to this principal. Because {{site.identity}} issues the tokens, you reference the auth server and client you created earlier instead of an external issuer and claim.
+Link the {{site.identity}} authorization server client to the principal so that {{site.identity}} can map the OAuth tokens it issues to this principal. Because {{site.identity}} issues the tokens, you reference the authorization server and client you created earlier instead of an external issuer and claim.
 
 Add the identity using the `/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/identities` endpoint:
 

From 904f579ed8f467c8351be9ed4fc65d5aaf066635 Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Thu, 25 Jun 2026 18:59:56 +0200
Subject: [PATCH 08/13] Apply suggestion from @juliamrch

---
 app/_how-tos/gateway/authenticate-principals-with-oidc.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/app/_how-tos/gateway/authenticate-principals-with-oidc.md b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
index 43357a3985b..769cd757c61 100644
--- a/app/_how-tos/gateway/authenticate-principals-with-oidc.md
+++ b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
@@ -17,6 +17,8 @@ plugins:
   - openid-connect
 works_on:
     - konnect
+    - on-prem
+    
 
 min_version:
   gateway: '3.15'

From 6d8a5889e31d1e7826094f590298aab15088644d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 25 Jun 2026 17:00:48 +0000
Subject: [PATCH 09/13] fix: clean TLDR whitespace in OIDC how-to

---
 app/_how-tos/gateway/authenticate-principals-with-oidc.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/app/_how-tos/gateway/authenticate-principals-with-oidc.md b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
index 769cd757c61..76221dd10b9 100644
--- a/app/_how-tos/gateway/authenticate-principals-with-oidc.md
+++ b/app/_how-tos/gateway/authenticate-principals-with-oidc.md
@@ -35,9 +35,9 @@ tools:
     - deck
 
 tldr:
-  q: How do I map OAuth clients to  principals with OpenID Connect?
+  q: How do I map OAuth clients to principals with OpenID Connect?
   a: |
-    Create a {{site.identity}} authorization server and OAuth client, create a principal, and link the client to the principal with an `auth_server_client` identity. Configure the OpenID Connect plugin with `principals.enabled` set to `true` to use {{site.identity}} as your IdP , then send a request with the client credentials in an `Authorization: Basic` header to a protected Gateway Service.
+    Create a {{site.identity}} authorization server and OAuth client, create a principal, and link the client to the principal with an `auth_server_client` identity. Configure the OpenID Connect plugin with `principals.enabled` set to `true` to use {{site.identity}} as your IdP, then send a request with the client credentials in an `Authorization: Basic` header to a protected Gateway Service.
 
 prereqs:
   entities:

From 90b0f15559925c8396dbf7b02ee8937cdde9d8b3 Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Thu, 25 Jun 2026 19:09:25 +0200
Subject: [PATCH 10/13] rename file

---
 ...oidc.md => authenticate-oauth-clients-with-kong-identity.md} | 2 +-
 app/_indices/identity.yaml                                      | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)
 rename app/_how-tos/gateway/{authenticate-principals-with-oidc.md => authenticate-oauth-clients-with-kong-identity.md} (99%)

diff --git a/app/_how-tos/gateway/authenticate-principals-with-oidc.md b/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
similarity index 99%
rename from app/_how-tos/gateway/authenticate-principals-with-oidc.md
rename to app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
index 76221dd10b9..3b07219e57a 100644
--- a/app/_how-tos/gateway/authenticate-principals-with-oidc.md
+++ b/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
@@ -1,6 +1,6 @@
 ---
 title: Authenticate OAuth clients with a Kong Identity authorization server
-permalink: /how-to/authenticate-principals-with-oidc/
+permalink: /how-to/authenticate-oauth-clients-with-kong-identity/
 content_type: how_to
 breadcrumbs:
   - /identity/
diff --git a/app/_indices/identity.yaml b/app/_indices/identity.yaml
index 991d99c4242..a59cb90d1b1 100644
--- a/app/_indices/identity.yaml
+++ b/app/_indices/identity.yaml
@@ -14,3 +14,4 @@ sections:
       - path: /how-to/kong-identity-dcr/
       - path: /how-to/authenticate-principals-with-key-auth/
       - path: /how-to/authenticate-principals-with-basic-authentication/
+      - path: /how-to/authenticate-oauth-clients-with-kong-identity/

From 4a8ba3677f096d2a7f59701944aceebf7952fc79 Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Fri, 26 Jun 2026 11:53:04 +0200
Subject: [PATCH 11/13] Apply suggestions from code review

Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Co-authored-by: Julia <101819212+juliamrch@users.noreply.github.com>
---
 .../authenticate-oauth-clients-with-kong-identity.md      | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md b/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
index 3b07219e57a..1e1796b5381 100644
--- a/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
+++ b/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
@@ -7,6 +7,10 @@ breadcrumbs:
 related_resources:
   - text: Authentication
     url: /gateway/authentication/
+  - text: "{{site.identity}}"
+    url: /identity/
+  - text: "{{site.identity}} principals and directories"
+    url: /identity/principals
 
 description: Use the OpenID Connect plugin to map authenticated OAuth clients to Kong Identity principals.
 products:
@@ -92,7 +96,7 @@ capture:
 
 ## Create a client
 
-The client is the credential that the OpenID Connect plugin uses to authenticate. {{site.konnect_short_name}} autogenerates the client ID and secret.
+The client is the credential that the OpenID Connect plugin uses to authenticate. {{site.identity}} autogenerates the client ID and secret.
 
 Create a client using the [`/v1/auth-servers/$AUTH_SERVER_ID/clients` endpoint](/api/konnect/kong-identity/v1/#/operations/createAuthServerClient):
 
@@ -173,7 +177,7 @@ export DECK_CLIENT_ID=$CLIENT_ID
 export DECK_CLIENT_SECRET=$CLIENT_SECRET
 ```
 
-Configure the [OpenID Connect plugin](/plugins/openid-connect/) to use {{site.identity}} as the identity provider and look up principals in your directory. Setting `principals.enabled` to `true` maps the authenticated token to a principal in the directory. This example applies the plugin to the `example-service` you created in the prerequisites.
+Configure the [OpenID Connect plugin](/plugins/openid-connect/) to use {{site.identity}} as the identity provider and map the client credentials. Setting `principals.enabled` to `true` maps the authenticated token to a directory. This example applies the plugin to the `example-service` you created in the prerequisites.
 
 {% entity_examples %}
 entities:

From fb00c9d26d5c4ac8155f6c1f366c62cc8c88a47e Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Fri, 26 Jun 2026 11:59:53 +0200
Subject: [PATCH 12/13] Apply suggestion from @juliamrch

---
 .../gateway/authenticate-oauth-clients-with-kong-identity.md    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md b/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
index 1e1796b5381..89e6ae9eff2 100644
--- a/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
+++ b/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
@@ -10,7 +10,7 @@ related_resources:
   - text: "{{site.identity}}"
     url: /identity/
   - text: "{{site.identity}} principals and directories"
-    url: /identity/principals
+    url: /identity/principals/
 
 description: Use the OpenID Connect plugin to map authenticated OAuth clients to Kong Identity principals.
 products:

From e7059198286a9e99c420d18b6892bda327d69e26 Mon Sep 17 00:00:00 2001
From: Julia <101819212+juliamrch@users.noreply.github.com>
Date: Mon, 29 Jun 2026 12:56:43 +0200
Subject: [PATCH 13/13] Update
 app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md

Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
---
 .../gateway/authenticate-oauth-clients-with-kong-identity.md     | 1 -
 1 file changed, 1 deletion(-)

diff --git a/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md b/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
index 89e6ae9eff2..ce885e9a38a 100644
--- a/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
+++ b/app/_how-tos/gateway/authenticate-oauth-clients-with-kong-identity.md
@@ -21,7 +21,6 @@ plugins:
   - openid-connect
 works_on:
     - konnect
-    - on-prem
     
 
 min_version: