docs: add OIDC guide for OAuth2-Proxy and NGINX

[leemeo3]

Related issue(s)

#2207

Checklist

• I agree to follow this project's Code of Conduct.
• I have read, and I am following this repository's Contributing Guidelines.
• I have read the Security Policy.
• I have referenced an issue describing the bug/feature request.
• I have updated the documentation.

Description

This adds a new guide under guides/authn for an OpenID Connect setup with OAuth2-Proxy, NGINX, and heimdall decision mode.

The guide covers the related OAuth2-Proxy handoff pattern from #2207: OAuth2-Proxy owns the browser login and session cookie, NGINX stays in front of the upstream service, and heimdall makes the access-control decision through NGINX auth_request.

Per maintainer feedback, this is no longer placed in the NGINX proxy guide. The NGINX guide is back to its original scope, and the new content now lives next to the other OIDC-related guide.

Validation performed:

• git diff --check
• direct render of docs/content/guides/authn/oidc_oauth2_proxy_nginx_decision.adoc with asciidoctor
• direct render of docs/content/guides/proxies/nginx.adoc with asciidoctor
• just run-docs was not run locally because this environment does not have just or Docker installed

[dadrus]

@leemeo3: thank you for addressing the FR you referenced in the PR description. I fear however, that the NGINX guide is a wrong place to describe that setup. IMO, the best place would be a new guide document in same section where the other oidc related guides are located.

[leemeo3]

Thanks for the placement guidance. I moved the content out of the NGINX guide into a new OIDC/Authn guide and force-pushed the signed commit. The current commit is fd4d44a6, GitHub reports the signature as verified, and I marked the PR ready for review.

[dadrus]

Hi, sorry for the silence. I took a closer look at this PR today.

I’m not convinced this adds enough value as a standalone guide in its current form. Most of the content appears to be a recombination of the existing NGINX guide, the existing first-party OIDC guide, and the setup already described in #2207.

The NGINX part mostly repeats the existing auth_request / X-Forwarded-* integration, with the OAuth2-Proxy redirect added on top. The heimdall part repeats the existing generic authenticator pattern against OAuth2-Proxy’s /oauth2/userinfo endpoint. The rest mainly points readers back to the other guides.

What I would expect from a standalone guide is either a complete, reproducible end-to-end setup, or additional guidance that is not already covered elsewhere: the exact OAuth2-Proxy settings, the required Keycloak redirect/home URL changes, the relevant heimdall rules, and any important caveats specific to this topology.

As written, I think this is closer to a short note about how to combine existing guides than a new guide on its own.

[leemeo3]

Thanks, that makes sense. I reworked the guide in commit 4957865d (GitHub reports the signature as verified) so it is no longer just a recombination of the other pages.

What changed:

• added the exact Keycloak client URL changes for this topology;
• added the OAuth2-Proxy environment settings, including the session-cookie caveat;
• expanded the NGINX example into the actual auth_request plus OAuth2-Proxy redirect flow;
• added a decision-mode heimdall config and route rules, explicitly noting that decision-mode rules do not use forward_to;
• added topology-specific caveats, including redirect ownership, trusted_proxies, and when to use the OAuth2-Proxy-in-front pattern instead.

Local validation:

• git diff --check origin/main...codex/nginx-oauth2-proxy-decision
• direct asciidoctor render of docs/content/guides/authn/oidc_oauth2_proxy_nginx_decision.adoc

I still could not run just run-docs locally because this environment has neither just nor Docker installed.