docs: add OAuth2-Proxy-fronted OIDC option

[leemeo3]

Related issue(s)

closes #3040

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 updates the First-Party OIDC guide with an alternative topology where OAuth2-Proxy runs in front of heimdall.

The current guide keeps OAuth2-Proxy behind heimdall and lets heimdall validate the OAuth2-Proxy session through /oauth2/userinfo. That is convenient when heimdall owns the public entry point and browser redirects, but it means heimdall validates the OAuth2-Proxy session instead of the access token issued by the identity provider.

The added section documents the smaller alternative where OAuth2-Proxy is the public reverse proxy, forwards the access token to heimdall, and heimdall validates that token with the oauth2_introspection authenticator. I kept this scoped to the existing proxy-mode guide and treated the broader NGINX/decision-mode integration from #2207 as a separate follow-up.

Validation performed:

• git diff --check
• direct render of docs/content/guides/authn/oidc_first_party_auth.adoc with asciidoctor
• attempted full docs build with npm ci && hugo --minify -d ./public; npm ci passed, but the full local build is blocked because this environment lacks a Java Runtime required by existing asciidoctor-diagram pages

[dadrus]

Thank you very much for this update @leemeo3. Just out of interest. How much is your update related to #2207?

FYI: You can also run the docs locally by making use of the just run-docs command. Alternatively, simply execute the commands the command uses (see

heimdall/Justfile

Line 66 in f2c9a26

run-docs: build-docs-debug-image

). The docs are then rendered in a container, which includes everything required. Though, the project folder is mounted into it to allow working on docs and see the results instanly

[leemeo3]

Thanks for taking a look.

I see this as related to #2207, but not the same scope.

This PR stays within the first-party OIDC guide's proxy-mode setup and documents the smaller alternative where OAuth2-Proxy becomes the public reverse proxy and forwards the access token to heimdall. Heimdall still runs in proxy mode and can introspect that token directly, which addresses the session-state caveat from #3040.

#2207 looks broader to me: heimdall in decision mode behind another proxy such as NGINX auth_request / forwardAuth-style integrations, with OAuth2-Proxy participating in that flow. The token-forwarding idea is similar, but the operating mode and proxy responsibility are different.

So I would treat this PR as a proxy-mode companion note for #3040, and #2207 as a separate follow-up for the decision-mode variant. I can add a short cross-reference if that would make the distinction clearer in the guide.

Also noted on just run-docs; thanks. The docs build passed in CI after the workflow was approved, and I will use the containerized docs flow for further edits.

[dadrus]

Thanks for sharing your view on that.

Regarding your PR description: I don't mean to nitpick, but it doesn't follow the project's PR template.

I was actually a bit surprised by this, as the template is usually applied automatically when creating a PR via the GitHub UI. It might be that the tool you used bypassed that behavior.

In any case, could you please update the description to match the template? That would help keep things consistent.

[dadrus]

Additionally, as noted in the contributing guide, all commits must be signed. This document might help with configuring your account accordingly.

[dadrus]

Thank you for updating the PR description. The only missing thing are the signatures over your commits (as mentioned in my previous comment). Most probably you'll have to rewrite the history of your branch - so all commits are signed, and then force push the update to the branch.

[leemeo3]

Thanks for the reminder. I rewrote the branch history and force-pushed the signed commit. The current commit is 0787e45a, and GitHub now reports the commit signature as verified.

[dadrus]

Hi, sorry for the silence. I took a closer look at the update today and tried the configuration suggested in the guide.

I don’t think we can merge this as-is. The described setup does not work with the Keycloak configuration from the guide: heimdall fails when validating the token signing key obtained via JWKS, because the generated Keycloak certificates are not suitable for this use case without additional configuration.

The fix is not complicated, but it is also not documented here. So at the moment this guide would lead users to a setup that appears complete, but is not actually reproducible. Could you please update it so that the documented setup is reproducible end to end?

[leemeo3]

Thanks for trying it out and for the concrete failure report. I updated the branch in commit d17bf47f (GitHub reports the signature as verified).

What changed:

• added the missing Keycloak/OAuth2-Proxy-front details, including that port 9090 is now OAuth2-Proxy-owned in this topology;
• added OAUTH2_PROXY_SKIP_AUTH_ROUTES for the public routes so OAuth2-Proxy does not preempt heimdall's anonymous rule;
• kept oauth2_introspection as the primary option for token-state checks against Keycloak;
• documented the JWT/JWKS alternative explicitly, including Keycloak's default RS256, the local tutorial validate_jwk: false setting for generated Keycloak JWKS certificate material, and the production trust_anchors direction.

Local validation:

• git diff --check origin/main...codex/oidc-oauth2-proxy-front
• direct asciidoctor render of docs/content/guides/authn/oidc_first_party_auth.adoc

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