# Back-Channel Logout 통합 가이드

이 문서는 Baron SSO와 연동하는 RP들이 `Back-Channel Logout`을 어떻게 처리하는지 한 곳에서 정리합니다.

핵심은 다음 두 가지입니다.

1. Baron SSO가 RP로 보내는 요청 형식은 공통입니다.
2. RP가 그 요청을 받아 세션을 찾고 지우는 내부 로직은 RP 유형에 따라 달라질 수 있습니다.

## 결론

Baron SSO는 모든 RP에 대해 같은 방식으로 `POST /backchannel-logout`를 보냅니다.

- `Content-Type: application/x-www-form-urlencoded`
- body: `logout_token=<jwt>`
- 검증용 공개키는 `GET /api/v1/auth/backchannel/jwks.json`

차이는 Baron이 보낸 뒤 RP 내부에서 세션을 어디서 찾고 어떻게 파기하느냐입니다.

- `PKCE RP`
- `server-side-app RP`
- `headless login RP`는 `PKCE` 기반 custom login UI 변형

## 공통 시퀀스

아래 흐름은 세 RP에 공통입니다.

```mermaid
sequenceDiagram
    autonumber
    participant Baron as Baron SSO
    participant RP as RP
    participant JWKS as Baron Back-Channel JWKS
    participant Store as RP Session Store

    Baron->>RP: POST /backchannel-logout\nlogout_token=<jwt>
    RP->>RP: logout_token 추출
    RP->>JWKS: JWKS로 서명 검증
    JWKS-->>RP: public key
    RP->>RP: iss / aud / events / nonce / jti 검증
    RP->>RP: sid 또는 sub로 세션 탐색
    RP->>Store: session destroy
    Store-->>RP: 삭제 완료
    RP->>RP: 세션 매핑 제거
    RP-->>Baron: 200 OK
```

## 공통 전송 규칙

Baron SSO에서 RP로 보내는 형식은 동일합니다.

| 항목 | 값 |
| --- | --- |
| HTTP method | `POST` |
| Path | `/backchannel-logout` |
| Content-Type | `application/x-www-form-urlencoded` |
| Body | `logout_token=<jwt>` |
| 검증 JWKS | `/api/v1/auth/backchannel/jwks.json` |

전송 로직은 Baron 쪽에서 공통으로 처리됩니다.

- [`backend/internal/service/backchannel_logout_service.go`](/home/kyy/workspace/baron-sso/backend/internal/service/backchannel_logout_service.go)
- [`backend/internal/handler/auth_handler.go`](/home/kyy/workspace/baron-sso/backend/internal/handler/auth_handler.go)

## RP별 차이

세 RP는 모두 `logout_token`을 받아 검증하고 세션을 지운다는 점은 같습니다.
다만 세션이 만들어지는 시점과 저장 방식이 다릅니다.

| 항목 | PKCE RP | server-side-app RP | headless login RP |
| --- | --- | --- | --- |
| 로그인 성격 | Authorization Code + PKCE | confidential client | PKCE 기반 custom login UI |
| 백채널 수신 endpoint | 필요 | 필요 | 필요 |
| 세션 저장 구조 | 앱 서버/BFF/브라우저 연동에 따라 다양 | 서버 세션 중심 | headless 로그인 이후 로컬 세션 바인딩 |
| `sid/sub` 매핑 | callback 이후 저장 | callback 이후 저장 | login 성공 이후 저장 |
| 세션 파기 방식 | 매핑된 session id 삭제 | 매핑된 session id 삭제 | 매핑된 session id 삭제 |
| 차이의 핵심 | 서버 endpoint가 없으면 처리 불가 | 서버 세션 구조와 잘 맞음 | 로그인 진입점만 다르고 로그아웃 처리는 공통 패턴 |

## RP별 처리 설명

### PKCE RP

PKCE RP는 브라우저 기반 로그인 흐름을 사용하지만, 백채널 로그아웃을 받으려면 **반드시 서버 endpoint**가 있어야 합니다.

이유는 Baron이 브라우저가 아니라 RP 서버로 직접 `POST`를 보내기 때문입니다.

처리 순서:

1. callback 이후 `sid` 또는 `sub`를 RP 세션과 바인딩합니다.
2. Baron이 `POST /backchannel-logout`를 보냅니다.
3. RP가 `logout_token`을 검증합니다.
4. `sid` 우선, 실패 시 `sub`로 세션을 찾습니다.
5. 세션 스토어에서 해당 세션을 삭제합니다.

주의:

- 순수 frontend-only PKCE 앱은 백채널 로그아웃을 직접 받을 수 없습니다.
- 서버나 BFF가 있어야 합니다.

### server-side-app RP

server-side-app RP는 confidential client이므로, 서버 세션 구조와 백채널 로그아웃이 자연스럽게 맞습니다.

처리 순서:

1. OIDC Authorization Code 로그인과 callback을 처리합니다.
2. callback 이후 `sid` 또는 `sub`를 서버 세션과 바인딩합니다.
3. Baron이 `POST /backchannel-logout`를 보냅니다.
4. RP가 `logout_token`을 검증합니다.
5. 세션 매핑을 찾아 직접 파기합니다.

이 유형은 PKCE보다 세션 관리가 명확해서 문서화와 운영이 단순합니다.

### headless login RP

headless login은 별도의 로그아웃 타입이 아니라 PKCE 계열의 로그인 변형입니다.

즉, 로그인 시에는 custom login UI가 있고 RP backend가 headless login API를 호출하지만, 백채널 로그아웃은 결국 동일한 패턴으로 처리합니다.

처리 순서:

1. headless login 성공 후 `sid` 또는 `sub`를 RP 세션에 바인딩합니다.
2. Baron이 `POST /backchannel-logout`를 보냅니다.
3. RP가 `logout_token`을 검증합니다.
4. `sid` 또는 `sub`로 세션을 찾습니다.
5. 세션 스토어에서 해당 세션을 삭제합니다.

핵심은 로그인 진입점만 다르고, 로그아웃 처리 패턴은 PKCE RP와 같습니다.

## 공통 검증 규칙

RP는 아래 항목을 검증해야 합니다.

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`

## 세션 파기 규칙

`Back-Channel Logout`은 현재 브라우저 요청의 `req.session.destroy()`만으로는 부족합니다.

반드시 세션 저장소에서 실제 세션 id를 찾아 직접 파기해야 합니다.

권장 우선순위:

1. `sid`로 탐색
2. `sid`가 없거나 매칭 실패 시 `sub`로 fallback

## 공통 테스트 포인트

1. RP 로그인 후 `sid/sub -> sessionId` 매핑이 생성되는지 확인
2. Baron이 `POST /backchannel-logout`를 실제로 보내는지 확인
3. RP가 `logout_token`을 검증하는지 확인
4. 세션 스토어에서 세션이 삭제되는지 확인
5. 동일한 `logout_token` 재전송 시 replay 방지가 동작하는지 확인

## 관련 문서

- [`docs/pkce-backchannel-logout-guide.md`](/home/kyy/workspace/baron-sso/docs/pkce-backchannel-logout-guide.md)
- [`docs/server-side-app-backchannel-logout-guide.md`](/home/kyy/workspace/baron-sso/docs/server-side-app-backchannel-logout-guide.md)

## 참고 구현

- [`backend/internal/service/backchannel_logout_service.go`](/home/kyy/workspace/baron-sso/backend/internal/service/backchannel_logout_service.go)
- [`backend/internal/handler/auth_handler.go`](/home/kyy/workspace/baron-sso/backend/internal/handler/auth_handler.go)