docs: add OIDC/OAuth2 concepts overview guide#736
Conversation
Closes kgateway-dev#735 Signed-off-by: AtharvaKathe18 <atharvakathe567@gmail.com>
| @@ -16,6 +16,7 @@ For example, you might use HTTPS listeners for external client connections, enfo | |||
| {{< card link="cors" title="CORS" >}} | |||
There was a problem hiding this comment.
Cards are not auto-generated, so these can be removed. Probably causing a conflict preventing merging.
| - An unauthenticated browser request for a protected route is intercepted by kgateway's OAuth2 policy (configured via a `GatewayExtension` and applied with a `TrafficPolicy`). | ||
|
|
||
| 2. Redirect to IdP authorization endpoint | ||
| - kgateway constructs an authorization request (issuer / authorization endpoint, client_id, redirect_uri, scope, state, and optionally PKCE) and redirects the user to the IdP's login page. |
There was a problem hiding this comment.
PKCE seems to be highlighted in this topic, but I don't think we want to give it more than a passing mention, if that. The underlying Envoy OAuth2 filter uses a confidential client with a client secret, not PKCE. Since it's not officially supported, I don't think it should be featured.
| Implementation tips | ||
| - Use provider discovery (`issuerURI`) when possible to avoid copying endpoints manually. Verify JWKS reachability from the cluster. | ||
| - Prefer short cookie lifetimes and secure cookie attributes. Configure `denyRedirect` for AJAX endpoints to avoid unexpected HTML redirects. | ||
| - Map only needed claims to headers (`claimsToHeaders`) and avoid forwarding sensitive claims unless the backend requires them. |
There was a problem hiding this comment.
claimsToHeaders is a JWT-provider field, not an OAuth2Provider field
|
|
||
| ## 6. Related guides | ||
|
|
||
| - JWT validation: ../jwt-validation |
There was a problem hiding this comment.
These links are in plain text rather than in markdown or using the link-hextra shortcode.
| @@ -0,0 +1,86 @@ | |||
| # OIDC / OAuth2 concepts for kgateway | |||
There was a problem hiding this comment.
Asset files should not start with H1 since they are reused in the other wrapper topics that do have H1s.
| ## 3. JWT vs OIDC | ||
|
|
||
| | Aspect | JWT validation | OIDC (Authorization Code / session) | | ||
| |---|---:|---| |
There was a problem hiding this comment.
Is the colon to adjust alignment?
|
|
||
| | Aspect | JWT validation | OIDC (Authorization Code / session) | | ||
| |---|---:|---| | ||
| | Primary use case | API-to-API authentication (bearer tokens) | Browser-based user authentication and delegated access |
There was a problem hiding this comment.
Each table row from here down is missing a closing pipe.
| - JWT validation: ../jwt-validation | ||
| - Keycloak integration (provider-specific): ../oauth2/keycloak | ||
|
|
||
| --- |
There was a problem hiding this comment.
Horizontal rule should be removed.
| @@ -0,0 +1,10 @@ | |||
| --- | |||
| title: OIDC / OAuth2 Concepts | |||
| weight: 30 | |||
There was a problem hiding this comment.
Add a description in the metadata.
| @@ -0,0 +1,6 @@ | |||
| --- | |||
| title: OIDC / OAuth2 Concepts | |||
There was a problem hiding this comment.
Add a description in the metadata.
2 participants
Description
This PR adds an OIDC/OAuth2 concepts overview guide to the security documentation.
Motivation:
While kgateway provides support for OAuth2/OIDC and includes provider-specific guides (such as Keycloak) and a JWT validation guide, there is no central explanation of how authentication flows work in kgateway or how these approaches relate to each other.
What changed:
Closes #735
Change Type
/kind documentation
Changelog
Additional Notes
This guide focuses on conceptual understanding and complements existing provider-specific guides without duplicating them.