@@ -60,23 +60,23 @@ server {
6060 auth_request_set $auth_cookie $upstream_http_set_cookie;
6161 add_header Set-Cookie $auth_cookie;
6262
63− # When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
64− # limit and so the OAuth2 Proxy splits these into multiple parts.
63+ # Large OIDC tokens can make the session cookie exceed the 4KB limit,
64+ # causing OAuth2 Proxy to split the cookie into multiple parts.
6565 # Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
66− # so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
67− auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
66+ # so extract the second part when using the default cookie name, `_oauth2_proxy`.
67+ auth_request_set $auth_cookie_upstream_1 $upstream_cookie__oauth2_proxy_1;
6868
6969 # Extract the Cookie attributes from the first Set-Cookie header and append them
7070 # to the second part ($upstream_cookie_* variables only contain the raw cookie content)
7171 if ($auth_cookie ~* "(; .*)") {
72− set $auth_cookie_name_0 $auth_cookie;
73− set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
72+ set $auth_cookie_0 $auth_cookie;
73+ set $auth_cookie_1 "_oauth2_proxy_1=$auth_cookie_upstream_1$1";
7474 }
7575
7676 # Send both Set-Cookie headers now if there was a second part
77− if ($auth_cookie_name_upstream_1) {
78− add_header Set-Cookie $auth_cookie_name_0;
79− add_header Set-Cookie $auth_cookie_name_1;
77+ if ($auth_cookie_upstream_1) {
78+ add_header Set-Cookie $auth_cookie_0;
79+ add_header Set-Cookie $auth_cookie_1;
8080 }
8181
8282 proxy_pass http://backend/;
@@ -91,6 +91,24 @@ server {
9191}
9292```
9393
94+### Multi-part session cookies
95+
96+The example above is ready to use with the default `--cookie-name=_oauth2_proxy` setting and handles a session split into two cookies. If you configure a custom cookie name, update both references to the second cookie part:
97+
98+| Cookie configuration | Nginx upstream cookie variable | `Set-Cookie` name |
99+| --- | --- | --- |
100+| Default (`_oauth2_proxy`) | `$upstream_cookie__oauth2_proxy_1` | `_oauth2_proxy_1=` |
101+| `--cookie-name=my_cookie` | `$upstream_cookie_my_cookie_1` | `my_cookie_1=` |
102+
103+For example, with `--cookie-name=my_cookie`, change the relevant lines to:
104+
105+```nginx
106+auth_request_set $auth_cookie_upstream_1 $upstream_cookie_my_cookie_1;
107+set $auth_cookie_1 "my_cookie_1=$auth_cookie_upstream_1$1";
108+```
109+
110+If a session is split into more than two cookies, repeat the extraction for each additional numeric suffix. For consistently large sessions, prefer `--session-store-type=redis` so only a small session ticket is stored in the browser cookie.
111+
94112### Understanding the `error_page` redirect pattern
95113
96114The `auth_request` directive expects the authentication endpoint (`/oauth2/auth`) to return:
@@ -167,8 +185,6 @@ It is recommended to use `--session-store-type=redis` when expecting large sessi
167185For a complete example of integrating oauth2-proxy with Kubernetes Dashboard on AKS using Azure Entra ID, including RBAC configuration and troubleshooting, see the [Kubernetes Dashboard on AKS](../providers/ms_entra_id.md#kubernetes-dashboard-on-aks) section in the Microsoft Entra ID provider documentation.
168186:::
169187
170−You 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=".
171−
172188:::note
173189If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
174190:::