브라우저 API 요청과 CORS 오류 해결 원리
브라우저에서 외부 API를 호출할 때 발생하는 CORS 오류의 의미와 서버 측에서 안전하게 해결하는 접근법을 설명합니다.
1. CORS 오류가 뜻하는 것
웹 페이지가 자신과 다른 출처의 API를 호출하면 브라우저는 응답을 JavaScript에 공개해도 되는지 확인합니다. 출처는 프로토콜, 호스트, 포트의 조합으로 결정됩니다. 서버가 적절한 Access-Control-Allow-Origin 응답 헤더를 보내지 않으면 브라우저가 응답 접근을 차단할 수 있습니다.
2. 요청이 항상 단순 요청은 아닙니다
일부 요청은 실제 API 호출 전에 OPTIONS 프리플라이트 요청을 보냅니다. JSON 콘텐츠 유형이나 특정 사용자 지정 헤더, PUT·DELETE 같은 메서드가 사용될 때 발생할 수 있습니다. 서버는 OPTIONS 요청에 허용 출처, 메서드, 헤더를 올바르게 응답해야 합니다.
3. 브라우저에서 헤더를 마음대로 고칠 수 없습니다
프런트엔드 코드에서 응답에 CORS 헤더를 추가해도 이미 서버에서 받은 응답의 정책을 바꿀 수는 없습니다. 서버가 제어하는 응답 헤더가 중요합니다. 브라우저의 보안 제한을 비활성화하거나 무분별한 공개 프록시를 사용하는 방식은 해결책이 아닙니다.
4. 직접 운영하는 API라면
서버에서 허용할 웹사이트 출처를 명시하고, 필요한 메서드와 헤더만 허용합니다. 쿠키 인증을 사용할 때는 와일드카드 출처와 자격 증명 허용을 함께 사용하지 않도록 주의해야 합니다. 인증과 권한 확인은 CORS와 별도로 구현합니다.
5. 외부 API라면
외부 API 운영자가 CORS를 허용하지 않는 경우 브라우저 코드만으로 해결할 수 없습니다. 공식적으로 제공되는 브라우저용 API나 승인된 서버 측 연동 방법이 있는지 문서를 확인해야 합니다. 서버 프록시를 만든다면 요청 대상과 응답 크기를 제한하고, 비밀 키를 서버에만 보관하며, 남용 방지 정책을 적용해야 합니다.
6. 디버깅 순서
개발자 도구의 Network 탭에서 실제 요청과 OPTIONS 요청의 상태 코드를 확인합니다. 응답 헤더에 허용 출처가 있는지, 요청 메서드와 헤더가 허용 목록에 포함되는지 살펴봅니다. 서버 로그와 브라우저 콘솔을 함께 확인하면 네트워크 실패, 인증 실패, CORS 정책 문제를 구분하는 데 도움이 됩니다.
7. 프리플라이트 요청을 직접 읽는 방법
개발자 도구에서 OPTIONS 요청이 보인다면 브라우저가 실제 요청을 보내기 전에 서버에 허용 여부를 확인하는 과정일 수 있습니다. Request Headers의 Origin, Access-Control-Request-Method, Access-Control-Request-Headers와 Response Headers의 Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers를 나란히 비교합니다. 서버가 OPTIONS를 404로 처리하거나 허용 헤더를 빠뜨리면 실제 요청이 시작되기 전에 실패할 수 있습니다.
예를 들어 웹 페이지가 https://example.com에서 실행되고 API가 https://api.example.net에 있다면 두 주소는 서로 다른 출처입니다. 서버는 실제로 허용할 출처를 정확히 응답해야 합니다. 개발 환경의 localhost 주소와 운영 도메인을 구분하고, 임의의 모든 출처를 허용하는 설정을 인증 대체 수단으로 사용하지 마세요.
8. 오류 메시지별로 원인을 좁히기
응답에 Access-Control-Allow-Origin이 없음: API 응답 또는 오류 응답에 CORS 헤더가 빠졌는지 확인합니다. Preflight 요청 실패: OPTIONS 경로, 허용 메서드와 헤더를 확인합니다. 상태 코드는 200인데 브라우저에서 차단: 리디렉션, 자격 증명 설정, 실제 응답 헤더를 확인합니다. 로그인 요청만 실패: 쿠키 전송 여부, SameSite 설정, 자격 증명 허용 정책을 별도로 점검합니다. 네트워크 연결 실패나 서버의 500 오류를 모두 CORS 문제라고 단정하지 않는 것이 중요합니다.
9. 수정 후 회귀 테스트
허용된 출처에서 정상 요청이 되는지 확인한 뒤, 허용되지 않은 출처에서도 서버의 인증·권한 검사가 유지되는지 확인합니다. GET뿐 아니라 실제 사용하는 POST·PUT 등의 메서드, JSON과 사용자 지정 헤더, OPTIONS 응답, 오류 응답에도 정책이 일관되게 적용되는지 확인합니다. 브라우저에서 보이는 CORS 오류는 보안 경계가 아니라 응답 접근 규칙이라는 점을 기억하세요.
참고 자료: MDN Web Docs - Cross-Origin Resource Sharing · MDN - Preflight request