CORS 헤더

fetch 요청을 보냅니다. 서버가 응답합니다. 그런데 브라우저가 그 응답을 버려버립니다.

Access to fetch at 'https://api.example.com' from origin 'https://app.example.com' 
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present.

이것이 CORS, 즉 Cross-Origin Resource Sharing(교차 출처 리소스 공유)입니다. 그리고 좌절감을 이해로 바꿔주는 핵심이 하나 있습니다: 서버는 이미 요청을 처리했습니다. 코드를 실행하고, 데이터베이스를 건드리고, 데이터를 돌려보냈습니다. CORS는 단지 여러분의 JavaScript가 무슨 일이 일어났는지 볼 수 있는지를 결정할 뿐입니다.

CORS는 모든 응답에서 손님 명단을 확인하는 브라우저의 문지기입니다.

브라우저가 이렇게 하는 이유

https://mybank.com에서 은행 계좌에 로그인했다고 상상해 보세요. 브라우저에는 여러분의 세션 쿠키가 있습니다. 그런데 https://sketchy-site.com을 방문하자 숨겨진 JavaScript가 실행됩니다:

fetch('https://mybank.com/api/transfer', {
    method: 'POST',
    credentials: 'include',
    body: JSON.stringify({ to: 'attacker', amount: 10000 })
});

CORS가 없다면 이 코드는 실제로 작동합니다. 브라우저는 충실하게 은행 쿠키를 요청에 담아 보내고, 이체가 실행되어 공격자가 돈을 가져갑니다.

CORS는 https://mybank.com이 명시적으로 "https://sketchy-site.com의 요청을 신뢰한다"고 선언하도록 요구함으로써 이를 막습니다. 어떤 정상적인 은행도 그런 선언을 하지 않기 때문에, 브라우저는 응답을 차단합니다. 더 중요한 것은, 사전 허가 없이 인증 정보가 담긴 요청 자체를 차단한다는 점입니다.

출처(Origin)란

출처는 스킴, 호스트명, 포트의 조합입니다:

• https://example.com과 http://example.com — 다른 출처 (스킴이 다름)
• https://example.com과 https://api.example.com — 다른 출처 (호스트명이 다름)
• https://example.com:443과 https://example.com:8443 — 다른 출처 (포트가 다름)

동일 출처란 세 가지가 모두 정확히 일치하는 경우를 말합니다.

모든 것을 제어하는 헤더들

Access-Control-Allow-Origin

CORS의 핵심 허가 헤더입니다:

Access-Control-Allow-Origin: https://app.example.com

"https://app.example.com의 JavaScript가 이 응답에 접근할 수 있다"는 뜻입니다. 다른 출처는 모두 차단됩니다.

와일드카드를 사용하면 모든 출처에 허용합니다:

Access-Control-Allow-Origin: *

진정으로 공개된 데이터라면 괜찮습니다. 그 외에는 위험합니다. 그리고 한 가지 중요한 점: 와일드카드는 인증 정보와 함께 사용할 수 없습니다.

Access-Control-Allow-Credentials

기본적으로 교차 출처 요청에는 쿠키나 Authorization 헤더가 포함되지 않습니다. 이를 허용하려면:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true

두 헤더가 모두 필요합니다. 그리고 여기서 와일드카드는 사용할 수 없습니다. 인증 정보가 관련된 경우, 서버는 신뢰하는 출처를 정확히 명시해야 합니다. 이는 의도적인 설계입니다—"모든 출처를 신뢰하면서 동시에 사용자의 인증 정보를 보호한다"는 건 말이 되지 않으니까요.

Access-Control-Allow-Methods

허용되는 HTTP 메서드:

Access-Control-Allow-Methods: GET, POST, PUT, DELETE

Access-Control-Allow-Headers

허용되는 요청 헤더:

Access-Control-Allow-Headers: Content-Type, Authorization

기본적으로 소수의 "안전한" 헤더만 허용됩니다. Authorization이나 Content-Type: application/json을 사용하는 순간, 명시적으로 허가해야 합니다.

Access-Control-Max-Age

허가 확인 결과를 캐시하는 시간(초 단위):

Access-Control-Max-Age: 86400

사전 요청(preflight) 때문에 이 값이 중요합니다.

Access-Control-Expose-Headers

기본적으로 JavaScript에서 볼 수 있는 응답 헤더는 몇 가지로 제한됩니다. 사용자 정의 헤더를 노출하려면:

Access-Control-Expose-Headers: X-Request-ID, X-RateLimit-Remaining

단순 요청 vs. 사전 요청(Preflight)

일부 요청은 "단순 요청"입니다—브라우저가 바로 보내고, 응답을 받은 후 CORS를 확인합니다:

• GET, HEAD, POST 메서드
• 표준 헤더만 사용 (Accept, 폼 값의 Content-Type 등)
• Content-Type이 application/x-www-form-urlencoded, multipart/form-data, text/plain 중 하나

이 조건을 벗어나면 **사전 요청(preflight)**이 발생합니다. 실제 요청을 보내기 전에 OPTIONS 요청으로 먼저 허가를 구하는 방식입니다:

OPTIONS /api/data HTTP/1.1
Origin: https://app.example.com
Access-Control-Request-Method: DELETE
Access-Control-Request-Headers: Authorization

서버가 허용 범위를 응답합니다:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, DELETE
Access-Control-Allow-Headers: Authorization
Access-Control-Max-Age: 86400

사전 요청이 통과되면 브라우저가 실제 요청을 보냅니다. 실패하면 실제 요청은 아예 발생하지 않습니다.

Access-Control-Max-Age가 중요한 이유가 바로 이것입니다—캐싱 없이는 사용자 정의 헤더가 포함된 API 호출마다 두 번의 왕복이 필요합니다.

자주 발생하는 오류와 의미

"No 'Access-Control-Allow-Origin' header is present"

서버가 CORS 헤더를 전혀 보내지 않았습니다. CORS 설정이 없거나, 해당 출처에 대한 설정이 없는 것입니다.

"The value of the 'Access-Control-Allow-Origin' header must not be the wildcard '*' when the request's credentials mode is 'include'"

인증 정보(쿠키, Authorization)를 포함해 요청했는데 서버가 *를 반환했습니다. 정확한 출처를 명시해야 합니다.

"Method PUT is not allowed by Access-Control-Allow-Methods"

사전 요청 응답에 PUT이 포함되지 않았습니다. 허용 메서드에 추가하세요.

"Request header field authorization is not allowed by Access-Control-Allow-Headers"

사전 요청 응답에서 Authorization 헤더를 허용하지 않았습니다. 추가하세요.

디버깅

개발자 도구를 여세요. 두 개의 탭이 중요합니다:

Console: 무엇이 실패했는지 상세히 알려주는 CORS 오류를 표시합니다.

Network: 실제 요청을 보여줍니다. 다음을 확인하세요:

• OPTIONS 사전 요청이 있는지
• 응답 헤더가 있는지 (없다면 그것 자체가 단서)
• 요청이 차단된 건지, 응답이 차단된 건지

기억하세요: Network 탭에서 서버 응답이 보인다면, 서버는 정상적으로 처리한 것입니다. CORS가 JavaScript의 결과 접근만 막은 것입니다.

서버 설정

Express/Node.js:

const cors = require('cors');
app.use(cors({
    origin: 'https://app.example.com',
    credentials: true
}));

Nginx:

location /api {
    add_header Access-Control-Allow-Origin https://app.example.com always;
    add_header Access-Control-Allow-Credentials true always;
    add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE' always;
    add_header Access-Control-Allow-Headers 'Content-Type, Authorization' always;
    
    if ($request_method = OPTIONS) {
        return 204;
    }
}

always 지시어는 오류 응답에도 헤더가 포함되도록 합니다. 이것이 없으면 500 오류 시 CORS 헤더가 사라져 디버깅이 훨씬 어려워집니다.

보안 현실

CORS는 브라우저 보안이지, 서버 보안이 아닙니다. curl, Postman, 또는 자체 HTTP 클라이언트를 사용하면 CORS를 완전히 우회합니다. CORS는 악의적인 웹사이트로부터 사용자를 보호하는 것이지, 악의적인 공격자로부터 API를 지키는 것이 아닙니다.

Origin 헤더를 무조건 반영하지 마세요:

// 위험 — 모든 출처를 허용하게 됨
response.header('Access-Control-Allow-Origin', request.headers.origin);

허용 목록을 관리하세요:

const allowed = ['https://app.example.com', 'https://admin.example.com'];
const origin = request.headers.origin;
if (allowed.includes(origin)) {
    response.header('Access-Control-Allow-Origin', origin);
}

인증 정보에는 각별히 주의하세요. Access-Control-Allow-Credentials: true는 "이 출처에서 사용자 권한으로 인증된 요청을 보낼 수 있다"는 뜻입니다. 완전히 통제하는 출처에만 부여하세요.

와일드카드는 공개 데이터에만 사용합니다. 인증이 필요한 API라면 *는 올바른 선택이 아닙니다.

동작 원리

CORS는 브라우저와 서버 사이의 대화입니다:

1. 브라우저: "저는 출처 X의 JavaScript인데, 출처 Y에 접근하고 싶습니다"
2. 서버: "요청을 처리했습니다. 그리고 제가 신뢰하는 출처는 이것입니다" (헤더를 통해 전달)
3. 브라우저: "출처 X가 그 목록에 있나요? 있으면 JavaScript가 데이터를 받고, 없으면 차단합니다."

서버는 항상 요청을 처리합니다. CORS는 브라우저가 그 응답을 JavaScript와 공유할지만 결정합니다.

CORS 오류가 이상하게 느껴지는 이유가 바로 이것입니다—DevTools에서 서버가 정상적으로 응답한 것을 분명히 볼 수 있는데 코드에서는 접근이 안 됩니다. 응답은 존재합니다. 브라우저가 여러분에게 보여주지 않을 뿐입니다.

CORS 자주 묻는 질문

Postman에서는 되는데 브라우저에서 실패하는 이유가 뭔가요?

Postman은 브라우저가 아닙니다—CORS를 적용하지 않습니다. CORS는 한 출처의 JavaScript가 다른 출처의 응답에 접근하는 것을 막는 브라우저 보안 기능입니다. curl이나 Postman 같은 도구는 이 검사를 완전히 건너뜁니다.

개발 중에 localhost에서 CORS 오류가 나는 이유가 뭔가요?

http://localhost:3000과 http://localhost:8080은 포트가 달라 서로 다른 출처입니다. 프론트엔드와 백엔드는 개발 환경에서도 적절한 CORS 설정이 필요합니다. 많은 프레임워크에서 이를 자동으로 처리하는 개발 모드를 제공합니다.

CORS를 끌 수 있나요?

사실상 불가능합니다. 개발용으로 CORS 헤더를 제거하는 브라우저 확장 프로그램을 설치할 수는 있지만, 그건 여러분의 브라우저에서만 적용됩니다. 사용자들은 여전히 CORS 오류를 겪습니다. 진짜 해결책은 서버를 올바르게 설정하는 것입니다.

Authorization 헤더를 추가했더니 갑자기 요청이 실패하는 이유가 뭔가요?

Authorization은 "안전한" 헤더가 아니기 때문에, OPTIONS 사전 요청을 발생시킵니다. 서버가 OPTIONS 요청을 처리하고 Authorization을 포함한 Access-Control-Allow-Headers를 반환해야 합니다.

와일드카드(*)를 인증 정보와 함께 쓸 수 없는 이유가 뭔가요?

의도적인 보안 설계입니다. 와일드카드와 함께 인증 정보를 허용하면 "어떤 웹사이트든 이 사용자 권한으로 인증된 요청을 보낼 수 있다"는 뜻이 되어버립니다—엄청난 보안 허점입니다. 인증 정보가 관련된 경우에는 출처를 정확히 명시하도록 명세에서 요구합니다.