81 lines
11 KiB
Markdown
81 lines
11 KiB
Markdown
---
|
|
title: official-doc / Spring Boot — server.servlet.session.cookie.same-site (Server Properties, Common Application Properties)
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-boot/appendix/application-properties/index.html
|
|
archive_url:
|
|
related_branches: [feature-keycloak-bff-csrf-samesite-defense]
|
|
related_projects: []
|
|
tags: [official-doc, keycloak-patterns, security, spring-boot, csrf]
|
|
created: 2026-07-25
|
|
---
|
|
|
|
# official-doc / Spring Boot — server.servlet.session.cookie.same-site (Server Properties, Common Application Properties)
|
|
|
|
> Layer: `raw/official-docs/` — Spring Boot 공식 "Common Application Properties" appendix, "Server Properties" 섹션의 `server.servlet.session.cookie.same-site` 항목 원문 발췌. `feature-keycloak-bff-csrf-samesite-defense` branch D3(SameSite 쿠키 속성을 defense-in-depth 로 결합)의 **벤더 메커니즘 존재 근거**로 보관. `[[raw/official-docs/csrf-protection-spring-official]]` 이 이미 "이 프로퍼티를 별도로 확인해야 한다"고 명시했던 후속 자료.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-keycloak-bff-csrf-samesite-defense]] | D3 — Spring Boot 는 `server.servlet.session.cookie.same-site` 프로퍼티로 세션 쿠키의 SameSite 속성을 노출한다. 이것이 AP3 BFF 세션 쿠키에 SameSite=Lax 를 적용하는 **벤더 메커니즘(설정 키가 존재한다는 사실) 근거**다. 단 **허용 값 목록(lax/strict/none)과 기본값은 이 페이지가 문서화하지 않음** — 아래 Usage Boundaries 참조. D3 를 완전히 뒷받침하려면 별도 출처(예: `Cookie.SameSite` Javadoc, MDN `Set-Cookie` SameSite)가 추가로 필요하다. |
|
|
|
|
## 출처
|
|
|
|
- 원본 URL: https://docs.spring.io/spring-boot/appendix/application-properties/index.html
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Spring Boot (VMware/Broadcom) — 공식 레퍼런스 문서 (Common Application Properties appendix)
|
|
- 발행일: 고정 발행일 없음 (rolling reference doc, 릴리스마다 갱신). 확인 시점 페이지 상단 네비게이션 버전 배너: `data-version="4.1.0"` (`nav-container` 요소) → **이 페이지가 문서화하는 Spring Boot 버전은 4.1.0**. `<title>` 태그: "Common Application Properties :: Spring Boot". 페이지 `<link rel="canonical">` 이 입력 URL과 동일함을 확인(`https://docs.spring.io/spring-boot/appendix/application-properties/index.html`).
|
|
- 마지막 확인일: 2026-07-25
|
|
|
|
## 왜 저장했는지
|
|
|
|
AP3(BFF) 세션 쿠키에 SameSite=Lax 를 defense-in-depth 로 결합하려는 branch D3 결정은, 지금까지 CSRF 공식 문서(`csrf-protection-spring-official`)만으로는 근거가 없었다("SameSite" 단어를 전혀 언급하지 않음, `UNSUPPORTED_DECISION`). 이 자료는 Spring Boot 가 `server.servlet.session.cookie.same-site` 라는 프로퍼티를 **실제로 노출한다는 사실**을 공식 문서로 확인하기 위해 저장한다. 단, 이 페이지 자체는 허용 값(lax/strict/none)이나 기본값, Spring Session 사용 시 동작을 다루지 않으므로 D3 근거는 여전히 **부분적**이다.
|
|
|
|
## 핵심 인용
|
|
|
|
> [§Server Properties, `server.servlet.session.cookie.same-site` 행] `server.servlet.session.cookie.same-site` — "SameSite setting for the cookie." (Default Value 열은 비어 있음 — 이 페이지는 기본값을 명시하지 않음)
|
|
|
|
> [§Server Properties, `server.reactive.session.cookie.same-site` 행] `server.reactive.session.cookie.same-site` — "SameSite setting for the cookie." (서블릿 스택과 동일한 설명이 리액티브 스택 프로퍼티에도 동일하게 붙어 있음)
|
|
|
|
> [heading] "Server Properties" (섹션 anchor: `#appendix.application-properties.server`, 프로퍼티 anchor: `#application-properties.server.server.servlet.session.cookie.same-site`)
|
|
|
|
> [nav-container 버전 배너] `data-version="4.1.0"` — 이 appendix 가 문서화하는 Spring Boot 버전
|
|
|
|
## Claims Extracted (추출된 주장)
|
|
|
|
> `Claim ID` prefix: `SPRINGBOOT-SESSION-SAMESITE`.
|
|
|
|
| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| SPRINGBOOT-SESSION-SAMESITE-C1 | Spring Boot 는 `server.servlet.session.cookie.same-site` 라는 설정 프로퍼티를 제공하며, 이 프로퍼티는 "세션 쿠키의 SameSite 설정"이다 | [§Server Properties] `server.servlet.session.cookie.same-site` — "SameSite setting for the cookie." | `official-vendor-doc` | Spring Boot 4.1.0, 서블릿 스택(embedded Tomcat/Jetty/Undertow) 세션 쿠키에 이 프로퍼티로 SameSite 속성을 externalized configuration 으로 설정할 수 있다는 사실 | (a) 허용 값 목록(lax/strict/none) — 이 페이지 Description/Default Value 열 어디에도 열거되지 않음. (b) 기본값 — Default Value 열이 이 행에서 비어 있음(다른 행, 예: `server.servlet.session.persistent`=`false` 는 명시되는 것과 대조). (c) Spring Session(`@EnableSpringHttpSession`, 예: Redis-backed) 사용 시 이 프로퍼티가 실제 적용되는지 — 이 페이지는 Spring Session 을 전혀 언급하지 않음(별도 nav 링크로만 존재) |
|
|
| SPRINGBOOT-SESSION-SAMESITE-C2 | 서블릿 스택의 `server.servlet.session.cookie.same-site` 와 별개로, 리액티브(WebFlux) 스택에도 `server.reactive.session.cookie.same-site` 라는 동일한 설명의 프로퍼티가 문서화되어 있다 | [§Server Properties] `server.reactive.session.cookie.same-site` — "SameSite setting for the cookie." | `official-vendor-doc` | Spring Boot 가 서블릿/리액티브 두 스택 모두에서 동일한 이름 패턴으로 SameSite 프로퍼티를 노출한다는 사실 확인(AP3 가 서블릿 스택이라면 `server.reactive.*` 는 직접 적용 대상 아님) | 두 스택의 실제 쿠키 작성 구현이 SameSite 처리에서 동일하게 동작하는지는 이 설명 문장만으로 증명되지 않음 |
|
|
| SPRINGBOOT-SESSION-SAMESITE-C3 | 이 두 프로퍼티는 "Server Properties" 섹션(`appendix.application-properties.server`)에 위치하며, 이 appendix 페이지가 확인 시점 문서화하는 Spring Boot 버전은 4.1.0 이다 | [heading] "Server Properties"; [nav banner] `data-version="4.1.0"` | `official-vendor-doc` | 이 claim 세트(C1·C2)가 유효한 버전 범위 — Spring Boot 4.1.0 기준 | 다른 Spring Boot 메이저/마이너 버전(예: 2.x, 3.x)에서 이 프로퍼티의 존재·설명·기본값이 동일한지는 이 페이지만으로 확인 불가 — branch/project 가 실제 사용하는 Spring Boot 버전과 대조 필요 |
|
|
|
|
## Usage Boundaries (적용 경계)
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `SPRINGBOOT-SESSION-SAMESITE-C1`: `server.servlet.session.cookie.same-site` 프로퍼티가 존재하고 "세션 쿠키의 SameSite 설정"이라는 것
|
|
- `SPRINGBOOT-SESSION-SAMESITE-C2`: 리액티브 스택에도 대응 프로퍼티가 존재한다는 것
|
|
- `SPRINGBOOT-SESSION-SAMESITE-C3`: 이 두 프로퍼티가 "Server Properties" 섹션 소속이며, 확인 시점 문서 버전은 Spring Boot 4.1.0
|
|
- 이 자료가 증명하지 않는 것 (**UNSUPPORTED_DECISION 후보 — branch D3 로 그대로 "허용 값/기본값 확인됨"이라 인용 금지**):
|
|
- **허용 값(lax / strict / none) 목록** — 이 페이지의 표는 Name/Description/Default Value 3열뿐이며, 열거형 값 목록을 어디에도 싣지 않는다. 값 목록·리터럴 표기(대소문자 등)를 확인하려면 `org.springframework.boot.web.server.Cookie.SameSite` Javadoc 등 별도 공식 자료가 필요하다(이번 조사 범위 밖, 미아카이빙).
|
|
- **기본값** — 이 행의 "Default Value" 열은 비어 있다(같은 표의 다른 행, 예: `server.servlet.session.persistent`=`false`, `server.servlet.session.timeout`=`30m` 은 값이 명시되는 것과 대조적으로, `same-site` 행은 공란). 즉 "미설정 시 어떤 SameSite 값이 적용되는가(속성 자체 생략 vs 특정 기본값)"는 이 페이지만으로 알 수 없다.
|
|
- **Spring Session 과의 상호작용** — 이 페이지는 "Spring Session" 을 전혀 언급하지 않는다(페이지 내 유일한 관련 텍스트는 nav 메뉴의 "Spring Session" 링크(`../../reference/web/spring-session.html`)뿐이며 본문 설명에는 등장하지 않음). 따라서 `@EnableSpringHttpSession`(예: Redis-backed Spring Session) 을 사용하는 구성에서 이 프로퍼티가 실제로 적용되는지, 무시되는지는 **이 페이지 범위 밖**이며 별도의 Spring Session 레퍼런스 확인이 필요하다.
|
|
- 내 프로젝트(AP3 BFF)에 적용하려면 추가 확인이 필요한 것:
|
|
- AP3 가 Spring Session(Redis 등)을 쓰는지, 순수 embedded 컨테이너 세션인지 확정 — 전자라면 이 프로퍼티의 실효성 자체를 별도 검증해야 한다(아래 메모의 미검증 caveat 참조).
|
|
- 허용 값 리터럴(`lax`/`strict`/`none`, 대소문자)과 기본값은 `Cookie.SameSite` Javadoc 또는 소스 확인 필요.
|
|
- `[[raw/official-docs/csrf-protection-spring-official]]` 의 `XSRF-TOKEN` 쿠키(`CookieCsrfTokenRepository`)에는 이 프로퍼티가 적용되지 않는다 — `server.servlet.session.cookie.*` 는 세션 쿠키(예: `JSESSIONID`) 전용이며 CSRF 쿠키의 SameSite 설정은 별개 메커니즘이다.
|
|
|
|
## 메모
|
|
|
|
> 검증되지 않은 내 해석/외부 미검증 caveat. 사실 인용과 분리.
|
|
|
|
- **미검증 caveat (공식 문서 아님, 인용 금지 — branch D3 근거로 그대로 쓰지 말 것)**: 벤더 GitHub 이슈(`spring-projects/spring-boot#28772`, `#15047`, `spring-projects/spring-session#3622`)에서 이 프로퍼티가 Spring Session(`@EnableSpringHttpSession`, 예: Redis-backed) 사용 시 **무시될 수 있다**는 보고가 있다고 알려져 있다. 이 자료(공식 appendix) 는 이 상호작용을 전혀 언급하지 않으므로(위 Usage Boundaries 참조), 해당 이슈들은 `official-doc` 등급 claim 으로 승격할 수 없고, 이 caveat 은 branch 작성 시 AP3 의 실제 세션 저장소(embedded container vs Spring Session)를 확인해야 한다는 조사 TODO 로만 취급해야 한다.
|
|
- D3(SameSite 결합)의 "메커니즘 존재" 부분은 이 자료(C1)로 뒷받침 가능해 보이나, "값/기본값/Spring Session 상호작용"은 여전히 근거 공백 — branch 작성자가 D3 를 완전히 `SUPPORTED` 로 승급하려면 위 미확보 항목을 별도 raw 자료로 채워야 한다(미검증 판단, 제안일 뿐).
|
|
- 추가로 봐야 할 동일 출처 페이지: `org.springframework.boot.web.server.Cookie.SameSite` Javadoc, Spring Session reference 의 쿠키 직렬화/SameSite 옵션 페이지, MDN `Set-Cookie` SameSite 사양.
|
|
|
|
## 관련
|
|
|
|
- 같은 주제 다른 official-doc / company-tech-blog: `[[raw/official-docs/csrf-protection-spring-official]]` — 이 문서가 SameSite 를 전혀 다루지 않는다고 명시하며 본 자료의 필요성을 예고했던 companion 자료
|
|
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/...]]` (생성 시)
|