AWS CORS 預檢請求與設定指南

更新日期： 2024 年 12 月 18 日

在網頁應用程式開發中，當前端發送跨來源請求時，瀏覽器會先發送一個 OPTIONS 請求來確認伺服器是否允許這個請求，這被稱為 CORS 預檢請求（preflight request）。

為了提升效能並減少重複的預檢請求，我們可以使用 MaxAgeSeconds 設定預檢結果的有效時間，讓瀏覽器在一段時間內使用緩存的 CORS 設定，而不需要重新發送 OPTIONS 請求。

本文將解釋 CORS 的主要設定參數，並教你如何根據需求配置。

什麼是 CORS 與預檢請求？

• CORS（Cross-Origin Resource Sharing）：一種允許跨來源請求的標準機制，例如從 https://example.com 發送請求到 https://api.example.com。
• 預檢請求：瀏覽器在發送實際的跨來源請求之前，會先發送一個 OPTIONS 請求，確認伺服器是否允許該操作。
• MaxAgeSeconds：用來設定瀏覽器緩存預檢結果的時間，單位為秒。

CORS 設定範例

以下是常見的 CORS 設定 JSON 格式：

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "POST", "PUT", "DELETE"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3600
  }
]

這段設定包含幾個重要參數，下面將進一步解析每個參數的用途和意義。

CORS 參數解析

AllowedHeaders（允許的標頭）

• 用途：定義哪些自定義 HTTP 標頭可以在跨來源請求中使用。
• 設定值："*" 表示允許所有標頭，例如 Content-Type, Authorization 等。
• 範例：

"AllowedHeaders": ["Content-Type", "Authorization"]

表示只允許 Content-Type 和 Authorization 這兩個標頭。

補充：什麼是自定義標頭

自定義 HTTP 標頭 是指開發者根據應用需求，額外新增的 HTTP 請求或回應標頭。

這些標頭不屬於標準的 HTTP 協議標頭（如 Content-Type、Authorization 等），而是由開發者自行定義，用來傳遞特定資訊，實現自訂功能或提升應用程式的靈活性。

HTTP 標頭的基本概念

HTTP 標頭是 HTTP 請求與回應中的關鍵部分，用於傳遞與請求或回應相關的額外資訊。

例如：

• 請求標頭：用於向伺服器提供請求相關的資訊。
  • 標準範例：Content-Type（指定請求的內容類型）
• 回應標頭：用於伺服器提供給客戶端的資訊。
  • 標準範例：Content-Length（指定回應的大小）

然而，當標準標頭無法滿足特定需求時，開發者可以定義自己的標頭，這些就稱為「自定義 HTTP 標頭」。

自定義標頭的命名規則

• 自定義標頭通常以 X- 或其他前綴開頭，以區分標準標頭。
• 雖然 HTTP/2 標準已建議避免使用 X- 前綴，但許多現有系統仍沿用此慣例。
• 現在更推薦直接使用描述性名稱，例如 App-、Custom- 等前綴，保持標頭語義清晰。

範例：自定義標頭命名

• X-Request-ID：用於追蹤單個請求的唯一識別碼。
• X-Custom-Auth：傳遞自定義的驗證資訊。
• App-Version：用於傳遞應用程式版本號。

自定義 HTTP 標頭的用途

1. 傳遞額外資訊

• 在請求或回應中傳遞自定義的應用程式資訊。
• 範例：
  客戶端傳送請求時，帶上應用程式版本號：

GET /api/data  
App-Version: 1.2.3  

• 伺服器可根據此標頭判斷應用程式的版本，返回相應的資料。

2. 追蹤請求或日誌記錄

• 用於伺服器端的日誌記錄或請求追蹤，方便後續排查問題。
• 範例：

X-Request-ID: 123e4567-e89b-12d3-a456-426614174000  

• 伺服器可以根據這個唯一 ID 追蹤整個請求流程。

3. 自定義安全驗證

• 傳遞自標頭，用來輔助驗證請求或增加安全性。
• 範例：自定義標頭攜帶驗證資訊：

GET /api/secure-data  
X-Custom-Auth: custom-token-123456  

• 伺服器可以解析 X-Custom-Auth 標頭來驗證請求是否合法。

4. 解決 CORS 問題

• 在跨來源資源共享（CORS）中，伺服器需要明確指定哪些自定義標頭可供客戶端存取。
• 例如：

"ExposeHeaders": ["X-Custom-Header", "X-Request-ID"]

• 這樣前端程式就能讀取回應中的自定義標頭資訊。

5. 客製化應用邏輯

• 自定義標頭可根據不同的需求觸發特定應用邏輯，例如切換語言、指定回應格式等。
• 範例：請求標頭攜帶語言設定：

GET /api/data  
X-Language: zh-TW  

• 伺服器可以根據 X-Language 的值回傳對應語言的內容。

AllowedMethods（允許的 HTTP 方法）

• 用途：定義允許哪些 HTTP 方法 可以進行跨來源請求。
• 常用方法：
  • GET：用於讀取資料。
  • POST：用於提交或新增資料。
  • PUT：用於更新資源。
  • DELETE：用於刪除資源。
• 範例：

"AllowedMethods": ["GET", "POST"]

表示只允許 GET 和 POST 方法。

AllowedOrigins（允許的來源）

• 用途：定義哪些網域可以發送跨來源請求到伺服器。
• 設定值：
  • "*"：允許所有網域存取。
  • 指定網域：例如 ["https://example.com"]。
• 範例：

"AllowedOrigins": ["https://example.com"]

表示只允許來自 https://example.com 的請求。

ExposeHeaders（可公開的標頭）

• 用途：定義哪些自定義標頭可以讓前端程式存取。
• 預設情況：瀏覽器僅允許前端存取少數預設標頭，例如 Content-Type。
• 範例：

"ExposeHeaders": ["X-Custom-Header"]

表示允許前端存取 X-Custom-Header 標頭。

MaxAgeSeconds（預檢結果的緩存時間）

• 用途：設定 OPTIONS 預檢結果的有效時間，單位是「秒」。
• 效果：在指定時間內，瀏覽器會緩存預檢結果，不會再次發送 OPTIONS 請求。
• 範例：

"MaxAgeSeconds": 3600

表示預檢結果有效時間為 3600 秒（1 小時）。

範例說明

CORS 設定的含義

根據以下設定：

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "POST", "PUT", "DELETE"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3600
  }
]

• AllowedOrigins：允許所有網域發送跨來源請求。
• AllowedMethods：允許 GET、POST、PUT 和 DELETE 方法。
• AllowedHeaders：允許所有自定義標頭。
• ExposeHeaders：沒有公開自定義標頭（空陣列）。
• MaxAgeSeconds：預檢結果會被瀏覽器緩存 1 小時，減少重複的 OPTIONS 請求。

CORS 設定小技巧

1. 開發階段使用「*」
   • 在開發階段，可以將 AllowedOrigins 和 AllowedHeaders 設為 "*"，方便測試。
   • 上線後，務必設定具體的來源和標頭，避免安全風險。
2. 精確設置 AllowedOrigins
   • 限定來源網域，僅允許可信的網站發送跨來源請求，增加安全性。
3. 設置合理的 MaxAgeSeconds
   • 適當延長預檢結果的緩存時間，減少 OPTIONS 請求次數，提升效能。
   • 例如：MaxAgeSeconds 設為 3600 秒（1 小時）或更長時間。
4. 公開標頭時謹慎使用 ExposeHeaders
   • 只公開必要的標頭，避免暴露敏感資訊。

結論

CORS 設定是解決跨來源資源存取的重要機制，它允許前端和後端安全地進行跨來源通信。

理解並合理配置 CORS 參數，能有效保護系統安全並提高效能。