Cross-Origin-Embedder-Policy 기준 정리

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Cross-Origin-Embedder-Policy 기준 정리

Cross-Origin-Embedder-Policy(COEP)는 현재 문서가 no-cors 모드로 요청되는 교차 출처 리소스를 어떤 조건에서 불러올 수 있는지 정하는 HTTP 응답 헤더다. 2026년 6월 6일 기준 MDN 문서를 보면 값은 unsafe-none, require-corp, credentialless를 사용하며, 핵심 목적은 교차 출처 리소스가 명시적으로 허용되었는지 확인하고 필요하면 교차 출처 격리(cross-origin isolation) 조건을 맞추는 데 있다.

실무에서는 COEP를 CORS의 다른 이름처럼 이해하면 운영이 꼬이기 쉽다. COEP는 문서 쪽에서 "어떤 외부 리소스를 받아들일지"를 더 엄격하게 정하는 정책이고, 실제 읽기 허용은 여전히 CORS나 리소스 응답의 CORP 설정이 담당한다. 이 글은 값별 차이와 적용 기준, 그리고 SharedArrayBuffer 같은 기능과의 관계를 공식 문서 기준으로 정리한다.

Cross-Origin-Embedder-Policy는 무엇을 제어할까?

MDN은 COEP를 현재 문서가 교차 출처 리소스를 로드하거나 임베드할 때의 정책을 구성하는 헤더로 설명한다. 특히 기본적으로 no-cors로 요청되는 이미지, 스크립트, 스타일시트, iframe 같은 리소스에 직접적인 영향을 준다.

중요한 점은 COEP가 CORS를 대체하지 않는다는 점이다. MDN은 cors 모드 요청의 임베딩 정책은 CORS가 제어한다고 설명한다. 즉 COEP는 "무조건 외부 리소스를 막는 헤더"가 아니라, no-cors 경로에서 명시적 허용이 없는 교차 출처 리소스를 더 엄격하게 다루는 정책이다.

값은 어떻게 다를까?

1. unsafe-none

기본값이다. MDN은 이 값에서 문서가 CORP 헤더 없이도 no-cors 교차 출처 리소스를 로드할 수 있다고 설명한다. 호환성은 가장 높지만, 교차 출처 격리를 만들기 위한 기반은 되지 않는다.

2. require-corp

교차 출처의 no-cors 리소스가 로드되려면, 같은 origin이거나 응답이 적절한 Cross-Origin-Resource-Policy(CORP) 헤더를 보내야 한다. 또는 요청이 cors 모드로 전환되어 CORS 허용을 받아야 한다. 외부 자산을 많이 쓰지 않는 서비스에서 가장 먼저 검토하는 값이 보통 이것이다.

3. credentialless

MDN은 이 값을 사용하면 no-cors 교차 출처 리소스를 CORP 없이 로드할 수 있지만, 그 요청은 자격 증명 없이 전송된다고 설명한다. 즉 쿠키는 요청에서 빠지고, 응답에 포함된 쿠키도 무시된다. 다른 요청 모드의 동작은 require-corp와 같으므로, 모든 서드파티 자산 문제가 자동으로 해결되는 것은 아니다.

실무에서는 언제 COEP를 켤까?

교차 출처 격리가 필요한 기능을 쓸 때

MDN은 SharedArrayBuffer나 더 정밀한 타이머 같은 기능을 쓰려면 문서가 cross-origin isolated 상태여야 한다고 설명한다. 이 상태를 만들려면 COEP와 COOP를 함께 맞춰야 하므로, 브라우저 기능 요구사항이 먼저라면 COEP 검토가 거의 필수다.

서드파티 자산을 통제 가능한 범위로 줄이고 싶을 때

외부 이미지, 폰트, 스크립트, iframe이 어디서 어떻게 로드되는지 관리 가능한 서비스라면 require-corp로 운영 기준을 명확히 만들 수 있다. 반대로 광고, 분석, 위젯 등 제어하기 어려운 외부 자산이 많다면 도입 전에 차단 영향을 먼저 확인해야 한다.

COEP와 CORP, CORS는 어떻게 연결될까?

COEP는 문서 쪽의 요구사항이고, CORP와 CORS는 리소스 쪽의 허용 메커니즘이다. MDN은 require-corp에서 교차 출처 리소스가 로드되려면, no-cors 요청이라면 CORP가 허용해야 하고 cors 요청이라면 CORS 허용을 받아야 한다고 설명한다.

따라서 "COEP를 켰더니 이미지가 안 뜬다"는 상황은 문서 설정만의 문제가 아닐 수 있다. 리소스 제공 서버가 CORP를 보내지 않거나, 프런트엔드가 crossorigin 속성을 통해 CORS 경로로 바꾸지 않았을 가능성을 함께 봐야 한다.

 

 

cross-origin isolation과는 어떤 관계일까?

MDN의 COEP 문서는 문서가 cross-origin isolated 상태가 되려면 COEP가 require-corp 또는 credentialless여야 하고, COOP는 same-origin이어야 한다고 설명한다. 여기에 Permissions-Policy: cross-origin-isolated가 이를 막지 않아야 한다.

web.dev 가이드도 같은 맥락에서, 최상위 문서에 Cross-Origin-Opener-Policy: same-origin과 Cross-Origin-Embedder-Policy: require-corp를 설정해 교차 출처 격리를 만든 뒤 self.crossOriginIsolated로 상태를 확인할 수 있다고 설명한다. 즉 COEP 단독 도입이 아니라 전체 리소스 체인과 팝업 동작까지 같이 점검해야 한다.

도입 전에 확인할 점

• 현재 페이지가 불러오는 이미지, 폰트, 스크립트, iframe 중 교차 출처 자산 목록을 먼저 정리해야 한다.
• require-corp를 검토한다면 각 자산이 CORP 또는 CORS를 지원하는지 확인해야 한다.
• 쿠키가 필요한 교차 출처 no-cors 리소스가 있다면 credentialless와 충돌할 수 있다.
• 교차 출처 격리가 목적이라면 COEP만이 아니라 COOP, Permissions-Policy, 워커 스크립트 로딩 방식까지 함께 점검해야 한다.
• 서드파티 분석 도구나 광고 태그가 많다면 배포 전 네트워크 패널에서 차단 상태를 반드시 확인해야 한다.

FAQ

Q. COEP를 설정하면 CORS 없이도 외부 API를 읽을 수 있나?

아니다. MDN은 cors 모드 요청의 허용은 여전히 CORS가 제어한다고 설명한다. COEP는 문서가 받아들일 수 있는 교차 출처 리소스 조건을 정하는 정책이다.

Q. require-corp를 쓰면 모든 외부 리소스가 차단되나?

그렇게 단순하지 않다. 같은 origin 리소스는 로드할 수 있고, 교차 출처 리소스도 CORP가 허용하거나 CORS로 허용되면 로드할 수 있다.

Q. credentialless는 require-corp의 완전한 대체인가?

아니다. MDN은 credentialless가 일부 no-cors 교차 출처 리소스를 CORP 없이 불러오게 해주지만, 요청에서 쿠키를 빼고 응답 쿠키도 무시한다고 설명한다. 쿠키 의존 자산이 있으면 동작이 달라질 수 있다.

정리

COEP는 외부 리소스를 얼마나 엄격하게 받아들일지 정하는 문서 정책이다. 2026년 6월 6일 기준 공식 문서상 기본 판단은 명확하다. 교차 출처 격리나 더 엄격한 리소스 통제가 필요하면 require-corp부터 검토하고, 일부 no-cors 자산을 쿠키 없이 허용해야 할 때만 credentialless를 본다.

중요한 것은 COEP를 단독 옵션으로 보지 않는 것이다. 실제 운영에서는 CORP, CORS, COOP, 그리고 현재 페이지가 불러오는 서드파티 자산 구조를 함께 봐야 차단 없이 적용할 수 있다.

참고 자료

• MDN: Cross-Origin-Embedder-Policy header
• MDN: Cross-Origin Resource Policy (CORP)
• MDN: Cross-Origin-Opener-Policy header
• web.dev: Making your website cross-origin isolated using COOP and COEP