You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/proposals/session-persistence.md
+6-12Lines changed: 6 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,18 +10,18 @@ Enable NGINX Gateway Fabric to support session persistence for both NGINX Plus a
10
10
## Goals
11
11
12
12
- Extend the Upstream Settings Policy API to allow specifying `ip_hash` load balancing method to support basic session persistence.
13
-
- Design the translation of the Gateway API `sessionPersistence` specification, which can be configured on both HTTPRoute and GRPCRoute, into NGINX Plus cookie-based session persistence directives with `secure` and `httpOnly` mode enforced by default.
13
+
- Design the translation of the Gateway API `sessionPersistence` specification, which can be configured on both HTTPRoute and GRPCRoute, into NGINX Plus cookie-based session persistence directives.
14
14
15
15
## Non-Goals
16
16
17
17
- Describe or implement low-level configuration details for enabling session persistence.
18
18
- Extend session persistence support to TLSRoutes or other Layer 4 route types.
19
-
- Supporting the `sameSite` cookie directive for NGINX Plus session persistence, which may be considered in the future as the Gateway API `sessionPersistence` specification evolves.
19
+
- Supporting the `secure`, `httponly`, `sameSite` cookie directive for NGINX Plus session persistence, which may be considered in the future as the Gateway API `sessionPersistence` specification evolves.
20
20
21
21
## Introduction
22
22
23
23
For NGINX OSS, session persistence is enabled by setting `loadBalancingMethod: ip_hash` on UpstreamSettingsPolicy, which adds the `ip_hash` directive to upstreams and provides IP-based affinity.
24
-
For NGINX Plus, session persistence defined on `HTTPRouteRule/GRPCRouteRule` is translated into sticky cookie upstream configuration with secure, httpOnly, host-only cookies and a path derived from HTTPRoute matches (or defaulted for GRPCRoutes), so sessions stick to a chosen backend.
24
+
For NGINX Plus, session persistence defined on `HTTPRouteRule/GRPCRouteRule` is translated into sticky cookie upstream configuration with host-only cookies and a path derived from HTTPRoute matches (or defaulted for GRPCRoutes), so sessions stick to a chosen backend.
25
25
26
26
### Understanding the NGINX directives
27
27
@@ -52,7 +52,7 @@ domain=<domain> - Sets the domain for the cookie scope.
52
52
path=<path> - Sets the path for the cookie scope.
53
53
samesite=[strict|lax|none|$variable] - Sets the sameSite attribute for the cookie.
54
54
secure - Sets the `secure` attribute for the cookie.
55
-
httpOnly - Sets the `httpOnly` attribute for the cookie.
55
+
httponly - Sets the `httponly` attribute for the cookie.
56
56
57
57
## API, Customer Driven Interfaces, and User Experience
58
58
@@ -139,10 +139,6 @@ Users can configure [sessionPersistence](https://gateway-api.sigs.k8s.io/referen
139
139
|`cookieConfig.lifetimeType=Permanent`|`expires=<absoluteTimeout>`| Cookie persists until the specified timeout. `absoluteTimeout` is required when `lifetimeType` is `Permanent`. |
140
140
| no matching spec field |_no `domain` attribute_| Cookies are host-only for both `HTTPRoute` and `GRPCRoute`. |
141
141
| no matching spec field |`path`| Behavior is described separately for `HTTPRoute` below. |
142
-
| no matching spec field |`secure`| Enabled by default for all routes. |
143
-
| no matching spec field |`httpOnly`| Enabled by default for all routes. |
144
-
145
-
Note: The default `secure` and `httpOnly` settings may change in the future if we need to align with the Gateway API specification. Enabling `secure` limits session persistence to HTTPS connections to the Gateway, which can be a limitation for HTTP-only clients, and `httpOnly` prevents JavaScript from accessing the cookie. These limitations will be described in more detail in the Session Persistence user documentation.
146
142
147
143
#### Domain and Path selection for Routes
148
144
@@ -177,8 +173,6 @@ There are no existing conformance tests for session persistence, so we will add
177
173
178
174
The main security concern is how far session cookies reach. This design keeps cookies host-only by never setting the domain attribute, and for HTTPRoutes it scopes cookies by route path (or `/` when no safe common prefix exists). That limits both cross-host and cross-path leakage and reduces the impact of a compromised cookie.
179
175
180
-
We also set `secure` and `httponly` on the session cookie by default as a hardening measure. If Gateway API later adds these as fields with different defaults, we’ll treat any change in behavior as an experimental-API breaking change. TThis will be documented in the Session Persistence guide, along with the limitations of these directives, and upgrade guidance will be provided so users can explicitly configure these cookie attributes.
181
-
182
176
### Edge Cases
183
177
184
178
- If an implementation routes through Service IPs, any Gateway-level session persistence must be rejected when Service-level session affinity is enabled. In our case, the data plane routes directly to pod IPs, so Service affinity does not interfere with session persistence between the gateway and backends.
@@ -187,7 +181,7 @@ We also set `secure` and `httponly` on the session cookie by default as a harden
187
181
### Future work
188
182
189
183
- Define clear precedence and additional restrictions when SessionPersistence is configured via a separate policy.
190
-
- Add support for the `sameSite` cookie attribute in a way that remains compliant with the Gateway API specification.
184
+
- Add support for the `sameSite`, `secure`, `httponly` cookie attribute in a way that remains compliant with the Gateway API specification.
191
185
192
186
## Useful Links
193
187
@@ -196,4 +190,4 @@ We also set `secure` and `httponly` on the session cookie by default as a harden
196
190
- RFC standard for [Set-Cookie](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1) header.
197
191
-[Security risks with subdomain](https://blog.stackademic.com/session-security-risks-with-subdomains-2802c56d681f).
198
192
-[Cookie Security](https://www.appsecmonkey.com/blog/cookie-security), read the section `Malicious Subdomains`.
0 commit comments