401 Unauthorization 에러의 원인 찾기

 

요약
middleware - bff - vercel - backend 체크하다 vercel env에서 문제를 발견함

목차

1. 상황: 로컬에서는 로그인이 잘되는데 배포본에서는 안된다

2. 현재의 인증 흐름 정리하기

3. 문제 발생 지점 확인하기 - middleware, serverApiClient

4. Sentry 연동하기

5. Vercel env 값 확인하기

6. 배운 것

---

1. 상황: 로컬에서는 로그인이 잘되는데 배포본에서는 안된다.

구글 OAuth 로그인 후 배포주소로 백에서 리다이렉트 되는 것을 수정이 불가능하다 하여

프론트에서는 백엔드로부터 전달받은 Docker로 http:localhost:8080에서 테스트를 하며 개발을 쭉 하고 있었다.

 

백엔드 문제로 배포주소에서 로그인만 하면 튕기다가 그게 해결이 돼서 드디어 로그인이 완성됐나 했더니

로그인하여 메인 페이지로 이동했는데 401 Unauthorization 에러가 발생하는 것을 확인했다.

 

프론트와 백엔드 모두 원인을 못찾고 있는 상황..

 

---

2. 현재의 인증 흐름 정리하기

현재 인증 흐름을 우선 다시 한 번 정리해보자.

시간이 없어 아직 블로그에 정리하지는 못했지만 우리 팀은 BFF(Backend For Frontend) 패턴 + middleware를 사용하고 있다.

브라우저 → Next.js BFF(Route Handler) → 외부 백엔드(api.linkiving.com)

 

1단계 - 로그인 버튼 클릭

유저가 로그인 버튼을 클릭하면 브라우저 상에서 백엔드의 엔드포인트로 직접 이동한다.

https://api.linkiving.com/oauth2/authorization/google

 

2단계 - Google OAuth 처리 (백엔드 딴에서 진행)

백엔드에서(api.linkiving.com) Google 인정 서버로 리디렉션하여 Google 로그인 및 동의를 완료한다.

사용자가 인증을 완료하면 Google에서 백엔드 callback url로 인증 코드를 전달한다.

백엔드는 인증 코드로 Google로부터 유저 정보를 획득하고, accessToken, refreshToken을 발급한다.

 

3단계 - 백엔드가 쿠키에 토큰을 심어서 프론트로 보냄

백엔드가 Cookie에 발급한 토큰을 심어서 프론트 페이지로 보낸다.

이 때 토큰은 HttpOnly 쿠키로, 브라우저 JS에서 직접 접근할 수 없다.

 

4단계 - middleware 통과

/home 페이지를 요청하면 미들웨어가 accessToken의 존재를 확인하여 토큰이 존재하면 /home으로, 존재하지 않으면 로그인페이지로 리디렉션 시킨다.

 

5단계 - 인증된 API 요청 및 응답

브라우저는 이제 발급받은 토큰에서 쿠키를 꺼내 사용한다.

BFF를 거쳐서 백엔드에게 요청을 보낼 때 serverApiClient가 쿠키로부터 토큰을 읽고,
헤더 Authorization에 토큰을 첨부해서 요청한다.

 

백엔드는 요청 헤더의 토큰을 확인해서 응답을 보낸다.

 

---

3. 문제 발생 지점 확인하기 - middleware, serverApiClient

1. middleware

import { COOKIES_KEYS } from '@/lib/constants/cookies';	// 쿠키에 삽입된 토큰명 정의
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const publicRoutes = ['/'];
export function middleware(req: NextRequest) {
  const token = req.cookies.get(COOKIES_KEYS.ACCESS_TOKEN)?.value;	// 쿠키에서 ACCESS_TOKEN 값 읽어옴
  const { pathname } = req.nextUrl;

  if (publicRoutes.includes(pathname)) {
    if (token) {	// 토큰이 있을 경우
      return NextResponse.redirect(new URL('/home', req.url));	// /home으로 이동
    }
    return NextResponse.next();
  }

  if (!token) {	// 토큰이 없을 경우
    const loginUrl = new URL('/', req.url);
    loginUrl.searchParams.set('redirect', pathname);	// /으로 이동
    return NextResponse.redirect(loginUrl);
  }

  return NextResponse.next();
}

// 적용 범위 (api, _next/static, _/next/image, favicon.ico, fonts, images, monitoring(sentry)는 인증 검사 통과
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|fonts|images|monitoring).*)'],
};

일단 미들웨어는 문제 발생 지점이 되지 않는다.

미들웨어는 로그인 후 받은 쿠키에 accessToken이 포함되어있는지를 체크하는 역할을 한다.

/home으로 넘어간 시점에서 프론트는 토큰이 포함된 쿠키를 받았다는 의미가 되기 때문이다.

 

 

2. server/apiClient.ts

serverApiClient는 좀 더 주목할만한 코드이다.

프론트는 토큰을 가지고 있고, 여기서 쿠키를 꺼내서 백엔드 요청에 같이 넘겨야하는데 그 어딘가에서 토큰이 없어지고 있기 때문이다.

import { createFetchError } from '@/hooks/util/api/error/errors';
import { COOKIES_KEYS } from '@/lib/constants/cookies';
import { cookies } from 'next/headers';

import { ApiError } from '../errors/ApiError';

const API_BASE_URL = process.env.NEXT_PUBLIC_BASE_API_URL; // TODO: 환경변수 논의 후 BASE_API_URL로 변경

if (!API_BASE_URL) {
  throw new Error('Missing environment variable: NEXT_PUBLIC_BASE_API_URL');
}

/**
 * 서버 사이드 API 클라이언트
 * Next.js API Routes에서만 사용
 */
export async function serverApiClient<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
  const cookieStore = await cookies(); // await 추가
  const token = cookieStore.get(COOKIES_KEYS.ACCESS_TOKEN)?.value;
  if (!token) {
    throw new ApiError(401, 'No authentication token');
  }

  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
    ...options,
    cache: options.cache ?? 'no-store',
    headers: {
      'Content-Type': 'application/json',
      ...options.headers,
      Authorization: `Bearer ${token}`,
    },
  });

  if (!response.ok) {
    const errorData = await response.json().catch(() => ({}));
    throw createFetchError(errorData.message || `Request failed`, {
      status: response.status,
    });
  }

  return response.json();
}

1. 우선 프론트가 보는 에러 메세지는 아래와 같았다.

 

이는 공통 에러 핸들러에 정의되어 있는 바디 형태로, createFetchError에서 잡히고 있는 에러인 것이다.

그럼 token도 있는데 fetch가 실패한 이유가 뭘까?

 

그걸 위해서 serverApiClient 내부에 콘솔을 찍어봤다.

사실 로직상으로 확인이 가능한 부분이지만 안되니까 직접 찍어서 vercel 로그로 확인해본 결과 역시 endpoint와 token이 정상적으로 출력된다.

 

이후로 백엔드의 postman과 프론트 curl 각각에서 확인해본 결과 양쪽 모두 로컬 테스트로는 잘 되는데 배포주소에서 테스트만 하면 프론트에서는 요청을 분명히 보내고, 백엔드에서는 분명히 요청이 오지도 않는 상황이 계속된다. (사실 경험과 자신이 좀 더 있었으면 여기서 좀 더 실마리를 빠르게 잡을 수 있었을 것 같다.)

 

그렇게 이틀에 걸쳐서 다양한 해석이 나온다.

 

백엔드 2인: 

>> 클라이언트 → next.js Backend → Backend로 요청을 보내기 때문에 요청 URL은 스웨거에 명시된 엔드포인트와 다른게 맞다.

클라이언트가 next.js route가 들어있는 api/links/route.ts로 요청을 보내면 거기서 실제 백엔드 엔드포인트를 호출하기 때문.

여기서 이 친구들이 잠깐 꽤 혼란스러워했는데 이런걸 보면 정말 백과 프론트도 서로의 방식에 대해 어느정도는 아는 것이 좋겠구나 싶었다.

 

미들웨어는 아니니까 넘어가고, me 요청이 된다길래 확인해본 결과, 

저 me에서는 아예 백엔드로 요청을 보내지 않고 있었다. 저 된다는 것은 그냥 200ok를 받는다는 얘기였던듯.

쿠키에서 유저 정보를 바로 읽어오기 때문에 인증을 담은 요청 로직이 없었다.

 

 

클로드 & 나

curl -v https://api.linkiving.com/v1/chats \
  -H "Authorization: Bearer 토큰값

로컬 터미널로 위와 같이 요청 테스트를 하면 응답을 잘 받아온다.

백엔드의 다른 응답 형태에 대해 내가 잘 모르기 때문에 클로드에게 체크 해봤다. 무조건 검색하라고 함

응답 형태 중 Access-Control-Allow-Origin: * 를 짚었다.

allowCredentials: true 와 Access-Control-Allow-Origin: *을 함께 사용하면 브라우저에서 차단될 수 있다는 말이다.

조금 찾아보니까 실제로 있는 경우이길래 백엔드에 확인 요청했다.

 

 

백엔드 마지막 답변

백엔드에서 로깅 작업을 완료한 후, 요청 자체가 안들어온다는 응답을 받았다.

그럼 여기서 드는 의문.. 백엔드에 요청을 안보냈는데 401이라는 응답을 받을 수 있는 것일까..??

그리고 정말 프론트 문제라면 왜 Docker에서 8080과 요청응답을 진행할 때는 왜 잘됐던 걸까??

 

따라서 문제는 프론트에서 백엔드로 요청을 던지고 난 이후 백엔드에 닿기 이전 그 사이에서 발생한다는 생각이 강해졌다.

하지만 혹시 모르니까 더 확실하게 하기 위해 단계적으로 확인해보기로 했다.

 

 

---

4. Sentry 연동 후 체크하기

1. 에러 핸들러에 Sentry 심기

솔직히 말하면 프론트에 문제가 있다고 가정하고 계속 원인을 찾아봤으나, 아무리 생각해도 현재 프론트 코드에서 문제가 없어보였다.

토큰을 받았고, apiServerClient에서 헤더에 토큰을 담아서 BFF 경로로 요청을 보낸다. 그 사이에 다른 문제가 끼어들 틈이 없다.

 

하지만 잘 모르는 일이기에 지금까지 무작정 콘솔을 추가했으나,

감을 못잡는 상황에서 그건 너무 광범위하다는 것을 느껴 Sentry를 연동해보았다.

 

Sentry 프로젝트 추가 후, 자동 세팅으로 진행했고, handleApiError에 Sentry 추적을 심었다.

import { zodErrorToResponse } from '@/hooks/util/zodError';
import { ApiError } from '@/lib/errors/ApiError';
import * as Sentry from '@sentry/nextjs';

import { RequestValidationError } from '../request/requestError';
import { FetchError, ParseError, TimeoutError } from './errors';

export function handleApiError(err: unknown): Response {
  if (err instanceof Error && !('sentryReported' in err)) {
    // 이미 보고된 에러인지 확인
    Sentry.captureException(err);
  }

  if (err instanceof RequestValidationError) {
    return zodErrorToResponse(err.zodError);
  }

  if (err instanceof TimeoutError) {
    return Response.json({ success: false, message: 'Upstream timeout' }, { status: 504 });
  }

  if (err instanceof FetchError) {
    return Response.json(
      { success: false, message: err.message || 'Upstream request failed' },	// 백엔드의 정확한 에러메세지 노출
      { status: err.status ?? 502 }
    );
  }

  if (err instanceof ParseError) {
    return Response.json({ success: false, message: 'Invalid upstream response' }, { status: 502 });
  }

  if (err instanceof ApiError) {
    return Response.json({ success: false, message: err.message }, { status: err.status });
  }

  return Response.json({ success: false, message: 'Internal server error' }, { status: 500 });
}

 

또한 serverApiClient에는 헤더에 Authorization과 쿠키를 제대로 심었는지 체크하기 위해 콘솔을 추가했다.

  console.log('[serverApiClient] Authorization:', headers.get('Authorization')); // TODO: 추후 삭제
  console.log('[serverApiClient] Cookie:', headers.get('Cookie')); // TODO: 추후 삭제

 

 

일단 아쉽게도 Sentry에서는 현재까지 확인한 것 외의 정보를 추가로 확인하지는 못했다.

 

 

2. claude 심기

다음으로 vscode에 claude를 심어서 체크를 해봤다.

I'm getting 401 errors after sending requests. The browser Application tab shows accessToken and refreshToken cookies are present. All request endpoints match the backend configuration.
Please check these folders first: src/apis, app/api, src/lib/server/apiClient.ts, middleware.ts
The backend insists it's a frontend issue. We're using middleware + BFF pattern.
This is a web-only service.

Check if there are any issues in the current code.
In api/member/me/route.ts and api/links/route.ts, the GET requests read cookies directly. This returns HTTP 200 in the response headers, but the actual response body contains an unauthorized error. Other routes using serverApiClient return 401 even in the response headers.
Please suggest a solution.
From Sentry logs, the request to https://api.linkiving.com/v1/links returns 401. The serverApiClient sets both Authorization header and Cookie header before sending to the backend, but the backend logs show "Token not found (missing in both header and cookie)". This suggests the headers are being stripped somewhere between Vercel and the backend server.
We confirmed via Vercel logs that the token exists in the cookie and the Authorization header is correctly set in serverApiClient before the request is sent to the backend. So the issue is not on the Vercel side.

Please answer in Korean.

"프론트 측에서 헤더가 설정된 것이 확인되나, 백엔드에는 헤더가 없다"고 전했다.

사실 백엔드에서 중간중간 헤더 없는 요청을 받았다고는 하나, 결론적으로 실제로 요청 자체를 받지 못했다고 했다.

(걔네가 받은 요청은 뭐였을까)

하지만 일단 이런 패턴의 유력한 원인이 HTTP 리디렉션이라고 한다.

 

serverApiClient에서 fetch를 호출할 때 'redirect' 프로퍼티 값과 관련된 내용이다.

• follow(default): 리다이렉트를 허용(30x)하는데 보안상 토큰을 제거하고 가버림
• manual: 리다이렉트를 허용하지 않고 보고함
• error: 리다이렉트 응답을 에러로 처리

즉, 토큰을 담아서 fetch 요청을 보낸 뒤, 301/302 응답을 받아, node.js fetch가 토큰을 버리고 리디렉션을 따라가서(follow) 헤더가 비었을 수 있다는 것이다.

 

이 부분 확인을 위해서 redirect 값을 'manual'로 수정하고 명시적인 에러 처리 로직을 추가했다.

const response = await fetch(`${API_BASE_URL}${endpoint}`, {
    ...options,
    cache: options.cache ?? 'no-store',
    redirect: 'manual',
    headers,
  });

  // 리디렉션 발생 시 Authorization 헤더가 제거되므로 명시적으로 에러 처리
  if ([301, 302, 303, 307, 308].includes(response.status)) {
    const rawLocation = response.headers.get('location');
    const safeLocation = rawLocation ? new URL(rawLocation, API_BASE_URL) : null;

    console.error('[serverApiClient] Redirect detected', {
      status: response.status,
      location: safeLocation ? `${safeLocation.origin}${safeLocation.pathname}` : null,
    });
    throw createFetchError('Unexpected redirect from upstream API', { status: 502 });
  }

 

3. 원인 발견

수정 후 머지해보니 드디어 402에러를 벗어나서 502에러를 받는 것을 확인할 수 있었다.

이를 통해서 리디렉션이 실제로 발생했음을 알 수 있었다.

curl -v -L"https://api.linkiving.com/v1/links" \
  -H "Authorization: Bearer 토큰값" \
  -H "Content-Type: application/json"

위와 같은 curl의 결과로는 200을 받으므로 백엔드 서버 자체는 정상임에도 불구하고 배포 환경에서 redirect가 감지된다는 것은

프론트와 백엔드 서버 사이 Vercel에 설정된 env 문제일 수 있다.

 

사실 현재 버셀이 무료 플랜이고, 다른 팀원 계정으로 로그인 해서 내가 직접 확인을 못하고 있었다.

마침 팀원이 약속을 나간대서 그냥 내가 직접 로그인해서 확인해보겠다 하고 이 친구의 계정을 받아서 로그인 해봤다.

 

---

5. Vercel env 값 확인하기

결론은 좀 허무하지만 env에 NEXT_PUBLIC_BASE_API_URL 값이 잘못 입력되어 있었다.

https://로 시작해야하는데 http://로 시작하고 있었던 것..ㅋㅋㅋㅋㅋㅋ

 

 

 

 

 

---

6. 배운 것

살짝 허무하게 문제를 해결하긴 했지만 많이 헤멘만큼 많이 배웠다고 생각한다.

1. 리디렉션과 헤더 탈락

fetch의 기본값인 'follow'는 30X 응답에서 Authorization, Cookie 헤더를 자동으로 제거한다.

인증이 필요한 요청에는 redirect: 'manual'로 명시적으로 처리함으로써 예외 상황을 잡을 수 있다.

 

2. 에러 좁혀나가기

이전처럼 막연하게 콘솔을 하나하나 찍어봤는데 이번의 경우는 배포를 해야 확인이 가능했다.

그렇게 테스트하는 의미가 없는 pr을 여러 번 올리게 되었다.

코드 구조와 로직에 대한 확신을 가진 이해와 Sentry 사용의 의의를 알았다면 이렇게 헤메지는 않았을 것이다.

처음부터 Sentry를 사용했다면, 그를 통해 쿠키에 토큰이 있음을 확신했다면, curl과 postman의 결과를 통해 확정적으로 에러 경로를 좁혔다면 금방 찾을 수 있었던 문제였다고 생각한다.

 

다만 현재 모두 신입을 준비하는 중이었기에 로직과 세팅에 확신을 가지기 어려워서 더 돌고 돌았던 것 같다.

 

3. 백엔드와 프론트 사이의 공유

우리팀의 백엔드는 백엔드만, 프론트엔드는 프론트엔드만 주로 다뤄와서 각자의 영역에서 코드의 흐름을 잘 알지 못했다.

물론 서로의 상황에 대해 무조건적으로 지식을 쌓기에는 무리가 있을 것이다.

 

하지만 어느정도의 지식은 있는 것이 좋지 않을까 하는 생각을 했다. 그 어느정도가 얼마나일지는 모르겠지만..

또한 BFF의 경우 내가 설명을 제대로 하지 못한 탓도 있다고 생각한다. 내가 작성한 부분이기에..

내가 백엔드의 구조를 아는 것은 둘째치고, 담당자로서 이런 아키텍처를 명확하게 설명할 수 있어야겠다는 것을 인지했다.

 

4. 환경변수 체크

docker를 도입하면서 환경변수가 여러번 바뀌게 되었다. 저게 로컬에서 실행하면서도 기존의 env로는 채팅이 안되거나 하는 문제가 있었었기 때문이다.

그래서 이번에 문제가 되었던 PUBLIC_BASE_API_URL가 로컬에서 테스트하는 중에서도 필요에 따라 다른 값을 활용하기도 했는데,

이번에 결국 핵심 문제가 되었었다.

http와 https의 차이로 단순 오타일 수도 있지만 환경변수 각각의 역할과 현재 프로젝트에서 가지는 의미를 파악하고 있었으면 더 좋았을 것 같다.

또한 팀원 간 정확한 환경변수를 정의해두고 무조건 해당 내용을 복사해서 사용하는 것도 방법이 될 수 있을 것 같다.

 

5. Vercel과 같은 도구의 공유

사실 이부분은 현재로써는 어쩔 수 없는 상황이라고 볼 수 있다.

내가 이번에 추가한 Sentry도 팀원 추가하려면 플랜을 업그레이드 해야하는데, 당장 수익을 내는 서비스 개발을 목표로 하기보다는

단순 완성을 목표로 하고 있는 서비스이기 때문에 무작정 그런 구독들을 할 수가 없었다.

게다가 친분이 있는 사이어서 서로 확인을 잘 하면 된다는 안일함도 있었다.

 

이번 경우도 내가 vercel에 대해 잘 이해하고 "이 부분 캡처를 보여달라"는 식으로 공유를 빠르게 했었으면 오타를 발견할 수 있었을 텐데 막연하게 잘 됐겠지하고 생각했던 것도 실수였다.

 

백엔드 상황은 정말 볼 수가 없으니까 캡처본을 그렇게 잘만 요구해놓고 정작 더 가까이에 있던 Vercel 체크를 못했다니..

 

에러는 "되겠지"같이 생각하면서는 잡을 수가 없다. 현재도 에러를 찾기 위해 작성한 여러 테스트/콘솔 코드들을 다시 만져야한다.

다양한 패턴을 확실하게 머릿속에 넣어두는 게 중요할 것 같다.

 

6. ai 도구의 활용

아 추가로 ai 도구 활용에 대해 다시 고려하게되었다. claude를 지금까지 브라우저로만 사용하다가 현재 적용한 BFF 및 에러 핸들러 구조에 뭔가 삐끗한 문제가 있는 게 아닐까 하여 vscode에 claude를 설치하고 사용해봤는데 바로 길이 나왔다. 이 부분은 구조의 문제라기보다는 한 파일에서 미처 잡지 못한 에러 경로긴 했지만.. 그래도 한 번 빠르게 문제를 해결해보니 미루던 ai 도구 도입(md 파일 작성이라던지)을 정말로 하긴 해야겠다고 느꼈다.

또한 도구를 활용하면서 질문의 뾰족함, 상황 정리를 하는 것도 역시 중요하다는 것을 느꼈다. 또 영어로 질문하는 것도 괜찮은 것 같다.

 

 

 

 

주저리주저리 말이 많았지만.. 오래걸렸던 에러 해결!

 

 

 

 

 

참고

참고자료링크