CORS란 무엇인가 – 브라우저에서 API 요청이 막히는 이유

목차

1. 개발하다가 갑자기 막히는 그 오류
2. 동일 출처 정책(Same-Origin Policy)이란?
3. CORS란 무엇인가?
4. CORS 오류가 발생하는 상황
5. CORS 오류를 해결하는 방법
6. CORS 관련 HTTP 헤더 이해하기
7. Preflight 요청이란?
8. 정리 및 다음 단계

1. 개발하다가 갑자기 막히는 그 오류

웹 개발을 처음 시작하면 반드시 한 번은 마주치는 오류가 있습니다. 브라우저 콘솔에 다음과 같은 메시지가 뜨면서 API 요청이 막히는 상황입니다.

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

이 오류를 처음 보면 무슨 의미인지, 어떻게 해결해야 하는지 당황스럽습니다. 이 글에서는 CORS가 왜 존재하는지, 오류가 왜 발생하는지, 어떻게 해결하는지를 단계별로 설명드립니다.

2. 동일 출처 정책(Same-Origin Policy)이란?

CORS를 이해하려면 먼저 **동일 출처 정책(Same-Origin Policy)**을 알아야 합니다.

브라우저는 보안상의 이유로 다른 출처에서 온 리소스를 기본적으로 차단합니다. 여기서 출처(Origin)는 프로토콜 + 도메인 + 포트의 조합입니다.

예를 들어 http://localhost:3000과 http://localhost:8080은 포트가 다르기 때문에 서로 다른 출처입니다. http://example.com과 https://example.com은 프로토콜이 달라 다른 출처입니다.

이 정책이 존재하는 이유는 악의적인 사이트가 사용자 모르게 다른 사이트의 API를 호출해 개인정보를 탈취하는 것을 막기 위해서입니다.

3. CORS란 무엇인가?

**CORS(Cross-Origin Resource Sharing)**는 동일 출처 정책의 예외를 허용하는 메커니즘입니다. 서버가 "특정 출처에서 오는 요청은 허용한다"고 브라우저에게 알려주는 방식입니다.

즉, CORS는 서버가 설정하는 것입니다. 브라우저가 요청을 막는 것이 아니라, 서버가 허용 출처를 명시해주지 않아서 브라우저가 차단하는 것입니다.

CORS 오류는 브라우저에서만 발생합니다. Postman이나 curl 같은 도구로 같은 API를 호출하면 정상적으로 응답이 옵니다. 이 차이가 CORS를 이해하는 핵심입니다.

4. CORS 오류가 발생하는 상황

가장 흔한 CORS 오류 상황입니다.

프론트엔드가 http://localhost:3000에서 실행 중인데, 백엔드 API가 http://localhost:8080에 있을 때 발생합니다. 프론트엔드 배포 주소가 https://myblog.com인데, API 서버는 https://api.myblog.com에 있을 때도 발생합니다. 외부 API를 브라우저에서 직접 호출할 때 해당 API 서버가 CORS를 허용하지 않으면 발생합니다.

5. CORS 오류를 해결하는 방법

CORS 오류는 서버 쪽에서 허용 출처를 설정해야 해결됩니다.

Node.js (Express) 서버에서 CORS 설정 cors 패키지를 설치하고 미들웨어로 등록합니다.

npm install cors

 

const cors = require('cors');
app.use(cors({ origin: 'http://localhost:3000' }));

모든 출처를 허용하고 싶다면 origin: '*'으로 설정합니다. 단, 실서비스에서 모든 출처를 허용하는 것은 보안상 좋지 않으므로 허용할 출처를 명시적으로 지정하는 것이 좋습니다.

Nginx에서 CORS 헤더 추가 Nginx 설정 파일의 location 블록에 아래 헤더를 추가합니다.

add_header 'Access-Control-Allow-Origin' 'https://myblog.com';
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';

Spring Boot에서 CORS 설정 컨트롤러나 설정 클래스에서 @CrossOrigin 어노테이션 또는 WebMvcConfigurer를 사용해 허용 출처를 등록합니다.

6. CORS 관련 HTTP 헤더 이해하기

CORS는 HTTP 헤더를 통해 동작합니다. 주요 헤더를 알아두면 오류 메시지를 해석하는 데 도움이 됩니다.

서버가 응답에 포함하는 헤더

Access-Control-Allow-Origin은 어떤 출처에서 오는 요청을 허용할지 지정합니다. https://myblog.com 처럼 특정 도메인을 지정하거나, *로 모든 출처를 허용할 수 있습니다.

Access-Control-Allow-Methods는 허용하는 HTTP 메서드를 지정합니다. GET, POST, PUT, DELETE 처럼 명시합니다.

Access-Control-Allow-Headers는 요청에 포함할 수 있는 헤더를 지정합니다. Authorization, Content-Type 처럼 명시합니다.

Access-Control-Max-Age는 Preflight 요청의 결과를 브라우저가 캐시하는 시간(초)을 지정합니다.

7. Preflight 요청이란?

브라우저는 실제 요청을 보내기 전에 서버가 해당 요청을 허용하는지 먼저 확인하는 Preflight 요청을 보내는 경우가 있습니다.

Preflight 요청은 OPTIONS 메서드로 전송되며, 서버가 해당 출처와 메서드를 허용한다고 응답하면 실제 요청을 보냅니다.

Preflight 요청이 발생하는 조건은 GET, POST, HEAD 이외의 메서드를 사용할 때, Content-Type이 application/json인 경우, 커스텀 헤더(예: Authorization)를 포함하는 경우입니다.

서버에서 OPTIONS 요청을 처리하도록 설정하지 않으면 Preflight 단계에서 CORS 오류가 발생합니다.

8. 정리 및 다음 단계

오늘 배운 핵심을 정리합니다.

• 동일 출처 정책 때문에 브라우저는 기본적으로 다른 출처의 리소스 요청을 차단합니다.
• CORS는 서버가 특정 출처의 요청을 허용하도록 브라우저에 알려주는 메커니즘입니다.
• CORS 오류는 서버에서 Access-Control-Allow-Origin 헤더를 설정해 해결합니다.
• CORS 오류는 브라우저에서만 발생하며, Postman 같은 도구에서는 발생하지 않습니다.
• 실서비스에서는 모든 출처(*)를 허용하지 말고 필요한 도메인만 명시적으로 허용합니다.

다음 글에서는 웹소켓(WebSocket)이란 무엇인지, 실시간 채팅이 되는 원리를 알아보겠습니다.