WEGO ) Next.js 미들웨어를 활용한 유저 인증 플로우 구현

작성일 2025-01-08 In Project Views: Disqus:

웹 애플리케이션에서 인증된 사용자와 비인증 사용자에 대한 페이지 접근 제어는 매우 중요합니다. 특히 사용자 경험(UX)을 해치지 않으면서 안전하게 구현하는 것이 핵심인데요. 이번 글에서는 Next.js의 미들웨어를 활용해 어떻게 더 나은 인증 플로우를 구현했는지 공유하고자 합니다.

▪︎ 기존 인증 구현의 문제점

유저의 인증 여부를 판단하기 위해 token 검증만을 위한 api를 백엔드 측에 요청했습니다. 백엔드 측에서는 요청의 쿠키에서 accessToken을 읽어 그 검증 여부에 따라 결과를 반환해줬습니다. 우리 프론트에서는 인가 필요 페이지에서 그 결과가 성공이면 페이지를 보여주고, 실패면 로그인 페이지로 리다이렉트 시키는 로직이 필요했습니다.

처음에는 컴포넌트 내부에서 api 요청을 하고 그 결과에 따라 리다이렉트 여부를 결정했습니다. 그러나 이 경우 api 요청에 대한 결과를 받는 동안 잠깐동안 페이지의 레이아웃이 보여지는 플리킹 현상이 발생했습니다. 추가로 각 컴포넌트마다 토큰 인증에 따른 리다이렉트 로직을 작성해주어야 했습니다.

▫︎ 깜빡임 현상 (Flash of Unauthorized Content)

// 컴포넌트 내부에서 인증 체크 시 발생하는 문제
const ProtectedPage = () => {
  useEffect(() => {
    // 인증 체크 후 리다이렉트
    if (!isAuthenticated) {
      router.push("/login");
    }
  }, []);

  return <div>보호된 콘텐츠</div>; // 잠깐 보였다가 사라짐
};

▫︎ 중복 코드 발생

// 여러 서버 컴포넌트에서 반복되는 인증 체크 로직
export default async function Page1() {
  const isAuthenticated = await checkAuth();
  if (!isAuthenticated) {
    redirect("/login");
  }
  // ...
}

export default async function Page2() {
  const isAuthenticated = await checkAuth();
  if (!isAuthenticated) {
    redirect("/login");
  }
  // ...
}

▪︎ 미들웨어를 활용한 해결 방안

▫︎ 중앙 집중화된 인증 로직

미들웨어의 가장 큰 장점은 모든 페이지 요청에 대해 선제적으로 실행된다는 점입니다. 이를 활용하여 인증 로직을 중앙에서 관리할 수 있습니다.

// middleware.ts
export const middleware = (request: NextRequest) => {
  // 정적 파일 요청은 미들웨어 처리하지 않음
  if (
    request.nextUrl.pathname.startsWith("/_next") ||
    request.nextUrl.pathname.includes("/api/") ||
    request.nextUrl.pathname.match(/\.(ico|png|svg|jpg|jpeg|gif)$/)
  ) {
    return NextResponse.next();
  }

  const response = NextResponse.next();

  // 로그인 여부에 따라 리다이렉트
  return authRedirect(request, response);
};

여기서 주목할 점은 다음과 같습니다.

성능 최적화: 정적 파일에 대한 요청은 미들웨어를 거치지 않도록 처리했습니다. 이는 불필요한 인증 검사를 줄여 성능을 향상시킵니다.
확장성: authRedirect 함수를 별도로 분리하여, 추후 인증 로직이 변경되거나 추가되어도 유연하게 대응할 수 있습니다.
유지보수성: 인증 관련 로직이 한 곳에 집중되어 있어, 변경이 필요할 때 이 파일만 수정하면 됩니다.

▫︎ 환경별 토큰 검증 전략

개발 환경과 프로덕션 환경에서의 토큰 검증 방식을 분리하여 관리했습니다.

const authRedirect = async (request: NextRequest, response: NextResponse) => {
  const verifyResponse =
    process.env.NODE_ENV === "development" ? await verifyTokenMock(request) : await verifyToken(request);

  // 토큰 유효성 검증이 필요한 페이지 처리
  if ((Object.values(NEED_LOGIN_PATH) as string[]).includes(request.nextUrl.pathname)) {
    if (verifyResponse.status === 200) {
      return response;
    }

    const loginUrl = new URL("/login", request.nextUrl.origin);
    return NextResponse.redirect(loginUrl);
  }

  // 로그인된 사용자가 접근하면 안 되는 페이지 처리
  if ((Object.values(NEED_LOGOUT_PATH) as string[]).includes(request.nextUrl.pathname)) {
    if (verifyResponse.status !== 200) {
      return response;
    }

    const mainUrl = new URL("/", request.nextUrl.origin);
    return NextResponse.redirect(mainUrl);
  }

  return response;
};

환경 분기: process.env.NODE_ENV를 통해 개발/프로덕션 환경을 구분하여 적절한 검증 로직을 실행합니다.
페이지 접근 제어:
- NEED_LOGIN_PATH: 로그인이 필요한 페이지들 (예: 마이페이지, 리뷰 작성 등)
- NEED_LOGOUT_PATH: 비로그인 상태에서만 접근 가능한 페이지들 (예: 로그인, 회원가입)
명확한 리다이렉션: 인증 상태에 따라 적절한 페이지로 리다이렉트합니다.

▫︎ 구현 시 고려 사항

1. 성능 최적화

1
2
3

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};

선택적 실행: 모든 요청이 아닌, 필요한 경로에 대해서만 미들웨어가 실행되도록 설정
정적 리소스 제외: 이미지, 스타일시트 등 정적 리소스는 미들웨어 처리에서 제외

2. 서버 컴포넌트 지원

const setPathnameHeader = (request: NextRequest, response: NextResponse) => {
  response.headers.set("x-pathname", request.nextUrl.pathname);
  return response;
};

경로 정보 전달: 서버 컴포넌트에서 현재 경로 정보가 필요한 경우를 위해 헤더에 포함
확장성: 추후 서버 컴포넌트에서 필요한 추가 정보도 헤더를 통해 전달 가능

▪︎ 미들웨어의 Edge Runtime을 고려한 모킹 시스템

Next.js 미들웨어는 Edge Runtime에서 실행되기 때문에, api 모킹을 위해 개발 환경에서 사용하고 있던 MSW와 같은 모킹 도구를 사용할 수 없었습니다. 이를 해결하기 위한 전용 모킹 시스템을 구현했습니다.

// middleware-mock.ts

export const mockResponses = {
  "/auth/token/verify": {
    success: {
      status: 200,
      body: { ok: true, message: "Token is valid" },
    },
    error: {
      status: 401,
      body: { ok: false, message: "Unauthorized" },
    },
  },
};

export const mockFetch = async (url: string, options?: RequestInit) => {
  const endpoint = new URL(url).pathname;
  const mock = mockResponses[endpoint as keyof typeof mockResponses];

  if (!mock) {
    return fetch(url); // 모킹되지 않은 엔드포인트는 실제 요청 수행
  }

  const cookies = options?.headers && "Cookie" in options.headers ? options.headers.Cookie : "";
  const hasAccessToken = cookies.includes("accessToken=");

  // 쿠키의 토큰 존재 여부에 따라 적절한 응답 반환
  return new Response(JSON.stringify(hasAccessToken ? mock.success.body : mock.error.body), {
    status: hasAccessToken ? mock.success.status : mock.error.status,
    headers: { "Content-Type": "application/json" },
  });
};

▫︎ 모킹 시스템의 주요 특징:

엔드포인트 기반 모킹: 각 엔드포인트별로 성공/실패 응답을 미리 정의합니다.
토큰 기반 응답: 쿠키의 토큰 존재 여부에 따라 다른 응답을 반환합니다.
유연한 확장: 새로운 엔드포인트 추가가 용이한 구조입니다.
폴백 메커니즘: 모킹되지 않은 엔드포인트는 실제 API를 호출합니다.
이러한 모킹 시스템의 장점:
- 개발 효율성: 백엔드 API 완성 전에도 프론트엔드 개발 진행 가능
- 안정성: 예측 가능한 응답으로 일관된 개발 환경 제공
- 디버깅 용이성: 인증 관련 문제 발생 시 빠른 원인 파악 가능

▪︎ 마치며

Next.js의 미들웨어를 활용한 인증 플로우 구현은 단순히 기능적인 요구사항을 충족시키는 것을 넘어, 사용자 경험과 코드 품질 모두를 개선하는 결과를 가져왔습니다. 특히 페이지 전환 시의 깜빡임 현상 제거와 인증 로직의 중앙 집중화는 프로젝트의 품질을 한 단계 높이는 중요한 요소가 되었습니다.

앞으로도 사용자 경험을 해치지 않으면서도 안전한 인증 시스템을 구축하기 위한 고민을 계속해 나갈 예정입니다.