246 lines
13 KiB
Markdown
246 lines
13 KiB
Markdown
# 세션 연장 Confirm 적용 가이드
|
|
|
|
## 1) 문서 목적
|
|
|
|
JWT 만료 **5분 전**에 `"로그인을 연장하시겠습니까?"` confirm 창을 띄우고, 사용자 선택에 따라 세션을 연장하거나 자동 갱신을 중단하는 기능을 서비스 앱에 적용하기 위한 가이드입니다.
|
|
|
|
이 문서는 [서비스별 인증 처리 리팩토링 가이드](./auth-service-refactoring-guide.md)의 **후속 단계**로 읽습니다.
|
|
`@common/auth` 기반 `authService` + `token-manager` + `AuthWrapper` 패턴이 먼저 갖춰져 있어야 합니다.
|
|
|
|
## 2) 선행 조건
|
|
|
|
아래 항목이 완료된 서비스만 이 가이드를 적용합니다.
|
|
|
|
| 항목 | 확인 |
|
|
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
| `createTokenManager(authConfig)` 사용 | [3-3. 토큰 매니저 공통화](./auth-service-refactoring-guide.md) |
|
|
| `authService.login` / `silentRefresh`에서 `getRemainingMs` + `setupRefreshTimer` | [3-4. 로그인 성공 처리 표준화](./auth-service-refactoring-guide.md) |
|
|
| `authService.declineSessionExtend` 구현 | confirm 취소 시 refresh 타이머 해제 |
|
|
| `AuthWrapper`에서 새로고침 시 refresh 타이머 복구 | cs / as / st 참고 |
|
|
| `ConfirmProvider` + `ConfirmDialog` 마운트 | AppProvider |
|
|
| `ConfirmProvider` **하위**에 `BaseLayout` → `Header` 렌더링 | `useConfirm` 사용 조건 |
|
|
| `BaseLayout`에 `authService` prop 전달 | Header까지 전달됨 |
|
|
|
|
**적용 완료 앱**: `cs`, `as`, `st`
|
|
**미적용**: `wr`, `sn`, `fo` 등 legacy `LoginApi` 패턴 앱
|
|
|
|
## 3) 전체 흐름
|
|
|
|
로그인 이후 JWT `exp`를 기준으로 **두 개의 독립 타이머**가 동작합니다.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Login as authService.login
|
|
participant RefreshTimer as refreshTimer
|
|
participant Header as Header
|
|
participant User as 사용자
|
|
participant API as authService.silentRefresh
|
|
|
|
Login->>RefreshTimer: setupRefreshTimer(exp - 1분)
|
|
Header->>Header: confirm 예약(exp - 5분)
|
|
Note over Header: 만료 5분 전
|
|
Header->>User: 로그인을 연장하시겠습니까?
|
|
alt 확인
|
|
User->>API: silentRefresh()
|
|
API->>RefreshTimer: 새 토큰 기준 타이머 재설정
|
|
Header->>Header: confirm 타이머 재설정
|
|
else 취소
|
|
Header->>API: declineSessionExtend()
|
|
API->>RefreshTimer: clearRefreshTimer()
|
|
Note over RefreshTimer: 취소시 만료까지 자동 갱신 없음
|
|
end
|
|
```
|
|
|
|
| 시점 | 동작 | 담당 |
|
|
| --------------------------- | ------------------------------------- | ------------------------------------------- |
|
|
| 로그인 / silentRefresh 성공 | 만료 1분 전 자동 `silentRefresh` 예약 | `authService` → `setupRefreshTimer` |
|
|
| 만료 5분 전 | confirm 표시 | `Header` → `useSessionExtendConfirm` |
|
|
| confirm **확인** | 즉시 `silentRefresh` + 타이머 재설정 | Header → `authService.silentRefresh` |
|
|
| confirm **취소** | 자동 `silentRefresh` 타이머 해제 | Header → `authService.declineSessionExtend` |
|
|
|
|
### 3-1. 시간 계산 (`getRemainingMs`)
|
|
|
|
`[packages/common/auth/jwt-utils.ts](../packages/common/auth/jwt-utils.ts)`
|
|
|
|
```typescript
|
|
export const REFRESH_BUFFER_MS = 60_000; // silent refresh: 만료 1분 전
|
|
export const SESSION_EXTEND_CONFIRM_BUFFER_MS = 5 * 60_000; // confirm: 만료 5분 전
|
|
|
|
getRemainingMs(token); // → refresh 타이머 delay
|
|
getRemainingMs(token, SESSION_EXTEND_CONFIRM_BUFFER_MS); // → confirm 타이머 delay
|
|
getRemainingMs(token, 0) > 0; // → 토큰 미만료 여부
|
|
```
|
|
|
|
`bufferMs` 인자 하나로 용도를 구분합니다. 기존 `getRemainingMs(token)` 호출부는 변경하지 않아도 됩니다.
|
|
|
|
## 4) 공통 모듈 변경 사항
|
|
|
|
### 4-1. `@common/auth` — `AuthService` / `clearRefreshTimer`
|
|
|
|
`[packages/common/auth/types.ts](../packages/common/auth/types.ts)`
|
|
|
|
```typescript
|
|
export interface AuthService {
|
|
login(payload: AuthPayload): Promise<void>;
|
|
silentRefresh(): Promise<void>;
|
|
declineSessionExtend(): void; // confirm 취소 시 refresh 타이머 해제
|
|
logout(): Promise<void>;
|
|
}
|
|
```
|
|
|
|
`[packages/common/auth/token-manager.ts](../packages/common/auth/token-manager.ts)`
|
|
|
|
- `setupRefreshTimer`: 만료 1분 전 `silentRefresh` 예약 (기존)
|
|
- `clearRefreshTimer`: 예약된 refresh 타이머 해제 (신규)
|
|
- `clearAuthToken`: 내부에서 `clearRefreshTimer` 호출
|
|
|
|
`refreshTimer`는 `createTokenManager()` 클로저 안의 **앱당 싱글톤** 변수입니다.
|
|
`authService.declineSessionExtend()`가 내부에서 `clearRefreshTimer()`를 호출하므로, Header는 token-manager를 직접 import하지 않습니다.
|
|
|
|
### 4-2. `@common/components` — Header + `useSessionExtendConfirm`
|
|
|
|
`[packages/common/components/src/ui/header/index.tsx](../packages/common/components/src/ui/header/index.tsx)`에서 훅을 실행합니다.
|
|
|
|
```typescript
|
|
useSessionExtendConfirm({
|
|
enabled:
|
|
mounted &&
|
|
isLoggedIn &&
|
|
!viewOnly &&
|
|
!!authService &&
|
|
!isAtLoginRedirectUrl(getAuthLoginRedirectUrl()),
|
|
getAccessToken: () => getCookie(appConfig.CLAIM_NAME ?? ""),
|
|
silentRefresh: authService.silentRefresh,
|
|
clearRefreshTimer: authService.declineSessionExtend,
|
|
});
|
|
```
|
|
|
|
| enabled 조건 | 이유 |
|
|
| ---------------------------- | ------------------------------- |
|
|
| `mounted` | hydration 후 타이머 시작 |
|
|
| `isLoggedIn` | 비로그인 제외 |
|
|
| `!viewOnly` | `VBaseLayout` 등 조회 전용 제외 |
|
|
| `!!authService` | legacy 앱 자동 비활성 |
|
|
| `!isAtLoginRedirectUrl(...)` | 로그인 페이지 제외 |
|
|
|
|
세션 만료 **카운트다운 UI**와 confirm 로직이 Header에 응집됩니다.
|
|
|
|
## 5) 서비스별 적용 단계
|
|
|
|
### 5-1. `auth-service`에 `declineSessionExtend` 추가
|
|
|
|
`[apps/cs/src/entities/auth/api/auth-service.ts](../apps/cs/src/entities/auth/api/auth-service.ts)` 참고:
|
|
|
|
```typescript
|
|
import { clearRefreshTimer } from "../lib/token-manager";
|
|
|
|
function declineSessionExtend(): void {
|
|
clearRefreshTimer();
|
|
}
|
|
|
|
export const authService: AuthService = {
|
|
login,
|
|
silentRefresh,
|
|
declineSessionExtend,
|
|
logout,
|
|
};
|
|
```
|
|
|
|
### 5-2. `BaseLayout`에 `authService` 전달
|
|
|
|
`[apps/cs/app/(main)/(with-base-layout)/layout.tsx](../apps/cs/app/(main)`/(with-base-layout)/layout.tsx) 참고:
|
|
|
|
```tsx
|
|
<BaseLayout
|
|
queryClient={queryClient}
|
|
authService={authService}
|
|
currentPath={pathname ?? ""}
|
|
handleMenuClick={handleMenuClick}
|
|
>
|
|
```
|
|
|
|
`BaseLayout`은 `authService`를 `Header`에 그대로 전달합니다. **AuthWrapper에서 훅을 연결하지 않습니다.**
|
|
|
|
### 5-3. `AuthWrapper` — refresh 타이머 복구만 유지
|
|
|
|
`[apps/cs/src/entities/auth/lib/auth-wrapper.tsx](../apps/cs/src/entities/auth/lib/auth-wrapper.tsx)`:
|
|
|
|
- `useSessionExtendConfirm` **사용하지 않음**
|
|
- 페이지 새로고침 시 `setupRefreshTimer(authService.silentRefresh, remainingMs)` 복구 유지
|
|
- 인증 체크, `auth:logout` 수신 유지
|
|
|
|
### 5-4. `AppProvider` 구조 확인
|
|
|
|
`[apps/cs/src/app/providers/app-provider.tsx](../apps/cs/src/app/providers/app-provider.tsx)` 참고:
|
|
|
|
```tsx
|
|
<ConfirmProvider>
|
|
<AuthWrapper>
|
|
{children}
|
|
<ConfirmDialog />
|
|
</AuthWrapper>
|
|
</ConfirmProvider>
|
|
```
|
|
|
|
`Header`는 `ConfirmProvider` 하위에서 렌더링되므로 `useConfirm()`이 동작합니다.
|
|
|
|
## 6) 책임 분리 요약
|
|
|
|
| 레이어 | 파일 | 역할 |
|
|
| ------------------ | ------------------------------------ | -------------------------------------------------- |
|
|
| JWT 시간 계산 | `@common/auth` `jwt-utils.ts` | `getRemainingMs`, 버퍼 상수 |
|
|
| refresh 타이머 | `@common/auth` `token-manager.ts` | `setupRefreshTimer`, `clearRefreshTimer` |
|
|
| API 오케스트레이션 | `entities/auth/api/auth-service.ts` | login, silentRefresh, declineSessionExtend, logout |
|
|
| confirm UX | `@common/components` `Header` | 카운트다운 UI + 5분 전 confirm |
|
|
| 앱 진입점 | `entities/auth/lib/auth-wrapper.tsx` | 타이머 복구, auth 체크 |
|
|
| 레이아웃 | `app/.../layout.tsx` | `authService` → `BaseLayout` → `Header` |
|
|
| UI 쉘 | `app/providers/app-provider.tsx` | ConfirmProvider, ConfirmDialog |
|
|
|
|
## 7) 엣지 케이스
|
|
|
|
| 상황 | 동작 |
|
|
| -------------------- | --------------------------------------------------------------- |
|
|
| 토큰 유효 시간 < 5분 | `confirmMs === 0`이면 페이지 진입 즉시 confirm |
|
|
| confirm **취소** | `declineSessionExtend()` + 동일 JWT에 재표시 안 함 |
|
|
| confirm **확인** | `silentRefresh()` → 새 토큰 기준 confirm/refresh 타이머 재설정 |
|
|
| `silentRefresh` 실패 | `authService`가 `auth:logout` 발행 → AuthWrapper 리다이렉트 |
|
|
| 로그아웃 | `clearAuthToken`이 refresh 타이머 정리, 훅 cleanup |
|
|
| `viewOnly` Header | confirm 비활성 |
|
|
| `authService` 미전달 | confirm 비활성 (wr/fo 등) |
|
|
| 페이지 새로고침 | AuthWrapper가 refresh 타이머 복구, Header가 confirm 타이머 복구 |
|
|
|
|
## 8) 적용 체크리스트
|
|
|
|
[리팩토링 가이드 체크리스트](./auth-service-refactoring-guide.md#4-서비스별-적용-체크리스트)에 더해 아래를 확인합니다.
|
|
|
|
- [ ] `auth-service`에 `declineSessionExtend` 구현
|
|
- [ ] `token-manager`에서 `clearRefreshTimer` re-export
|
|
- [ ] `BaseLayout`에 `authService` prop 전달 (→ Header까지)
|
|
- [ ] `ConfirmProvider` > `AuthWrapper` > `BaseLayout` > `Header` 계층 확인
|
|
- [ ] `AuthWrapper`에 `useSessionExtendConfirm` **없음** 확인
|
|
- [ ] 만료 5분 전 confirm 노출 확인
|
|
- [ ] 확인 클릭 시 `SILENT_REFRESH` API 호출 확인
|
|
- [ ] 취소 클릭 시 만료 1분 전 자동 refresh 미발생 확인
|
|
|
|
## 9) 검증 방법
|
|
|
|
1. 로그인 후 JWT `exp`가 5분 이내가 되도록 대기하거나 테스트 토큰 사용
|
|
2. confirm 문구 `"로그인을 연장하시겠습니까?"` 표시 확인
|
|
3. **확인** → Network 탭에서 `SILENT_REFRESH` PUT 호출, 쿠키 갱신, confirm 재예약
|
|
4. **취소** → 만료 1분 전까지 `SILENT_REFRESH` 자동 호출 없음
|
|
5. 취소 후 세션 만료 → 401 / 로그인 리다이렉트
|
|
6. 새로고침 후 refresh·confirm 타이머 복구
|
|
|
|
## 10) 참고 구현
|
|
|
|
| 앱 | Header (공통) | auth-service | BaseLayout layout |
|
|
| --- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
| cs | `[packages/common/components/src/ui/header/index.tsx](../packages/common/components/src/ui/header/index.tsx)` | `[apps/cs/src/entities/auth/api/auth-service.ts](../apps/cs/src/entities/auth/api/auth-service.ts)` | `[apps/cs/app/(main)/(with-base-layout)/layout.tsx](../apps/cs/app/(main)`/(with-base-layout)/layout.tsx) |
|
|
| as | (동일) | `[apps/as/src/entities/auth/api/auth-service.ts](../apps/as/src/entities/auth/api/auth-service.ts)` | `[apps/as/src/app/layouts/base-layout.tsx](../apps/as/src/app/layouts/base-layout.tsx)` |
|
|
| st | (동일) | `[apps/st/src/entities/auth/api/auth-service.ts](../apps/st/src/entities/auth/api/auth-service.ts)` | `[apps/st/app/(main)/(with-base-layout)/layout.tsx](../apps/st/app/(main)`/(with-base-layout)/layout.tsx) |
|
|
|
|
## 11) 관련 문서
|
|
|
|
- [서비스별 인증 처리 리팩토링 가이드](./auth-service-refactoring-guide.md) — 선행 리팩토링
|
|
- `[packages/common/auth/README.md](../packages/common/auth/README.md)` — `getRemainingMs`, token-manager API
|