Cross-Origin-Embedder-Policy (COEP) header

Cú pháp

Cross-Origin-Embedder-Policy: <token>; <parameter>

Chỉ thị

Tiêu đề chỉ nên được đặt với một token và một tham số report-to tùy chọn. Đặt tiêu đề nhiều lần hoặc với nhiều token tương đương với việc đặt unsafe-none.

Giá trị <token> có thể là một trong:

unsafe-none

Cho phép tài liệu tải các tài nguyên được yêu cầu ở chế độ no-cors mà không cần cấp quyền rõ ràng thông qua tiêu đề Cross-Origin-Resource-Policy. Đây là giá trị mặc định.

require-corp

Tài liệu chỉ có thể tải các tài nguyên được yêu cầu ở chế độ no-cors từ cùng nguồn gốc, hoặc các tài nguyên đã đặt rõ ràng tiêu đề Cross-Origin-Resource-Policy với giá trị cho phép nhúng.

Việc tải tài nguyên khác nguồn gốc sẽ bị COEP chặn trừ khi:

• Tài nguyên được yêu cầu ở chế độ no-cors và phản hồi bao gồm tiêu đề Cross-Origin-Resource-Policy cho phép tải vào nguồn gốc tài liệu.
• Tài nguyên được yêu cầu ở chế độ cors; ví dụ: trong HTML sử dụng thuộc tính crossorigin, hoặc trong JavaScript bằng cách gửi yêu cầu với {mode="cors"}. Lưu ý rằng các yêu cầu được thực hiện ở chế độ cors sẽ không bị COEP chặn hoặc kích hoạt vi phạm COEP, nhưng vẫn phải được CORS cho phép.

credentialless

Tài liệu có thể tải các tài nguyên khác nguồn gốc được yêu cầu ở chế độ no-cors mà không cần quyền rõ ràng thông qua tiêu đề Cross-Origin-Resource-Policy. Trong trường hợp này, các yêu cầu được gửi mà không có thông tin xác thực: cookie bị bỏ qua trong yêu cầu và bị bỏ qua trong phản hồi.

Hành vi tải khác nguồn gốc cho các chế độ yêu cầu khác giống như đối với require-corp. Ví dụ: một tài nguyên khác nguồn gốc được yêu cầu ở chế độ cors phải hỗ trợ (và được CORS cho phép).

Tham số <parameter> là tùy chọn và có thể là:

report-to <endpoint_name> Optional

<endpoint_name> là tên của điểm cuối mà các vi phạm chính sách sẽ được gửi đến. Ánh xạ giữa tên và một điểm cuối cụ thể được xác định riêng trong tiêu đề HTTP Reporting-Endpoints.

Mô tả

Chính sách về việc một tài nguyên cụ thể có thể được nhúng khác trang web có thể được xác định cho tài nguyên đó bằng tiêu đề Cross-Origin-Resource-Policy (CORP) trong phản hồi cho một yêu cầu no-cors, hoặc bằng CORS. Nếu không có chính sách nào trong số này được đặt, thì theo mặc định, các tài nguyên có thể được tải hoặc nhúng vào tài liệu như thể chúng có giá trị CORP là cross-origin (nghĩa là chúng có thể được tải khác nguồn gốc).

Cross-Origin-Embedder-Policy cho phép bạn yêu cầu rằng tiêu đề CORP phải được đặt, trong các phản hồi cho yêu cầu no-cors, để tải các tài nguyên khác trang web vào tài liệu hiện tại. Bạn cũng có thể đặt chính sách để giữ hành vi mặc định, hoặc để cho phép các tài nguyên được tải, nhưng loại bỏ bất kỳ thông tin xác thực nào có thể được gửi. Chính sách áp dụng cho các tài nguyên đã tải, và các tài nguyên trong <iframe> và các khung lồng nhau.

Cách ly khác nguồn gốc

COEP và CORS cùng nhau đảm bảo rằng tiến trình trình duyệt chỉ chứa các tài nguyên đã đồng ý được chia sẻ, hoặc không chứa dữ liệu riêng tư. Đây là một trong những điều kiện cần thiết để tài liệu được cách ly khác nguồn gốc.

Báo cáo vi phạm

Các vi phạm chính sách có thể được báo cáo bằng API Báo cáo. Báo cáo có thể được quan sát trong trang mà chính sách đang được đặt bằng ReportingObserver, và gửi đến các điểm cuối máy chủ được xác định trong tiêu đề phản hồi HTTP Reporting-Endpoints và được chọn bằng tham số report-to. Để biết thêm thông tin, xem COEPViolationReport.

Ví dụ

Chặn và báo cáo khi tài nguyên không đặt tiêu đề CORP

Ví dụ này hiển thị tài liệu chặn việc tải các tài nguyên được yêu cầu ở chế độ no-cors mà không đặt tiêu đề CORP phù hợp.

Tài liệu là tệp HTML được lưu trữ trên nguồn gốc https://example.com, và bao gồm trong phần thân một phần tử <img> đặt làm nguồn tài nguyên some-image.png (khác nguồn gốc). Vì phần tử không có thuộc tính cross-origin, nó sẽ được yêu cầu ở chế độ no-cors:

<img src="https://another-example.com/some-image.png" />

Tiêu đề phản hồi cho tài liệu đặt Cross-Origin-Embedder-Policy và tiêu đề Reporting-Endpoints như hiển thị bên dưới. Vì chỉ thị require-corp được đặt, tất cả tài nguyên khác nguồn gốc được yêu cầu ở chế độ no-cors phải được phục vụ với tiêu đề CORP. Tham số report-to chỉ định tên "coep-endpoint" là tên của điểm cuối nơi báo cáo nên được gửi, và Reporting-Endpoints chỉ định cách tên đó ánh xạ đến một URL cụ thể.

Reporting-Endpoints: coep-endpoint="https://some-example.com/coep"
Cross-Origin-Embedder-Policy: require-corp; report-to="coep-endpoint"

Để some-image.png được tải mà không kích hoạt vi phạm, nó cần đặt Cross-Origin-Resource-Policy thành cross-origin. Nếu chúng ta bỏ qua tiêu đề hoặc không bao gồm nó là cross-origin, một vi phạm sẽ xảy ra.

Báo cáo được gửi trong yêu cầu POST báo cáo sẽ tương tự như đối tượng JSON hiển thị bên dưới:

[
  {
    "age": 717139,
    "body": {
      "blockedURL": "https://another-example.com/some-image.png",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://example.com",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
  }
]

type của báo cáo là coep, và url là tài liệu nơi vi phạm xảy ra. body của báo cáo cung cấp URL của tài nguyên bị chặn (blockedURL), đích của nó (image), loại vi phạm (corp), và rằng báo cáo là cho vi phạm được thực thi (disposition).

Các tính năng phụ thuộc vào cách ly khác nguồn gốc

Một số tính năng nhất định, chẳng hạn như truy cập đối tượng SharedArrayBuffer hoặc sử dụng Performance.now() với bộ đếm thời gian không bị giới hạn, chỉ khả dụng nếu tài liệu của bạn được cách ly khác nguồn gốc.

Để sử dụng các tính năng này trong tài liệu, bạn cần đặt tiêu đề COEP với giá trị require-corp hoặc credentialless, và tiêu đề Cross-Origin-Opener-Policy thành same-origin. Ngoài ra, tính năng không được chặn bởi Permissions-Policy: cross-origin-isolated.

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Bạn có thể sử dụng các thuộc tính Window.crossOriginIsolated và WorkerGlobalScope.crossOriginIsolated để kiểm tra xem các tính năng có bị hạn chế trong ngữ cảnh window và worker hay không:

const myWorker = new Worker("worker.js");

if (crossOriginIsolated) {
  const buffer = new SharedArrayBuffer(16);
  myWorker.postMessage(buffer);
} else {
  const buffer = new ArrayBuffer(16);
  myWorker.postMessage(buffer);
}

Tránh bị COEP chặn với CORS

Nếu bạn bật COEP bằng require-corp và muốn nhúng tài nguyên khác nguồn gốc hỗ trợ CORS, bạn cần chỉ định rõ ràng rằng nó được yêu cầu ở chế độ cors.

Ví dụ: để tải một hình ảnh được khai báo trong HTML từ trang web bên thứ ba hỗ trợ CORS, bạn có thể sử dụng thuộc tính crossorigin để nó được yêu cầu ở chế độ cors:

<img src="https://thirdparty.com/img.png" crossorigin />

Bạn cũng có thể sử dụng thuộc tính HTMLScriptElement.crossOrigin hoặc fetch với { mode: 'cors' } để yêu cầu tệp ở chế độ CORS bằng JavaScript.

Nếu CORS không được hỗ trợ cho một số hình ảnh, giá trị COEP credentialless có thể được sử dụng như một thay thế để tải hình ảnh mà không cần đồng ý rõ ràng từ máy chủ khác nguồn gốc, với chi phí là yêu cầu mà không có cookie.

Đặc tả

Khả năng tương thích trình duyệt

Xem thêm

• Cross-Origin-Embedder-Policy-Report-Only
• Cross-Origin-Opener-Policy
• Window.crossOriginIsolated và WorkerGlobalScope.crossOriginIsolated
• ReportingObserver
• COEPViolationReport
• API Báo cáo
• Cross Origin Opener Policy trong Why you need "cross-origin isolated" for powerful features trên web.dev (2020)
• COOP and COEP explained: Artur Janc, Charlie Reis, Anne van Kesteren (2020)