728x90

    "Postman에선 되는데 브라우저에선 안 돼요"

    개발하다 보면 한 번쯤은 만나는 문구예요. API 서버는 분명 살아있고, curl로 치면 응답이 오는데, 프론트에서 fetch만 하면 빨간 글씨가 뜨죠.

    
    Access to fetch at 'https://api.example.com/data' from origin
    'http://localhost:3000' has been blocked by CORS policy
    

    문제는 이 에러가 "서버가 거절했다"가 아니라 브라우저가 응답을 막았다는 뜻이라는 거예요. 서버는 응답을 보냈어요. 응답이 브라우저의 CORS 정책 검사를 통과 못 해서 JS 코드가 못 읽게 된 거죠. 이걸 매번 검색해서 찾기 지겨워서, 브라우저가 실제로 어떤 순서로 검사하는지를 단계별로 보여주는 시뮬레이터를 만들었어요.

    CORS 시뮬레이터 — 요청 설정과 서버 응답 설정, 아래에 브라우저 검사 타임라인

    만든 도구가 하는 일

    요청 쪽(출처, 메서드, Content-Type, 커스텀 헤더, credentials)과 응답 쪽(Access-Control-Allow-* 헤더들)을 따로 설정하게 했어요. 값을 바꾸면 아래 타임라인이 실시간으로 다시 계산돼요.

    • 단순 요청 판정: GET/POST/HEAD + 단순 헤더만 + 단순 Content-Type이면 OPTIONS를 안 보내고 바로 본 요청으로 가요
    • 프리플라이트: 조건을 벗어나면 브라우저가 먼저 OPTIONS로 "해도 되나요?" 물어봐요 — 실제 헤더 스니펫(Access-Control-Request-Method 등)을 그대로 보여줘요
    • 응답 검사: 서버의 ACAO/메서드/헤더 허용 목록을 하나씩 비교하고, 막히면 그 단계가 빨간색으로 찍혀요
    • 크롬 에러 재현: 최종적으로 차단되면 실제 개발자도구에 뜨는 문구를 그대로 만들어서 콘솔 패널에 보여줘요

    프리플라이트 시나리오 — OPTIONS 요청과 응답 헤더가 단계별로 표시됨

    삽질 1 — "단순 요청"의 경계가 생각보다 좁았어요

    시뮬레이션 로직을 짜면서 제일 헷갈렸던 게 단순 요청(simple request) 판정이에요. 대충 "GET/POST면 프리플라이트 없음"으로 아는 경우가 많은데, 실제론 세 조건을 전부 만족해야 해요.

    1. 메서드가 GET, HEAD, POST 중 하나
    2. 헤더가 안전 목록(Accept, Accept-Language, Content-Language, Content-Type) 안에 있음
    3. Content-Type이 application/x-www-form-urlencoded, multipart/form-data, text/plain 중 하나

    여기서 함정이 3번이에요. Content-Type: application/json만 붙여도 단순 요청이 아니게 돼요. 그래서 "JSON POST면 무조건 프리플라이트"가 되는 거예요. 요즘 API가 거의 다 JSON이라, 사실상 POST는 대부분 OPTIONS를 거친다고 봐도 돼요.

    커스텀 헤더도 마찬가지예요. X-Auth-Token 하나만 붙여도 프리플라이트 대상이에요. 시뮬레이터에서도 헤더 칩 하나 토글하면 타임라인에 OPTIONS 단계가 생겼다 없어졌다 하는 걸 눈으로 볼 수 있게 했어요.

    삽질 2 — 와일드카드와 credentials는 같이 못 써요

    제일 유명한 함정인데, 만들면서도 다시 확인하게 된 조합이에요.

    
    Access-Control-Allow-Origin: *
    Access-Control-Allow-Credentials: true   ← 이 조합은 무효!
    

    withCredentials(쿠키, 인증 헤더 포함)를 켜면 브라우저는 ACAO가 *인 응답을 통째로 거부해요. 보안상 당연한 얘기인데, "모든 출처에 쿠키 세션을 열어준다"는 게 말이 안 되니까요. 이때는 요청 Origin을 그대로 echo 해줘야 해요.

    그래서 시뮬레이터에도 이 조합을 그대로 재현했어요. credentials를 켠 상태에서 ACAO를 *로 두면 "credentials 사용 시 와일드카드 불가" 에러가 떠요. 시나리오 프리셋에도 이 케이스를 따로 넣어뒀어요.

    차단 시나리오 — 어느 단계에서 막혔는지 빨간색으로 표시되고 콘솔에 실제 에러 문구가 뜸

    삽질 3 — Access-Control-Allow-Headers 입력이 번거로웠어요

    만들고 나서 스스로 써보다 불편했던 부분이에요. 처음엔 Access-Control-Allow-Headers를 자유 입력칸으로만 뒀거든요. "헤더 이름은 서버마다 제각각이라 칩으로 못 만든다"는 이유였는데, 막상 쓰니까 매번 x-auth-token 치기가 귀찮았어요.

    그래서 두 종류의 토글 칩을 추가했어요.

    • 지금 요청이 실제 필요로 하는 헤더: 입력한 커스텀 헤더명이 자동으로 칩이 돼요. X-Foo로 바꾸면 칩도 x-foo로 따라와요
    • 자주 쓰는 값: authorization, * 같은 대표값

    칩 하나 누르면 차단이 풀리는 걸 바로 실험할 수 있게 됐어요. "서버에서 뭘 열어줘야 하는지"를 반대로 읽는 셈이죠.

    Postman에서 되는 이유를 다시 정리하면

    시뮬레이터를 만들고 나서야 확실히 정리가 됐어요. CORS는 서버의 정책이 아니라 브라우저의 정책이에요. Postman이나 curl은 브라우저가 아니니까 ACAO 검사를 아예 안 해요. 그래서 "Postman은 되는데 브라우저는 안 된다"가 성립하는 거고, 해결 방법도 서버의 응답 헤더를 맞춰주는 것밖에 없어요.

    정리하면

    CORS 에러를 만나면 이제 순서가 있어요.

    1. 프리플라이트가 가는 요청인지 확인 (메서드? 커스텀 헤더? JSON Content-Type?)
    2. OPTIONS 응답에 ACAO/메서드/헤더 허용이 빠짐없이 있는지 확인
    3. credentials를 쓰면 ACAO에 * 금지 + Access-Control-Allow-Credentials: true 필수

    이 순서를 손으로 몇 번 돌려보면 이후엔 에러 문구만 봐도 어느 단계에서 막힌 건지 감이 와요. 직접 값을 바꿔가며 단계가 끊기는 지점을 보고 싶으면 CORS 시뮬레이터에서 시나리오를 돌려볼 수 있어요. "헤더 미허용"이나 "credentials 함정" 같은 프리셋이 실제 겪는 케이스랑 거의 같아서, 막힌 원인 찾기가 훨씬 빨라져요.

    728x90
    Posted by 천상나타.