From 57d2eb157d71f95671d38edd6902cf080b8ad393 Mon Sep 17 00:00:00 2001 From: Marcus Da Coregio Date: Tue, 10 Oct 2023 10:31:25 -0300 Subject: [PATCH 1/2] Add guides to navigation list Issue gh-2456 --- spring-session-docs/modules/ROOT/nav.adoc | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/spring-session-docs/modules/ROOT/nav.adoc b/spring-session-docs/modules/ROOT/nav.adoc index 647dda86..014c8938 100644 --- a/spring-session-docs/modules/ROOT/nav.adoc +++ b/spring-session-docs/modules/ROOT/nav.adoc @@ -14,7 +14,15 @@ *** {gh-samples-url}spring-session-sample-boot-webflux[Redis] *** xref:guides/boot-webflux-custom-cookie.adoc[Custom Cookie] ** Java Configuration +*** xref:guides/java-custom-cookie.adoc[Custom Cookie] +*** xref:guides/java-redis.adoc[Redis] +*** xref:guides/java-jdbc.adoc[JDBC] +*** xref:guides/java-hazelcast.adoc[Hazelcast] +*** xref:guides/java-rest.adoc[REST] +*** xref:guides/java-security.adoc[Spring Security] ** XML Configuration +*** xref:guides/xml-redis.adoc[Redis] +*** xref:guides/xml-jdbc.adoc[JDBC] * xref:configurations.adoc[Configurations] ** xref:configuration/redis.adoc[Redis] * xref:http-session.adoc[HttpSession Integration] From 4602eaa194e0d509d8012d6ee74be6ecf885796f Mon Sep 17 00:00:00 2001 From: Marcus Da Coregio Date: Tue, 10 Oct 2023 10:32:05 -0300 Subject: [PATCH 2/2] Add Customizing Cookie to Common Configurations Closes gh-2456 --- spring-session-docs/modules/ROOT/nav.adoc | 1 + .../ROOT/pages/configuration/common.adoc | 80 +++++++++++++++++++ 2 files changed, 81 insertions(+) create mode 100644 spring-session-docs/modules/ROOT/pages/configuration/common.adoc diff --git a/spring-session-docs/modules/ROOT/nav.adoc b/spring-session-docs/modules/ROOT/nav.adoc index 014c8938..d2e4e76a 100644 --- a/spring-session-docs/modules/ROOT/nav.adoc +++ b/spring-session-docs/modules/ROOT/nav.adoc @@ -25,6 +25,7 @@ *** xref:guides/xml-jdbc.adoc[JDBC] * xref:configurations.adoc[Configurations] ** xref:configuration/redis.adoc[Redis] +** xref:configuration/common.adoc[Common Configurations] * xref:http-session.adoc[HttpSession Integration] * xref:web-socket.adoc[WebSocket Integration] * xref:web-session.adoc[WebSession Integration] diff --git a/spring-session-docs/modules/ROOT/pages/configuration/common.adoc b/spring-session-docs/modules/ROOT/pages/configuration/common.adoc new file mode 100644 index 00000000..78119802 --- /dev/null +++ b/spring-session-docs/modules/ROOT/pages/configuration/common.adoc @@ -0,0 +1,80 @@ +[[common-configurations]] += Common Configurations + +This section contains common configurations that applies to all or most Spring Session modules. +It contains configuration examples for the following use cases: + +- I need to <> + +[[customizing-session-cookie]] +== Customizing Session Cookie + +Once you have set up Spring Session, you can customize how the session cookie is written by exposing a `CookieSerializer` as a Spring bean. +Spring Session comes with `DefaultCookieSerializer`. +Exposing the `DefaultCookieSerializer` as a Spring bean augments the existing configuration when you use configurations like `@EnableRedisHttpSession`. +The following example shows how to customize Spring Session's cookie: + +==== +[source,java] +---- +include::{samples-dir}spring-session-sample-javaconfig-custom-cookie/src/main/java/sample/Config.java[tags=cookie-serializer] +---- + +<1> We customize the name of the cookie to be `JSESSIONID`. +<2> We customize the path of the cookie to be `/` (rather than the default of the context root). +<3> We customize the domain name pattern (a regular expression) to be `^.+?\\.(\\w+\\.[a-z]+)$`. +This allows sharing a session across domains and applications. +If the regular expression does not match, no domain is set and the existing domain is used. +If the regular expression matches, the first https://docs.oracle.com/javase/tutorial/essential/regex/groups.html[grouping] is used as the domain. +This means that a request to https://child.example.com sets the domain to `example.com`. +However, a request to http://localhost:8080/ or https://192.168.1.100:8080/ leaves the cookie unset and, thus, still works in development without any changes being necessary for production. +==== + +WARNING: You should only match on valid domain characters, since the domain name is reflected in the response. +Doing so prevents a malicious user from performing such attacks as https://en.wikipedia.org/wiki/HTTP_response_splitting[HTTP Response Splitting]. + +[[custom-cookie-options]] +=== Configuration Options + +The following configuration options are available: + +* `cookieName`: The name of the cookie to use. +Default: `SESSION`. +* `useSecureCookie`: Specifies whether a secure cookie should be used. +Default: Use the value of `HttpServletRequest.isSecure()` at the time of creation. +* `cookiePath`: The path of the cookie. +Default: The context root. +* `cookieMaxAge`: Specifies the max age of the cookie to be set at the time the session is created. +Default: `-1`, which indicates the cookie should be removed when the browser is closed. +* `jvmRoute`: Specifies a suffix to be appended to the session ID and included in the cookie. +Used to identify which JVM to route to for session affinity. +With some implementations (that is, Redis) this option provides no performance benefit. +However, it can help with tracing logs of a particular user. +* `domainName`: Allows specifying a specific domain name to be used for the cookie. +This option is simple to understand but often requires a different configuration between development and production environments. +See `domainNamePattern` as an alternative. +* `domainNamePattern`: A case-insensitive pattern used to extract the domain name from the `HttpServletRequest#getServerName()`. +The pattern should provide a single grouping that is used to extract the value of the cookie domain. +If the regular expression does not match, no domain is set and the existing domain is used. +If the regular expression matches, the first https://docs.oracle.com/javase/tutorial/essential/regex/groups.html[grouping] is used as the domain. +* `sameSite`: The value for the `SameSite` cookie directive. +To disable the serialization of the `SameSite` cookie directive, you may set this value to `null`. +Default: `Lax` + +[[custom-cookie-in-webflux]] +=== Custom Cookie in WebFlux + +You can customize how the session cookie is written in a WebFlux application by exposing a `WebSessionIdResolver` as a Spring bean. +Spring Session uses a `CookieWebSessionIdResolver` by default. +The following example shows how to customize Spring Session's cookie: + +==== +[source,java] +---- +include::{samples-dir}spring-session-sample-boot-webflux-custom-cookie/src/main/java/sample/CookieConfig.java[tags=webflux-cookie-serializer] +---- + +<1> We customize the name of the cookie to be `JSESSIONID`. +<2> We customize the path of the cookie to be `/` (rather than the default of the context root). +<3> We customize the `SameSite` cookie directive to be `Strict`. +====