git.iko.soy/typeable/oauth2-proxy
on master help sign in
docs: clarify ingress-nginx integration and remove Lua block example (#3202)

* docs: clarify ingress-nginx integration and remove Lua block example for oauth2-proxy This PR revises the integration guide for oauth2-proxy with ingress-nginx in Kubernetes: Recommends the minimal configuration: just auth-url and auth-signin annotations. Removes the Lua block example, as it did not work in practice despite following nginx documentation and extensive testing. Clearly states that the official ingress-nginx external auth example is the recommended approach for most users. Notes that advanced Lua/cookie handling is only needed for rare, advanced scenarios. Signed-off-by: Jan Larwig <jan@larwig.com> * doc: update 3 latest docs versions Signed-off-by: Jan Larwig <jan@larwig.com> --------- Signed-off-by: Jan Larwig <jan@larwig.com> Co-authored-by: Jan Larwig <jan@larwig.com>

commit31b275f5805ee1d6c62906a81274c21587e70a40 authorSchmitt Paul <100230730+paulsc54@users.noreply.github.com> dateTue 28 Oct 2025, 08:48 (1 year ago) parentea1dc3f
4 files changed+24−56
compare with master
unifiedsplit
docs/docs/configuration/integration.md+6−14 docs/versioned_docs/version-7.10.x/configuration/integration.md+6−14 docs/versioned_docs/version-7.11.x/configuration/integration.md+6−14 docs/versioned_docs/version-7.12.x/configuration/integration.md+6−14
docs/docs/configuration/integration.md+6−14
@@ -77,23 +77,15 @@ server {
7777}
7878```
7979
80−When you use ingress-nginx in Kubernetes, you MUST use `kubernetes/ingress-nginx` (which includes the Lua module) and the following configuration snippet for your `Ingress`.
81−Variables set with `auth_request_set` are not `set`-able in plain nginx config when the location is processed via `proxy_pass` and then may only be processed by Lua.
82−Note that `nginxinc/kubernetes-ingress` does not include the Lua module.
80+When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
8381
8482```yaml
85−nginx.ingress.kubernetes.io/auth-response-headers: Authorization
86−nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$escaped_request_uri
87−nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
88−nginx.ingress.kubernetes.io/configuration-snippet: |
89− auth_request_set $name_upstream_1 $upstream_cookie_name_1;
90−
91− access_by_lua_block {
92− if ngx.var.name_upstream_1 ~= "" then
93− ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
94− end
95− }
83+nginx.ingress.kubernetes.io/auth-url: "https://<oauth2-proxy-fqdn>/oauth2/auth"
84+nginx.ingress.kubernetes.io/auth-signin: "https://<oauth2-proxy-fqdn>/oauth2/start?rd=$escaped_request_uri"
9685```
86+
87+This minimal configuration works for standard authentication flows. Lua/cookie handling is only needed for advanced scenarios (e.g., multi-part cookies, custom session logic). See the official ingress-nginx example: https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/.
88+
9789It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
9890
9991You have to substitute *name* with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=".
docs/versioned_docs/version-7.10.x/configuration/integration.md+6−14
@@ -77,23 +77,15 @@ server {
7777}
7878```
7979
80−When you use ingress-nginx in Kubernetes, you MUST use `kubernetes/ingress-nginx` (which includes the Lua module) and the following configuration snippet for your `Ingress`.
81−Variables set with `auth_request_set` are not `set`-able in plain nginx config when the location is processed via `proxy_pass` and then may only be processed by Lua.
82−Note that `nginxinc/kubernetes-ingress` does not include the Lua module.
80+When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
8381
8482```yaml
85−nginx.ingress.kubernetes.io/auth-response-headers: Authorization
86−nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$escaped_request_uri
87−nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
88−nginx.ingress.kubernetes.io/configuration-snippet: |
89− auth_request_set $name_upstream_1 $upstream_cookie_name_1;
90−
91− access_by_lua_block {
92− if ngx.var.name_upstream_1 ~= "" then
93− ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
94− end
95− }
83+nginx.ingress.kubernetes.io/auth-url: "https://<oauth2-proxy-fqdn>/oauth2/auth"
84+nginx.ingress.kubernetes.io/auth-signin: "https://<oauth2-proxy-fqdn>/oauth2/start?rd=$escaped_request_uri"
9685```
86+
87+This minimal configuration works for standard authentication flows. Lua/cookie handling is only needed for advanced scenarios (e.g., multi-part cookies, custom session logic). See the official ingress-nginx example: https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/.
88+
9789It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
9890
9991You have to substitute *name* with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=".
docs/versioned_docs/version-7.11.x/configuration/integration.md+6−14
@@ -77,23 +77,15 @@ server {
7777}
7878```
7979
80−When you use ingress-nginx in Kubernetes, you MUST use `kubernetes/ingress-nginx` (which includes the Lua module) and the following configuration snippet for your `Ingress`.
81−Variables set with `auth_request_set` are not `set`-able in plain nginx config when the location is processed via `proxy_pass` and then may only be processed by Lua.
82−Note that `nginxinc/kubernetes-ingress` does not include the Lua module.
80+When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
8381
8482```yaml
85−nginx.ingress.kubernetes.io/auth-response-headers: Authorization
86−nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$escaped_request_uri
87−nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
88−nginx.ingress.kubernetes.io/configuration-snippet: |
89− auth_request_set $name_upstream_1 $upstream_cookie_name_1;
90−
91− access_by_lua_block {
92− if ngx.var.name_upstream_1 ~= "" then
93− ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
94− end
95− }
83+nginx.ingress.kubernetes.io/auth-url: "https://<oauth2-proxy-fqdn>/oauth2/auth"
84+nginx.ingress.kubernetes.io/auth-signin: "https://<oauth2-proxy-fqdn>/oauth2/start?rd=$escaped_request_uri"
9685```
86+
87+This minimal configuration works for standard authentication flows. Lua/cookie handling is only needed for advanced scenarios (e.g., multi-part cookies, custom session logic). See the official ingress-nginx example: https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/.
88+
9789It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
9890
9991You have to substitute *name* with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=".
docs/versioned_docs/version-7.12.x/configuration/integration.md+6−14
@@ -77,23 +77,15 @@ server {
7777}
7878```
7979
80−When you use ingress-nginx in Kubernetes, you MUST use `kubernetes/ingress-nginx` (which includes the Lua module) and the following configuration snippet for your `Ingress`.
81−Variables set with `auth_request_set` are not `set`-able in plain nginx config when the location is processed via `proxy_pass` and then may only be processed by Lua.
82−Note that `nginxinc/kubernetes-ingress` does not include the Lua module.
80+When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
8381
8482```yaml
85−nginx.ingress.kubernetes.io/auth-response-headers: Authorization
86−nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$escaped_request_uri
87−nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
88−nginx.ingress.kubernetes.io/configuration-snippet: |
89− auth_request_set $name_upstream_1 $upstream_cookie_name_1;
90−
91− access_by_lua_block {
92− if ngx.var.name_upstream_1 ~= "" then
93− ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
94− end
95− }
83+nginx.ingress.kubernetes.io/auth-url: "https://<oauth2-proxy-fqdn>/oauth2/auth"
84+nginx.ingress.kubernetes.io/auth-signin: "https://<oauth2-proxy-fqdn>/oauth2/start?rd=$escaped_request_uri"
9685```
86+
87+This minimal configuration works for standard authentication flows. Lua/cookie handling is only needed for advanced scenarios (e.g., multi-part cookies, custom session logic). See the official ingress-nginx example: https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/.
88+
9789It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
9890
9991You have to substitute *name* with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=".