배경과 과제
배경
기존 React WebView는 accessToken과 refreshToken을 localStorage에 저장했습니다. 신규 Next.js 웹은 도메인이 달라 이 값을 읽을 수 없었습니다.
신규 Next.js 웹은 일반 브라우저에서 쿠키 기반 인증을 쓰고 있었습니다. 서버가 refreshToken을 httpOnly 쿠키로 설정하고 401이 나면 서버가 그 쿠키로 토큰을 재발급하는 구조였습니다.
핵심 과제
도메인이 바뀌어도 기존 사용자가 다시 로그인하지 않도록, 기존 토큰을 신규 WebView로 넘겨야 했습니다.
설계 시 고려한 점
- Same-Origin 정책 때문에 신규 도메인에서 기존 localStorage를 직접 읽을 수 없었습니다.
- 앱 WebView에서는 서버의 setCookie가 안정적으로 반영되지 않았습니다. 쿠키에 refreshToken이 없으면 서버가 토큰을 재발급할 수 없었습니다.
운영 제약
- 기존 사용자를 일괄 로그아웃하지 않아야 했습니다.
- 백엔드의 토큰 발급과 재발급 규칙은 그대로 유지해야 했습니다.
- 같은 사이트가 일반 브라우저에서도 동작해야 했기 때문에 인증 흐름을 앱 전용으로 따로 만들지 않아야 했습니다.
- 신규 앱이 배포되기 전에 기존 React WebView 사용자의 토큰이 앱 저장소에 먼저 옮겨져 있어야 했습니다.
도메인 전환을 위한 인증 이관 흐름
앱 저장소를 거쳐 신규 도메인의 쿠키로 토큰 이관
기존 웹이 운영되는 동안 토큰을 앱 저장소로 옮겨 두고 신규 웹에서는 앱이 그 토큰을 WebView 쿠키에 설정했습니다. 이후 재발급은 일반 브라우저와 같은 서버 경로를 씁니다.
인증 전환 결과
- 사용자
- 앱 저장소에 토큰이 옮겨진 사용자는 도메인이 바뀐 뒤에도 다시 로그인하지 않고 서비스를 이어갈 수 있게 했습니다.
- 개발
- 앱 WebView도 쿠키에 토큰을 두게 되면서 401 재발급과 서버 렌더링 전 토큰 확인을 일반 브라우저와 같은 서버 경로로 처리했습니다.
- 협업
- 브릿지 규격과 다섯 가지 시나리오를 문서로 먼저 정리해 웹과 앱이 같은 기준으로 구현하고 확인할 수 있었습니다.
핵심 구현과 판단
1. 신규 앱 배포 전에 기존 WebView에서 토큰 선적재
기존 React WebView에 토큰 전달 코드를 먼저 배포했습니다. 로그인한 사용자가 WebView를 열면 localStorage의 accessToken과 refreshToken을 setTokens 브릿지로 앱 저장소에 보냈습니다.
- 로그아웃할 때는 clearTokens를 호출해 종료한 세션이 신규 WebView에서 되살아나지 않게 했습니다.
주요 예외 처리
쿠키를 설정하는 주체만 환경별로 나누고 재발급과 로그아웃 규칙은 같게 유지했습니다.
앱 저장소에 토큰이 없는 경우 (선행 배포 기간에 기존 WebView를 열지 않은 사용자)
- 처리
- 토큰이 비어 있으면 쿠키 저장과 새로고침을 하지 않고 비로그인 상태로 시작합니다.
- 결과
- 새로고침이 반복되지 않고 사용자는 새로 로그인할 수 있습니다.
앱 저장소의 토큰이 오래된 경우
- 처리
- 유효 기간의 절반을 넘겼으면 진입 시점에 미리 재발급하고 앱 저장소도 새 토큰으로 바꿉니다.
- 결과
- 다음 진입 때 만료가 가까운 토큰을 다시 쓰지 않습니다.
앱 WebView에서 API가 401을 받은 경우
- 처리
- 서버가 쿠키의 refreshToken으로 재발급하고 앱이면 setTokensInCookie로 쿠키를 다시 설정합니다.
- 결과
- 서버의 setCookie가 반영되지 않아도 새 토큰이 쿠키에 남습니다.
추가 예외 처리 3개
서버 렌더링 시점에 accessToken 쿠키가 없는 경우
- 처리
- middleware에서 refreshToken 쿠키로 먼저 재발급합니다.
- 결과
- 서버에서 페이지를 그릴 때도 로그인 상태를 이어갑니다.
사용자가 로그아웃한 경우
- 처리
- 서버에 쿠키 삭제를 요청하고 clearTokens로 앱 저장소와 WebView 쿠키를 함께 비웁니다.
- 결과
- 다음 앱 실행에서 종료한 로그인이 되살아나지 않습니다.
앱이 아닌 일반 브라우저에서 사용하는 경우
- 처리
- 브릿지를 호출하지 않고 기존처럼 서버가 쿠키를 관리합니다.
- 결과
- 앱 대응이 브라우저의 로그인과 재발급에 영향을 주지 않습니다.
회고
앱에서 받은 refreshToken은 쿠키에 저장되기 전까지 잠깐 WebView의 JavaScript를 거칩니다. 앱이 직접 재발급하고 웹에는 accessToken만 넘기는 구조였다면 노출 범위를 더 줄일 수 있었습니다.
선행 배포 기간에 기존 WebView를 열지 않은 사용자는 앱 저장소에 토큰이 없어 다시 로그인해야 했습니다. 이 범위를 이관의 경계로 두었습니다.
토큰 만료와 재발급 경로는 유효 시간을 줄인 테스트 빌드로 앱에서 직접 반복 확인했습니다. 이 확인 과정을 자동화 테스트로 남기면 이후 변경에도 같은 경로를 반복해서 검증할 수 있습니다.