From 53cad429a16795d8da78f2d1865f5e81c3c2985e Mon Sep 17 00:00:00 2001 From: kyy Date: Wed, 6 May 2026 14:09:44 +0900 Subject: [PATCH] =?UTF-8?q?PCKE=20=EA=B5=AC=ED=98=84=20=EA=B0=80=EC=9D=B4?= =?UTF-8?q?=EB=93=9C=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/pkce-backchannel-logout-guide.md | 321 ++++++++++++++++++++++++++ 1 file changed, 321 insertions(+) create mode 100644 docs/pkce-backchannel-logout-guide.md diff --git a/docs/pkce-backchannel-logout-guide.md b/docs/pkce-backchannel-logout-guide.md new file mode 100644 index 00000000..6385ab7a --- /dev/null +++ b/docs/pkce-backchannel-logout-guide.md @@ -0,0 +1,321 @@ +# PKCE RP Back-Channel Logout 구현 가이드 + +이 문서는 Baron SSO와 연동하는 PKCE RP가 `Back-Channel Logout`을 지원하려고 할 때 필요한 구현 기준을 정리합니다. + +## 목적 + +PKCE RP도 OIDC `Authorization Code + PKCE` 흐름을 사용하면서 Baron SSO의 원격 세션 종료 이벤트를 받을 수 있어야 합니다. 다만 `Back-Channel Logout`은 브라우저가 아니라 OP(Baron)가 RP 서버로 직접 `logout_token`을 보내는 방식이므로, **순수 frontend-only PKCE 앱만으로는 구현할 수 없습니다.** + +즉, PKCE RP가 `Back-Channel Logout`을 사용하려면 다음 둘을 모두 가져야 합니다. + +1. PKCE 로그인 플로우를 시작하고 callback을 처리하는 RP +2. `logout_token`을 수신하는 서버 endpoint + +## 적용 대상 + +이 가이드는 다음 경우를 대상으로 합니다. + +- 브라우저에서 `Authorization Code + PKCE`를 사용하는 RP +- RP가 자체 세션 또는 BFF 세션을 보유하는 경우 +- RP가 `Back-Channel Logout URI`를 등록하고 Baron의 세션 종료 이벤트를 직접 수신하려는 경우 + +다음 경우는 이 가이드의 직접 대상이 아닙니다. + +- 순수 frontend-only SPA +- 서버 없이 `localStorage`/`sessionStorage`만 사용하는 PKCE 앱 + +이 경우에는 `Back-Channel Logout` 대신 front-channel logout, 세션 재검증, 짧은 token TTL 같은 별도 전략을 사용해야 합니다. + +## devfront 등록 기준 + +PKCE RP는 devfront에서 아래 항목을 등록합니다. + +1. `Type`: `pkce` +2. `Redirect URI`: RP callback URL +3. `Back-Channel Logout URI`: RP 서버 endpoint +4. 필요 시 `SID Claim Required` + +예시: + +```text +Type: pkce +Redirect URI: https://rp.example.com/callback +Back-Channel Logout URI: https://rp.example.com/backchannel-logout +SID Claim Required: off +``` + +로컬 Docker 개발 예시: + +```text +Redirect URI: http://localhost:3333/callback +Back-Channel Logout URI: http://baron-sso-login-demo:3333/backchannel-logout +``` + +주의: + +- `Back-Channel Logout URI`는 **브라우저 기준 주소가 아니라 Baron backend가 실제로 접근 가능한 주소**여야 합니다. +- Docker 환경에서는 `localhost`가 backend 컨테이너 자신을 가리킬 수 있으므로, Docker 서비스명이나 사설 IP를 사용해야 할 수 있습니다. + +## 구현 요구사항 + +PKCE RP는 최소한 아래를 구현해야 합니다. + +### 1. 로그인 후 세션 매핑 저장 + +RP는 callback 이후 아래 정보 중 하나 이상을 로컬 세션과 연결해야 합니다. + +- `sid -> rpSessionId` +- `sub -> rpSessionId` + +권장 순서는 다음과 같습니다. + +1. `sid`를 우선 저장 +2. `sub`도 함께 저장 +3. 한 사용자가 여러 브라우저 세션을 가질 수 있으므로 `1:N` 구조를 가정 + +예시: + +```text +sid: 796f5cf7-37e7-494b-9b4c-26cc0c217a6a +sub: 8150cb83-a905-4b50-bdcf-d22046ecdc30 +rpSessionId: DqKlQ8MbsGnn_jfOus1k03MFRDpuXCrj +``` + +### 2. `POST /backchannel-logout` endpoint + +RP는 Baron이 서버 간으로 호출할 endpoint를 제공해야 합니다. + +예: + +```text +POST /backchannel-logout +Content-Type: application/x-www-form-urlencoded +Body: logout_token= +``` + +RP는 이 endpoint에서: + +1. `logout_token` 존재 여부 확인 +2. JWT 서명 및 claim 검증 +3. `sid` 또는 `sub`로 로컬 세션 탐색 +4. 세션 스토어에서 직접 세션 파기 +5. 성공 시 `2xx` 응답 + +을 수행해야 합니다. + +### 3. `logout_token` 검증 + +RP는 Baron이 노출하는 Back-Channel Logout JWKS로 `logout_token`을 검증해야 합니다. + +현재 Baron의 JWKS endpoint 예시는 다음과 같습니다. + +```text +GET /api/v1/auth/backchannel/jwks.json +``` + +검증 필수 항목: + +1. JWT 서명 검증 +2. `iss`가 Baron OIDC issuer와 일치 +3. `aud`에 현재 RP `client_id` 포함 +4. `iat` 존재 +5. `jti` 존재 +6. `events`에 `http://schemas.openid.net/event/backchannel-logout` 포함 +7. `nonce`가 없어야 함 +8. `sid` 또는 `sub`가 있어야 함 + +추가 권장 항목: + +- `jti` replay 방지 캐시 +- 시계 오차 허용 범위 설정 +- 검증 실패 시 `400` + +## 세션 종료 기준 + +### 권장 순서 + +1. `sid`로 매칭 시도 +2. 매칭 실패 시 `sub`로 fallback + +이 기준은 `SID Claim Required` 정책에 따라 달라집니다. + +### `SID Claim Required = true` + +- `logout_token`에 `sid`가 있어야만 처리 +- `sub` fallback 금지 +- 세션 모델이 `sid` 중심으로 안정적으로 유지되는 RP에 적합 + +### `SID Claim Required = false` + +- `sid`가 있으면 우선 사용 +- `sid` 매칭이 안 되거나 `sid`가 없어도 `sub`로 fallback 가능 +- 실제 운영에서는 이 모드가 더 현실적일 수 있음 + +## 세션 파기 방식 + +`Back-Channel Logout`에서는 현재 브라우저 요청의 `req.session.destroy()`로는 부족합니다. +반드시 **세션 스토어에서 session id를 찾아 직접 파기**해야 합니다. + +예: + +```text +store.destroy(rpSessionId) +``` + +필수 조건: + +- 로그아웃 대상 세션 ID를 매핑 테이블에서 찾을 수 있어야 함 +- 이미 삭제된 세션은 idempotent success 처리 + +## 권장 로그 항목 + +RP는 아래 정도의 로그를 남기는 것을 권장합니다. + +1. 요청 수신 +2. 토큰 검증 성공/실패 +3. `sid`, `sub`, `jti` +4. 매칭된 `rpSessionId` 목록 +5. 세션 파기 성공/실패 수 + +예시: + +```text +[백채널 로그아웃] 요청 수신 +[백채널 로그아웃] 토큰 검증 성공 +[백채널 로그아웃] 세션 탐색 결과 +[백채널 로그아웃] 세션 파기 완료 +[백채널 로그아웃] 처리 완료 +``` + +주의: + +- raw `logout_token` 전체를 로그에 남기지 않습니다. +- access token, refresh token, cookie raw value도 남기지 않습니다. + +## 테스트 체크리스트 + +### 기본 성공 시나리오 + +1. PKCE RP 로그인 +2. callback 후 `sid/sub -> rpSessionId` 매핑 생성 확인 +3. UserFront에서 `세션 종료` +4. Baron이 RP의 `Back-Channel Logout URI`로 POST +5. RP가 `logout_token` 검증 성공 +6. RP 세션 파기 성공 +7. 보호 페이지 접근 시 비로그인 상태 확인 + +### 확인 포인트 + +1. devfront에 `Back-Channel Logout URI`가 실제 저장됐는가 +2. Baron backend가 해당 URI에 실제로 도달 가능한가 +3. RP 로그에 `요청 수신`과 `토큰 검증 성공`이 찍히는가 +4. 세션 스토어에서 실제 세션이 삭제됐는가 +5. `SID Claim Required=true`일 때와 `false`일 때 결과가 의도대로 다른가 + +## 구현 예시 구조 + +Node.js/Express 기준 최소 구조 예시는 다음과 같습니다. + +```text +GET /login +GET /callback +GET /profile +GET /logout +POST /backchannel-logout +``` + +내부 저장 예시: + +```text +sidToSessionIds: Map> +subToSessionIds: Map> +sessionIdToBinding: Map +``` + +실제 분리 예시는 아래 데모 코드를 참고할 수 있습니다. + +- 백채널 로그아웃 모듈: `https://gitea.hmac.kr/kyy/pkce-login-demo/src/branch/main/backchannel-logout.js` +- 데모 앱 엔트리포인트: `https://gitea.hmac.kr/kyy/pkce-login-demo/src/branch/main/app.js` + +이 데모는: + +1. callback 이후 `registerSessionBinding()`으로 `sid/sub -> sessionId`를 등록 +2. `POST /backchannel-logout`에서 `handleBackchannelLogout`를 그대로 연결 +3. 로컬 `/logout` 또는 세션 정리 시 `removeSessionBinding()` 호출 + +구조로 동작합니다. + +## 자주 생기는 문제 + +### 1. `localhost`로는 안 되는데 입력은 저장됨 + +입력 validation을 통과하는 것과 Baron backend가 실제로 그 주소에 도달하는 것은 다릅니다. + +예: + +```text +http://localhost:3333/backchannel-logout +``` + +이 값은 backend 컨테이너 기준으로는 자기 자신을 가리킬 수 있습니다. Docker 환경에서는 Docker 서비스명 또는 사설 IP를 사용해야 할 수 있습니다. + +### 2. `sid`가 로그인 시 값과 다름 + +실제 운영에서는 `logout_token.sid`가 RP가 저장한 `sid`와 항상 같다고 가정하면 안 됩니다. + +따라서: + +1. `sid` 우선 +2. `sub` fallback + +구현을 권장합니다. 다만 보안 정책상 `SID Claim Required=true`를 선택한 경우에는 fallback 없이 `sid`만 사용해야 합니다. + +### 3. 순수 frontend-only PKCE인데 endpoint를 만들 수 없음 + +그 경우는 `Back-Channel Logout` 자체를 구현할 수 없습니다. 최소한 logout 수신용 서버 컴포넌트를 추가해야 합니다. + +## 로직 흐름 + +```mermaid +sequenceDiagram + autonumber + participant Browser as 브라우저 + participant RP as PKCE RP + participant Baron as Baron SSO + participant Store as 세션 스토어 + + Browser->>RP: GET /login 호출 + RP->>Browser: Baron authorize endpoint로 리다이렉트 + Browser->>Baron: Authorization Code + PKCE 로그인 + Baron->>Browser: /callback?code=... 으로 리다이렉트 + Browser->>RP: GET /callback 호출 + RP->>Baron: code_verifier 포함 token 요청 + Baron-->>RP: ID Token / Access Token 반환 + RP->>Store: RP 세션 생성 + RP->>RP: registerSessionBinding(sessionId, sid, sub) + RP-->>Browser: 로그인 완료 응답 + + Browser->>Baron: UserFront 또는 연동 서비스에서 세션 종료 + Baron->>RP: POST /backchannel-logout (logout_token) + RP->>Baron: Back-Channel JWKS로 logout_token 검증 + Baron-->>RP: 서명 / issuer / audience 검증 기준 제공 + RP->>RP: sid 또는 sub로 sessionId 탐색 + RP->>Store: destroy(sessionId) + RP->>RP: removeSessionBinding(sessionId) + RP-->>Baron: 200 OK + + Browser->>RP: GET /profile 호출 + RP-->>Browser: 루트 리다이렉트 또는 비로그인 응답 +``` + +## 권장 결론 + +PKCE RP에서 `Back-Channel Logout`을 쓰려면, 다음 원칙을 따르십시오. + +1. PKCE 로그인 플로우는 그대로 유지 +2. logout 수신용 서버 endpoint 별도 구현 +3. `sid`와 `sub`를 모두 저장 +4. 세션 스토어에서 직접 세션 파기 +5. 로컬 개발 시 Baron backend가 도달 가능한 URI를 사용 + +이 다섯 가지가 갖춰져야 Baron의 원격 세션 종료가 RP 로컬 세션 종료까지 이어집니다.