CORS를 정확히 이해하기: 문제의 본질부터 짚고 가기
CORS(Cross-Origin Resource Sharing)는 브라우저가 다른 Origin(스킴 + 호스트 + 포트)에서 제공되는 리소스에 접근할 때 적용되는 보안 메커니즘입니다. 서버가 적절한 헤더로 “허용”했음을 명시하지 않으면, 브라우저는 요청을 막거나 응답을 노출하지 않습니다. 이때 가장 핵심적인 응답 헤더가 바로 Access-Control-Allow-Origin(이하 ACAO)입니다.
하지만 많은 프로젝트에서 ACAO를 단순히 “*”로 설정하거나, Origin 헤더를 그대로 반사(reflect)하는 방식으로 문제를 해결하려다 보안 취약점과 유지보수 문제를 야기합니다. 이 글에서는 CORS의 원리부터 ACAO 설정 최적화, 실전 사례, 성능 개선, 보안 체크리스트까지 “현업에서 바로 적용 가능한” 방법을 정리합니다.
CORS의 동작 요약
- 같은 Origin이란 무엇인가?
- “스킴 + 호스트 + 포트”가 모두 동일해야 합니다. 예: https://app.example.com:443 와 http://app.example.com:80은 서로 다른 Origin입니다.
- 간단 요청(Simple Request):
- GET, HEAD, POST 중 특정 조건을 만족하는 요청은 사전 검사(Preflight) 없이 바로 보냅니다.
- Content-Type이 application/x-www-form-urlencoded, multipart/form-data, text/plain 중 하나여야 하고, 커스텀 헤더가 없어야 합니다.
- 사전 검사(Preflight, OPTIONS):
- 그 외 대부분의 요청은 브라우저가 먼저 OPTIONS 요청을 보내 서버가 허용하는 메서드/헤더를 확인합니다.
- 서버는 Access-Control-Allow-Methods, Access-Control-Allow-Headers, 그리고 필요한 경우 Access-Control-Max-Age로 응답합니다.
- 응답 노출 제한:
- 브라우저는 서버가 허용한 범위에 따라 응답 접근을 제한합니다. 쿠키/인증정보를 포함한 요청은 추가 요건이 있습니다.
Access-Control-Allow-Origin의 의미와 함정
- ACAO: 어떤 Origin에서의 접근을 허용할지 서버가 명시합니다.
- 예: Access-Control-Allow-Origin: https://app.example.com
- “*”는 모든 Origin 허용을 의미하지만, credentials(쿠키/인증 토큰 포함) 요청과 함께 사용할 수 없습니다.
- 복수 Origin:
- ACAO는 하나의 값만 허용합니다. 콤마로 여러 Origin을 나열할 수 없습니다. 필요한 경우 서버가 요청의 Origin을 검사해 “해당 Origin 하나”만 설정해야 합니다.
- Vary: Origin 반드시 고려:
- 동적으로 Origin을 반사하는 경우, Vary: Origin 헤더를 추가해 캐시/프록시가 Origin 별로 응답을 구분하도록 해야 캐시 오염을 방지합니다.
- null Origin 주의:
- file://, sandbox된 iframe, 일부 데이터 URL 등에서 오는 요청은 Origin 값이 “null”일 수 있습니다. 무분별하게 허용하면 보안 위험이 큽니다.
자주 보는 에러와 근본 원인
- “No ‘Access-Control-Allow-Origin’ header is present on the requested resource”
- 서버에서 ACAO가 빠졌거나, 프록시/리다이렉트 구간에서 사라졌습니다.
- “The value of the ‘Access-Control-Allow-Origin’ header must not be the wildcard ‘*’ when the request’s credentials mode is ‘include’”
- 쿠키/인증정보를 보내는 요청인데 ACAO를 “*”로 설정했습니다. 정확한 Origin 값을 넣어야 합니다.
- “Response to preflight request doesn’t pass access control check”
- OPTIONS 응답에 Access-Control-Allow-Methods/Headers가 충분히 설정되지 않았거나, 상태 코드/리다이렉트 처리에 문제가 있습니다.
- 302/301 리다이렉트에서 CORS 실패
- 리다이렉트 응답에도 CORS 헤더가 필요합니다. 중간 프록시/CDN 단계에서 헤더가 누락되지 않도록 하세요.
설계 원칙: 보안과 유지보수의 균형
- 최소 허용 원칙
- 정확한 도메인만 허용하고, 불가피할 때에만 와일드카드를 사용합니다.
- 자격 증명(쿠키, 인증 토큰) 처리 시 엄격 모드
- ACAO는 정확한 Origin으로 설정하고, Access-Control-Allow-Credentials: true를 사용합니다.
- 쿠키를 쓸 경우 Set-Cookie에 SameSite=None; Secure 설정을 포함합니다.
- 동적 반사는 “검증 후 반사”
- 요청 Origin을 안전한 allowlist로 검증한 뒤, 해당 Origin만 ACAO에 넣습니다. 정규식은 엄격하게 작성하고, “.example.com.evil.com” 같은 우회가 없도록 주의하세요.
- 캐시/프록시 고려
- Vary: Origin을 반드시 포함하고, CDN의 캐시 키에도 Origin을 포함하세요.
실전 예제 1: Node.js(Express)에서 안전한 동적 Origin 허용
간단히 cors 미들웨어를 쓰되, 함수형 origin 옵션으로 allowlist를 검사합니다.
// npm i cors express
const express = require('express');
const cors = require('cors');
const app = express();
const allowlist = new Set([
'https://app.example.com',
'https://admin.example.com',
]);
const corsOptionsDelegate = (req, callback) => {
const requestOrigin = req.header('Origin');
let corsOptions;
if (requestOrigin && allowlist.has(requestOrigin)) {
corsOptions = {
origin: requestOrigin,
credentials: true, // 쿠키/인증정보 허용 시
allowedHeaders: ['Content-Type', 'Authorization'],
methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
maxAge: 600, // Preflight 캐시(브라우저 상한 있음)
exposedHeaders: ['X-Request-Id'],
};
} else {
corsOptions = { origin: false }; // 허용하지 않음
}
callback(null, corsOptions);
};
app.use(cors(corsOptionsDelegate));
// OPTIONS 핸들링 (cors 미들웨어가 자동 처리)
app.options('*', cors(corsOptionsDelegate));
app.get('/api/data', (req, res) => {
res.setHeader('Vary', 'Origin'); // 동적 ACAO시 권장
res.json({ ok: true });
});
app.listen(3000);
팁:
- 동적으로 Origin을 설정할 때는 반드시 res.setHeader('Vary', 'Origin') 또는 서버/프록시 레벨에서 Vary 적용.
- allowlist를 코드에 하드코딩하지 말고 환경변수/DB로 관리하면 운영 편의성이 커집니다.
실전 예제 2: NGINX 리버스 프록시에서 CORS 처리
하나의 서버에서 여러 Origin을 허용하려면 map을 사용해 정교하게 적용합니다.
map $http_origin $cors_origin {
default "";
"~^https://app\.example\.com$" $http_origin;
"~^https://admin\.example\.com$" $http_origin;
}
server {
listen 443 ssl;
server_name api.example.com;
location / {
if ($request_method = OPTIONS) {
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Access-Control-Allow-Credentials "true" always;
add_header Access-Control-Allow-Methods "GET,POST,PUT,DELETE,OPTIONS" always;
add_header Access-Control-Allow-Headers "Content-Type,Authorization" always;
add_header Access-Control-Max-Age "600" always;
add_header Vary "Origin" always;
return 204;
}
proxy_pass http://upstream_api;
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Access-Control-Allow-Credentials "true" always;
add_header Vary "Origin" always;
}
}
주의:
- 정규식은 “.”를 이스케이프하고, 스킴까지 포함해야 합니다.
- $cors_origin이 빈 문자열일 때는 ACAO가 추가되지 않아야 합니다. map에서 default ""로 처리.
실전 예제 3: Spring Boot에서 CORS 구성
전역 설정으로 특정 도메인만 허용합니다.
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.*;
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**")
.allowedOrigins("https://app.example.com", "https://admin.example.com")
.allowedMethods("GET","POST","PUT","DELETE","OPTIONS")
.allowedHeaders("Content-Type","Authorization")
.exposedHeaders("X-Request-Id")
.allowCredentials(true)
.maxAge(600);
}
}
만약 테넌트별 커스텀 도메인이 동적으로 늘어나는 SaaS라면, Filter에서 Origin을 검사하고 응답 헤더를 직접 설정하는 전략을 사용하세요. 이때 반드시 Vary: Origin을 추가합니다.
실전 예제 4: S3/CloudFront에서 파일 업로드 CORS
직접 브라우저에서 S3로 업로드(PUT)하거나, pre-signed URL을 사용할 때는 S3 버킷 CORS 규칙이 필요합니다.
S3 버킷 CORS 예시(XML):
<CORSConfiguration>
<CORSRule>
<AllowedOrigin>https://app.example.com</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
<AllowedMethod>PUT</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<ExposeHeader>ETag</ExposeHeader>
<MaxAgeSeconds>600</MaxAgeSeconds>
</CORSRule>
</CORSConfiguration>
CloudFront를 경유한다면:
- 캐시 키에 Origin 헤더를 포함하거나, “Cache policy”에서 Origin을 포함.
- Origin 요청 정책과 응답 헤더 정책을 적절히 설정.
- 리다이렉트/에러 페이지에도 CORS 헤더가 유지되도록 확인.
Credentials(쿠키/토큰) 요청을 안전하게 처리하는 요령
- 서버:
- Access-Control-Allow-Credentials: true
- Access-Control-Allow-Origin: 정확히 요청 Origin
- Vary: Origin
- 클라이언트(fetch):
- fetch(url, { credentials: 'include' })
- XMLHttpRequest에서는 xhr.withCredentials = true
- 쿠키 설정:
- Set-Cookie: name=value; Path=/; Domain=.example.com; Secure; HttpOnly; SameSite=None
- Secure는 HTTPS에서만 동작. SameSite=None이 없으면 크로스 사이트 쿠키 전송이 차단됩니다.
주의:
- ACAO에 “*”와 Credentials를 함께 사용할 수 없습니다.
- Authorization 헤더를 쓴다면 Preflight가 발생합니다. API를 단순화하거나 토큰을 쿠키 기반으로 전환하는 전략도 고려하세요.
Preflight(OPTIONS) 최적화: 성능과 안정성
- Access-Control-Max-Age로 Preflight 캐시
- 서버는 600~7200초 범위로 설정하는 경우가 많습니다.
- 브라우저마다 상한이 다릅니다(사파리는 상대적으로 보수적, 수분 단위 제한이 흔함). 목표 브라우저에서 실제 동작을 검증하세요.
- Preflight 자체를 줄이기
- 가능하면 Simple Request 요건을 맞추세요.
- Content-Type을 application/json 대신 text/plain + 서버 변환으로 설계해도 됩니다. 다만 유지보수성을 고려해 트레이드오프를 평가해야 합니다.
- 커스텀 헤더 최소화. 필요 없는 X- 요청 헤더 제거.
- CDN/프록시 캐싱
- Preflight 응답도 캐시될 수 있습니다. Vary: Origin을 유지하고, CDN에서 OPTIONS 응답 캐시 정책을 명확히 하세요.
- 상태 코드
- Preflight 응답은 204/200 등 성공 코드로, 본문 없이도 충분합니다.
실전 사례로 보는 문제 해결
사례 1: SPA + API 서브도메인, 쿠키 인증
상황:
- 프론트: https://app.example.com
- API: https://api.example.com
- 세션 쿠키 기반 인증 필요
해결:
- API 서버
- ACAO: 요청 Origin이 app.example.com일 때만 설정
- Access-Control-Allow-Credentials: true
- Vary: Origin
- 쿠키
- Set-Cookie: session=...; Domain=.example.com; Path=/; Secure; HttpOnly; SameSite=None
- 클라이언트
- fetch('/me', { credentials: 'include' })
검증:
- DevTools Network에서 Request Headers의 Origin, Response Headers의 ACAO/ACAC(Allow-Credentials) 확인
- OPTIONS 요청에서 Allow-Methods/Headers/Max-Age 확인
성능:
- Access-Control-Max-Age 600 설정
- 커스텀 헤더 제거로 Preflight 빈도 추가 감소
보안:
- allowlist에 app.example.com만 포함
- admin 도메인 분리 시 별도 정책
사례 2: 멀티테넌트 SaaS, 고객 커스텀 도메인 지원
상황:
- 각 고객이 https://customer1.example.app, https://store.customer.com 등의 커스텀 도메인을 사용
- Origin 허용을 동적으로 관리해야 함
해결:
- DB/설정 저장소에 테넌트별 허용 Origin 목록 관리
- 서버에서 요청 Origin을 조회해 허용 시 ACAO에 그대로 반영
- 부정확한 정규식 금지, 정확한 일치 또는 엄격한 앵커 사용
- Vary: Origin 필수
- 관측
- 미허용 Origin 요청 로깅 및 경고 대시보드 구성
- OPTIONS 비율 모니터링으로 Preflight 튜닝
보안:
- “null” Origin 기본 거부
- 와일드카드 서브도메인 허용 불가(ACAO는 와일드카드 서브도메인 패턴을 지원하지 않음). 반드시 명시적 Origin만 허용.
사례 3: S3에 대한 대용량 파일 업로드
상황:
- 브라우저에서 S3로 직접 PUT 업로드
- x-amz-* 헤더들로 인해 Preflight 발생
해결:
- S3 CORS에 AllowedOrigin을 앱 도메인으로 제한
- AllowedMethod에 PUT 포함, AllowedHeader에 필요한 x-amz-* 포함
- CloudFront를 사용한다면 OPTIONS 캐시 최적화, Origin 포함한 캐시 키 설정
- 성능을 위해 MaxAgeSeconds 증가(브라우저 상한 고려)
안티패턴과 보안 이슈
- Origin 무차별 반사
- 요청 Origin을 무조건 ACAO로 되돌려주는 패턴은 공격자가 악성 도메인에서 민감 데이터를 읽도록 악용할 수 있습니다. 반드시 allowlist로 검증하세요.
- ACAO “*” + Credentials
- 브라우저가 거부합니다. 보안상도 위험합니다.
- “null” Origin 허용
- file://, sandbox iframe 등에서 오는 요청까지 허용하면 데이터 유출 리스크가 큽니다.
- 리다이렉트에서 CORS 헤더 누락
- 301/302 응답에도 CORS 헤더를 넣거나, 리다이렉트를 회피하는 구조로 바꾸세요.
- 과도하게 넓은 Allowed-Headers/Methods
- 필요한 최소 범위로 제한하세요. 특히 Authorization 외에 불필요한 커스텀 헤더는 제거를 권장합니다.
테스트와 디버깅 방법
- curl로 빠르게 재현
- 단순 요청:
- curl -i -H "Origin: https://app.example.com" https://api.example.com/data
- Preflight:
- curl -i -X OPTIONS https://api.example.com/data
-H "Origin: https://app.example.com"
-H "Access-Control-Request-Method: PUT"
-H "Access-Control-Request-Headers: Authorization,Content-Type"
- curl -i -X OPTIONS https://api.example.com/data
- 단순 요청:
- 브라우저 DevTools
- Network 탭에서 Request/Response Headers 확인
- 콘솔 에러 메시지로 누락된 헤더 식별
- 서버/프록시 로그
- 요청 Origin을 로그에 남기고 거부 사유를 모니터링
- 자동화 테스트
- 통합 테스트에 OPTIONS 시나리오 포함
- 주요 브라우저(Chrome, Safari, Firefox)에서 실제 동작 검증
CDN/프록시와 CORS: 놓치기 쉬운 포인트
- Vary: Origin
- 동적 ACAO 응답은 CDN이 Origin별로 캐싱해야 합니다. 그렇지 않으면 잘못된 Origin의 헤더가 재사용됩니다.
- 캐시 키 구성
- CloudFront/Nginx/Envoy 등에서 Origin을 캐시 키에 포함시키는 정책을 적용합니다.
- OPTIONS 캐시
- Preflight 응답을 일정 시간 캐시해 부하를 줄일 수 있습니다.
- 헤더 유지
- 프록시/리다이렉트 단계에서 CORS 헤더가 사라지지 않도록 “always” 플래그 또는 헤더 전파 정책을 설정합니다.
운영 체크리스트
- 정책
- 허용 Origin 명시 목록(환경/테넌트별)
- Credentials 사용 여부와 이유
- Allowed-Methods/Allowed-Headers 최소화
- 구현
- 동적 ACAO 시 Vary: Origin 적용
- OPTIONS 응답: 200/204, Allow-Methods/Headers/Max-Age 포함
- 리다이렉트/에러 응답에도 CORS 헤더 확인
- 보안
- null Origin 차단
- 정규식 우회 방지(정확한 앵커, 스킴 포함)
- 로그/알림으로 비정상 Origin 탐지
- 성능
- Access-Control-Max-Age 적정 설정(목표 브라우저 검증)
- Preflight 빈도 모니터링 및 헤더 단순화
- CDN 캐시 정책과 일관성
빠른 레시피 모음
- Express + cors
- credentials 필요하면 origin: true 대신 allowlist 검증 함수 사용
- res.setHeader('Vary','Origin') 추가
- Nginx
- map + 정규식으로 안전한 Origin 매핑
- OPTIONS 별도 처리 + always 플래그
- Spring Boot
- WebMvcConfigurer로 전역 규칙
- 동적 필요 시 Filter로 Origin 검증 + 직접 헤더 설정
- Kubernetes Ingress-NGINX
- nginx.ingress.kubernetes.io/configuration-snippet으로 헤더 추가
- 또는 서버 애플리케이션에서 처리
- CloudFront
- Cache policy에 Origin 포함
- Response headers policy로 CORS 일괄 적용
- S3
- 버킷 CORS에 AllowedOrigin/Methods/Headers 정확히 설정
- Pre-signed URL이면 동일 규칙 필요
문제 해결 가이드: 상황별 처방전
- 쿠키가 안 간다
- 클라이언트: credentials: 'include'
- 서버: ACAC: true, ACAO: 정확한 Origin
- 쿠키: SameSite=None; Secure
- “* not allowed with credentials”
- ACAO를 요청 Origin으로 설정(allowlist 검증 후)
- Preflight 과다
- 커스텀 헤더/메서드 줄이기
- Max-Age 늘리기(브라우저 상한 확인)
- OPTIONS 캐시 도입
- S3 업로드 실패
- AllowedHeader에 필요한 x-amz-* 포함
- CloudFront 캐시 정책 점검
- Redirect에서 실패
- 중간 30x 응답에도 CORS 헤더가 유지되도록 설정하거나, 리다이렉트 없는 경로 사용
마무리: “동적, 최소, 검증”이 핵심
CORS는 복잡해 보이지만 원리는 단순합니다. 서버가 어떤 Origin을 허용하는지 명시하고, 필요한 경우에만 최소한으로 문을 열면 됩니다. 실전에서는 다음 3가지를 기억하세요.
- 동적: 여러 Origin을 지원해야 한다면 요청 Origin을 검증 후 반사합니다.
- 최소: Methods/Headers/Origins를 최소화하고, Credentials는 꼭 필요한 경우에만 사용합니다.
- 검증: Vary: Origin, CDN 캐시 키, 리다이렉트/에러 경로, 브라우저별 Preflight 상한 등 운영 환경 전체를 검증합니다.
이 글의 예제와 체크리스트를 적용하면, CORS 에러에 당황하지 않고 안정적이면서도 성능 좋은 ACAO 설정을 구축할 수 있을 것입니다.