12 KiB
title, source_type, url, archive_url, related_branches, related_projects, tags, created
| title | source_type | url | archive_url | related_branches | related_projects | tags | created | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| official-doc / Keycloak JavaScript Adapter — Third-Party Cookies, Silent check-sso Mechanism & Fallback | official-doc | https://www.keycloak.org/securing-apps/javascript-adapter |
|
|
|
2026-07-18 |
Keycloak JavaScript Adapter — Third-Party Cookies, Silent check-sso Mechanism & Fallback
Layer:
raw/— 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은/ingest후wiki/concepts/에source-summary-template형식으로 별도 작성. 원본은 raw에 영구 보관.
source_type
official-doc — Keycloak 공식 문서 (keycloak.org, "Nightly" 버전 페이지, securing-apps/javascript-adapter).
Parent / 활용 branch (필수, 최소 1개+)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-keycloak-spa-token-storage-tradeoff | D3 — MECHANISM anchor: Keycloak JS adapter의 silent check-sso는 hidden iframe 기반으로 동작하며, adapter는 Session Status iframe / silent check-sso / 일부 regular(non-silent) check-sso에 대해 third-party cookie에 의존한다. third-party cookie가 차단되면 (문서가 명시하는 예: Safari 13.1+) silent check-sso는 자동으로 regular(non-silent, 즉 full redirect) check-sso로 fallback한다 — "silent renew가 Safari ITP 하에서 저하된다"는 branch 본문 서술의 공식 메커니즘 근거. |
출처 / Source
- 원본 URL: https://www.keycloak.org/securing-apps/javascript-adapter
- 아카이브 URL: (미제공 — 사용자 archive_url 미입력)
- 저자 / 조직: Keycloak project (keycloak.org 공식 문서, "Securing applications" 가이드 하위)
- 발행일: 명시 없음 — 페이지 상단에 "Nightly" 버전 표기가 있는 rolling/versioned 문서 (특정 릴리스에 고정되지 않고 지속 갱신됨)
- 마지막 확인일: 2026-07-18
왜 저장했는지 / Why archived
Parent branch의 D3 결정("silent renew는 3rd-party cookie 제약으로 점점 어려워진다")이 UNSUPPORTED_DECISION으로 라벨링되어 있었다 (근거: Safari ITP / Chrome 3rd-party cookie phase-out의 직접 인용이 branch Sources에 없음). 본 자료는 Keycloak 공식 문서에서 (1) silent check-sso가 hidden iframe 기반으로 동작하는 메커니즘, (2) adapter가 third-party cookie에 의존한다는 명시적 진술, (3) third-party cookie 차단 시 자동 fallback 동작, (4) Safari 13.1을 영향받는 브라우저 예시로 직접 지목하는 문장을 확보하여 D3의 메커니즘(MECHANISM) 앵커로 사용하기 위해 저장.
핵심 인용 / Key quotes (verbatim, 5문장)
[§Using the adapter] "You can configure a silent check-sso option. With this feature enabled, your browser will not perform a full redirect to the Keycloak server and back to your application, but this action will be performed in a hidden iframe. Therefore, your application resources are only loaded and parsed once by the browser, namely when the application is initialized and not again after the redirect back from Keycloak to your application. This approach is particularly useful in case of SPAs (Single Page Applications)."
[§Modern Browsers with Tracking Protection] "The adapter relies on third-party cookies for Session Status iframe, silent check-sso and partially also for regular (non-silent) check-sso. Those features have limited functionality or are completely disabled based on how restrictive the browser is regarding cookies. The adapter tries to detect this setting and reacts accordingly."
[§Modern Browsers with Tracking Protection / Browsers with Blocked Third-Party Cookies] "Session Status iframe is not supported and is automatically disabled if such browser behavior is detected by the adapter. This means the adapter cannot use a session cookie for Single Sign-Out detection and must rely purely on tokens. As a result, when a user logs out in another window, the application using the adapter will not be logged out until the application tries to refresh the Access Token. Therefore, consider setting the Access Token Lifespan to a relatively short time, so that the logout is detected as soon as possible. For more details, see Session and Token Timeouts."
[§Modern Browsers with Tracking Protection / Browsers with Blocked Third-Party Cookies] "Silent check-sso is not supported and falls back to regular (non-silent) check-sso by default. This behavior can be changed by setting silentCheckSsoFallback: false in the options passed to the init method. In this case, check-sso will be completely disabled if restrictive browser behavior is detected."
[§Modern Browsers with Tracking Protection / Browsers with Blocked Third-Party Cookies] "An affected browser is for example Safari starting with version 13.1."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KC-JSADAPTER-C1 | silent check-sso는 Keycloak 서버로의 full redirect 대신 hidden iframe에서 인증 상태를 확인하는 메커니즘이다 | [§Using the adapter] "With this feature enabled, your browser will not perform a full redirect to the Keycloak server and back to your application, but this action will be performed in a hidden iframe." | official-vendor-doc |
Keycloak JS adapter (keycloak-js)의 onLoad: 'check-sso' + silentCheckSsoRedirectUri 옵션 사용 시 |
이 hidden iframe 메커니즘이 왜 third-party cookie를 필요로 하는지의 브라우저 레벨 이유(쿠키 파티셔닝 자체)는 이 문장만으로 증명 안 됨 — C2가 보완 |
| KC-JSADAPTER-C2 | adapter는 Session Status iframe, silent check-sso, 그리고 부분적으로 regular(non-silent) check-sso에 대해 third-party cookie에 의존한다 | [§Modern Browsers with Tracking Protection] "The adapter relies on third-party cookies for Session Status iframe, silent check-sso and partially also for regular (non-silent) check-sso." | official-vendor-doc |
Keycloak JS adapter 전반 (Session Status iframe SSO 감지, silent check-sso, 그리고 부분적으로 일반 check-sso) | 어떤 브라우저가 어느 시점부터 third-party cookie를 차단하는지의 정확한 버전/일정은 이 문장만으로 증명 안 됨 — 브라우저 벤더 공식 문서(Apple WebKit ITP, Chrome Privacy Sandbox) 별도 확인 필요 |
| KC-JSADAPTER-C3 | third-party cookie가 차단된 브라우저에서는 Session Status iframe이 자동 비활성화되고, adapter는 세션 쿠키 대신 순수 토큰 기반으로만 Single Sign-Out을 감지한다 (로그아웃 감지는 Access Token 갱신 시점까지 지연됨) | [§Modern Browsers with Tracking Protection] "Session Status iframe is not supported and is automatically disabled if such browser behavior is detected by the adapter. This means the adapter cannot use a session cookie for Single Sign-Out detection and must rely purely on tokens." | official-vendor-doc |
Session Status iframe 기능 (다른 창에서의 로그아웃 감지) — third-party cookie 차단 브라우저 한정 | silent check-sso 자체의 fallback 동작은 별도(C4) — 이 인용은 Session Status iframe(SSO 로그아웃 감지)에 대한 것 |
| KC-JSADAPTER-C4 | silent check-sso는 third-party cookie가 차단되면 미지원 상태가 되어 기본값으로 regular(non-silent, 즉 full redirect) check-sso로 자동 fallback한다. silentCheckSsoFallback: false로 이 동작을 끌 수 있으며, 이 경우 check-sso 자체가 완전히 비활성화된다 |
[§Modern Browsers with Tracking Protection] "Silent check-sso is not supported and falls back to regular (non-silent) check-sso by default. This behavior can be changed by setting silentCheckSsoFallback: false in the options passed to the init method." | official-vendor-doc |
onLoad: 'check-sso' + silentCheckSsoRedirectUri를 사용하는 Keycloak JS adapter 초기화 전체 |
silent renew(토큰 갱신) 자체가 완전히 불가능해진다는 뜻은 아님 — fallback은 "hidden iframe → full redirect" 전환이며, refresh_token grant 직접 사용 등 다른 경로의 가능/불가능은 이 문장이 다루지 않음 |
| KC-JSADAPTER-C5 | Safari 13.1 이상 버전이 이 third-party cookie 차단 정책의 영향을 받는 브라우저의 예시로 문서에 명시되어 있다 | [§Modern Browsers with Tracking Protection / Browsers with Blocked Third-Party Cookies] "An affected browser is for example Safari starting with version 13.1." | official-vendor-doc |
Safari 13.1 이상에서 Keycloak JS adapter의 Session Status iframe / silent check-sso 동작 예측 | "Safari ITP(Intelligent Tracking Prevention)"라는 명칭 자체는 이 문서에 등장하지 않음 — Safari가 왜/어떤 메커니즘으로 third-party cookie를 차단하는지의 상세는 Apple WebKit 공식 문서로 별도 corroborate 필요. Chrome의 정확한 phase-out 일정도 이 문장으로 증명 안 됨 |
Strength 값 설명
모든 claim은 official-vendor-doc — Keycloak 프로젝트가 발행하는 공식 adapter 문서이며 RFC/표준(official-standard)은 아니고, 사례 기반 기업 블로그(company-case-study)도 아니다.
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
KC-JSADAPTER-C1: silent check-sso의 메커니즘 = hidden iframe (full redirect 아님)KC-JSADAPTER-C2: adapter가 Session Status iframe / silent check-sso / 부분적 regular check-sso에 third-party cookie를 의존한다는 사실KC-JSADAPTER-C3: third-party cookie 차단 시 Session Status iframe이 비활성화되고 로그아웃 감지가 토큰 갱신 시점까지 지연됨KC-JSADAPTER-C4: silent check-sso가 미지원 시 regular(non-silent) check-sso로 기본 fallback한다는 adapter 자체의 동작KC-JSADAPTER-C5: Safari 13.1 이상이 영향받는 브라우저의 명시적 예시
- 이 자료가 증명하지 않는 것:
- "Safari ITP"라는 정책 명칭 자체 — 이 문서는 그 용어를 사용하지 않는다 (Safari 버전만 명시)
- Chrome 3rd-party cookie phase-out의 정확한 일정·범위
- 이 fallback이 branch 본문에서 말하는 "refresh_token grant 직접 사용" 대안의 우수성 — 이 문서는 fallback 존재만 진술하지, 대안 권고는 하지 않음
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 본 프로젝트의 Keycloak 배포가 실제로 Safari/Chrome에서 silent check-sso fallback을 트리거하는지 e2e 재현 필요 (branch의 Claims To Verify 항목과 일치)
- Apple WebKit ITP 공식 문서로 "Safari ITP"라는 용어와 정책 메커니즘 자체를 별도 corroborate (branch D3의 완전한 근거 보강을 위해서는 이 자료 하나로 부족 — 이 자료는 **Keycloak adapter 측 반응(메커니즘)**만 증명, 브라우저 벤더 측 정책 원인은 별도 자료 필요)
메모 / Notes
- 이 문서는 branch D3의 "왜 silent renew가 저하되는가"에 대한 adapter 측 메커니즘 근거로는 충분하다 (hidden iframe → third-party cookie 의존 → 차단 시 fallback). 다만 "Safari ITP"라는 브라우저 정책 자체의 공식 근거(Apple WebKit 블로그/문서)는 여전히 별도 필요 — branch D3를 완전히
SUPPORTED로 전환하려면 이 자료 + Apple/Chrome vendor 자료 조합이 필요할 것으로 보임 (미검증 추론, 사용자 확인 필요). - 페이지가 "Nightly" 버전 표기이므로 특정 Keycloak 릴리스에 고정된 문서가 아님 — 향후 재확인 시 문구가 바뀔 수 있음에 유의.
Related / 관련
- 같은 branch의 다른 근거 자료: raw/official-docs/owasp-html5-storage-xss-spa, raw/official-docs/oauth-v2-1-draft-ietf, raw/company-tech-blogs/curity-bff-pattern-spa
- 이 자료를 인용한 wiki 요약: (아직 생성되지 않음 —
/ingest대상 후보)