docs: add comprehensive OAuth2/OIDC integration guide by ApurveKaranwal · Pull Request #866 · kgateway-dev/kgateway.dev

ApurveKaranwal · 2026-06-22T18:56:42Z

Description

This PR introduces a brand-new, comprehensive documentation guide for configuring and utilizing native OAuth2 and OpenID Connect (OIDC) authentication in kgateway.

Motivation

Developers need clear instruction and architecture guidance to delegate authentication to external Identity Providers (IdPs) like Keycloak, Auth0, or Okta. Previously, security documentation lacked a detailed guide for OIDC configurations, cookie customization, claim propagation, and endpoint exemptions.

What changed

Created a shared content page at oauth2-auth.md detailing:
- Conceptual overview of kgateway acting as the OAuth2 client.
- A Mermaid sequence diagram illustrating the redirection, token exchange, and upstream forwarding.
- Setup steps: creating client secrets, configuring the GatewayExtension (spec.oauth2), and enforcing policies via TrafficPolicy.
- Advanced configurations: forwarding access tokens (forwardAccessToken), custom cookie naming/domains (cookies), extracting JWT claims to upstream headers (jwt.idToken.claimsToHeaders), and preventing redirects for API/AJAX requests (denyRedirect).
Created versioned content pages importing the shared guide via Hextra shortcodes for main, latest, and 2.2.x.

Related issues

Closes Add OIDC / OAuth2 Concepts Overview Guide #735 (OIDC / OAuth2 Concepts Overview Guide)
Closes [Documentation] Guide for Extracting JWT Claims to Custom Request Headers #739 (Extracting JWT Claims to Custom Request Headers)
Closes docs: add OAuth2/OIDC integration guides for Keycloak, Auth0, and other IdPs #732 (docs: add OAuth2/OIDC integration guides for Keycloak, Auth0, and other IdPs)
Addresses Add JWT Validation Guide to Security Documentation #730 (Add JWT Validation Guide to Security Documentation)
Addresses Security docs for integrating kgateway with OIDC and JWT IdPs #725 (Security docs for integrating kgateway with OIDC and JWT IdPs)

Change Type

/kind documentation

Changelog

docs: add comprehensive OAuth2/OIDC integration guide with advanced configurations (claims extraction, cookie customizations, and redirect prevention)

Covers issuer configuration, traffic policy integration, JWT claims to headers mapping, and denial of redirects for API/AJAX requests. Closes kgateway-dev#735, Closes kgateway-dev#739, Addresses kgateway-dev#730 Signed-off-by: ApurveKaranwal <apurvekaranwal282@gmail.com>

ApurveKaranwal · 2026-06-25T16:28:20Z

@kristin-kronstain-brown ma'am, @artberger sir, please review my PR and do let me know if i need to change anything.

kristin-kronstain-brown

This PR is great for filling in some holes that we have and closes some issues. Just a few minor issues to still work through.

kristin-kronstain-brown · 2026-06-26T13:05:15Z

+
+### 2. Create a GatewayExtension for OAuth2
+
+Create a `GatewayExtension` specifying your OIDC provider settings in the `spec.oauth2` block. The following example uses Keycloak as the Identity Provider:


This section references a keycloak Service in keycloak-system, a Gateway named http, and an HTTPRoute — none of which the guide creates, and the prereq snippet won't deploy an IdP. At minimum add a prerequisite line like: "This guide requires an OIDC IdP, such as Keycloak, deployed in-cluster and reachable, and an HTTPRoute for your app."

kristin-kronstain-brown · 2026-06-26T13:07:30Z

+      name: keycloak
+      namespace: keycloak-system
+      port: 8080
+    issuerURI: https://keycloak.example.com/realms/master


issuerURI vs backendRef mismatch will confuse readers. issuerURI: https://keycloak.example.com/... (public host) but backendRef points to in-cluster keycloak.keycloak-system:8080. That's valid (backendRef = network path, issuerURI = issuer identity), but it reads like a contradiction. One sentence explaining the distinction would help.

kristin-kronstain-brown · 2026-06-26T13:08:06Z

+sequenceDiagram
+    autonumber
+    participant Client as User Browser
+    participant AGW as Kgateway Proxy


Should this be Gateway rather than AGW?

kristin-kronstain-brown · 2026-06-26T13:09:07Z

+    autonumber
+    participant Client as User Browser
+    participant AGW as Kgateway Proxy
+    participant IdP as Identity Provider (e.g. Keycloak)


Avoid e.g.. It's part of our style guidelines to write out something like "for example" or "such as" instead. It's in here a few more times.

Signed-off-by: ApurveKaranwal <apurvekaranwal282@gmail.com>

ApurveKaranwal · 2026-06-26T14:54:14Z

Thank you for the review, @kristin-kronstain-brown maam!

I have addressed all the feedback and pushed the updates:

Added Prerequisites: Added a line under Before you begin clarifying that the guide assumes you have an OIDC IdP (such as Keycloak) deployed in-cluster and reachable, as well as an HTTPRoute configured for your application.
Clarified issuerURI vs backendRef: Updated the parameter table to explicitly explain the distinction between the internal network path (backendRef) and the public issuer identity (issuerURI).
Sequence Diagram: Updated the sequence diagram to use Gateway instead of AGW as the participant name.
Style Guidelines (Abbreviations): Removed all occurrences of e.g. and replaced them with such as or for example per the style guidelines.

Let me know if there's anything else needed!

ApurveKaranwal · 2026-06-30T16:34:31Z

@npolshakova ma'am, please check my PR and tell me if i need to fix anything.

Signed-off-by: Kristin Brown <kristin.brown@solo.io> # Conflicts: # assets/kgw-docs/pages/security/oauth2-auth.md

Align the OAuth2/OIDC guide with the assets/docs -> assets/kgw-docs rename from main. Updates the shared page include path in the main, latest, and 2.2.x versioned pages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Kristin Brown <kristin.brown@solo.io>

- Lowercase 'kgateway proxy' in the mermaid diagram participant label to match product style. - Expand the four advanced-config examples into complete, applyable GatewayExtension manifests (consistent with step 2) so they are copy-paste runnable and can be exercised by doc tests. Each re-applies the same-named resource to layer on the advanced field. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Kristin Brown <kristin.brown@solo.io>

kristin-kronstain-brown · 2026-07-07T14:08:27Z

Thanks @ApurveKaranwal! I pushed a few updates directly to the branch to get it merge-ready:

Merged in main — the branch was based on an older main, and assets/docs/ has since been renamed to assets/kgw-docs/. Moved the shared page to assets/kgw-docs/pages/security/oauth2-auth.md and updated all reuse paths (shared page + the 3 versioned pages) to the kgw-docs/ prefix so the includes resolve.
Verified the API fields against the current CRDs — everything checks out, including the client-secret Secret key (confirmed in the kgateway source).
Advanced-config examples — expanded them into complete, applyable GatewayExtension manifests (matching the step 2 style) so they're copy-paste runnable.
Style nit — lowercased kgateway proxy in the mermaid diagram.

Everything else is your work — nice, thorough guide. 🙌

ApurveKaranwal · 2026-07-07T16:26:14Z

thank you so much @kristin-kronstain-brown ma'am.

* docs: add curl examples to OAuth2/OIDC guide Signed-off-by: MIKE-4-prog <uzukwuekene.michael@gmail.com> * docs: add OAuth2/OIDC authentication flow screenshots - Add 4 screenshots for OAuth2/OIDC authentication flow verification - Include dark mode support with reuse-image-dark shortcode - Use correct inline shortcode syntax matching ArgoCD pattern - Remove unsupported caption parameter to fix image rendering Signed-off-by: MIKE-4-prog <uzukwuekene.michael@gmail.com> * docs: address Nina's feedback for OAuth2/OIDC guide - Add screenshots with dark mode support - Replace curl examples with OAuth2 browser flow - Add Keycloak setup section (Helm and YAML) - Add client secret note and API reference link - Fix hostname consistency and expected outputs Signed-off-by: MIKE-4-prog <uzukwuekene.michael@gmail.com> --------- Signed-off-by: MIKE-4-prog <uzukwuekene.michael@gmail.com>

Mike-4-prog mentioned this pull request Jun 25, 2026

adds curl examples to the OAuth2/OIDC integration guide (#866) #872

Merged

kristin-kronstain-brown requested changes Jun 26, 2026

View reviewed changes

docs: address review feedback on OAuth2/OIDC guide

f84927e

Signed-off-by: ApurveKaranwal <apurvekaranwal282@gmail.com>

ApurveKaranwal requested a review from kristin-kronstain-brown June 30, 2026 16:31

kristin-kronstain-brown and others added 3 commits July 7, 2026 09:46

Merge remote-tracking branch 'origin/main' into pr-866

bdeb563

Signed-off-by: Kristin Brown <kristin.brown@solo.io> # Conflicts: # assets/kgw-docs/pages/security/oauth2-auth.md

kristin-kronstain-brown approved these changes Jul 7, 2026

View reviewed changes

kristin-kronstain-brown merged commit e14e1d4 into kgateway-dev:main Jul 7, 2026
2 checks passed

Navigation Menu

Uh oh!

docs: add comprehensive OAuth2/OIDC integration guide - #866

docs: add comprehensive OAuth2/OIDC integration guide#866
kristin-kronstain-brown merged 5 commits into
kgateway-dev:mainfrom
ApurveKaranwal:docs/oauth2-oidc-guide

ApurveKaranwal commented Jun 22, 2026 •

edited

Loading

Uh oh!

ApurveKaranwal commented Jun 25, 2026

Uh oh!

kristin-kronstain-brown left a comment

Uh oh!

kristin-kronstain-brown Jun 26, 2026

Uh oh!

kristin-kronstain-brown Jun 26, 2026

Uh oh!

kristin-kronstain-brown Jun 26, 2026

Uh oh!

kristin-kronstain-brown Jun 26, 2026

Uh oh!

ApurveKaranwal commented Jun 26, 2026

Uh oh!

ApurveKaranwal commented Jun 30, 2026

Uh oh!

kristin-kronstain-brown commented Jul 7, 2026

Uh oh!

Uh oh!

ApurveKaranwal commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		### 2. Create a GatewayExtension for OAuth2

		Create a `GatewayExtension` specifying your OIDC provider settings in the `spec.oauth2` block. The following example uses Keycloak as the Identity Provider:

Uh oh!

Conversation

ApurveKaranwal commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

What changed

Related issues

Change Type

Changelog

Uh oh!

ApurveKaranwal commented Jun 25, 2026

Uh oh!

kristin-kronstain-brown left a comment

Choose a reason for hiding this comment

Uh oh!

kristin-kronstain-brown Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

kristin-kronstain-brown Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

kristin-kronstain-brown Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

kristin-kronstain-brown Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

ApurveKaranwal commented Jun 26, 2026

Uh oh!

ApurveKaranwal commented Jun 30, 2026

Uh oh!

kristin-kronstain-brown commented Jul 7, 2026

Uh oh!

Uh oh!

ApurveKaranwal commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ApurveKaranwal commented Jun 22, 2026 •

edited

Loading