From 2abd58bb17a261dbdb2b8ca035573ee68b69dd74 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Tue, 16 Jun 2026 12:44:55 -0700 Subject: [PATCH] docs(cors): add Security section on wildcard origin + credentials (#277) Upstream echo#2400 asked for the docs to explain the danger of combining a wildcard origin with AllowCredentials, and the maintainer asked for a security block on echo.labstack.com. The page only had a one-line caution that didn't explain the behaviour or v5's enforcement. Expand it into a "Security" section that explains: - the danger: wildcard origin + AllowCredentials:true reflects any Origin back, enabling credentialed cross-origin attacks; - v5's enforcement: CORS / CORSWithConfig panic and ToMiddleware() returns an error rather than building an insecure middleware; - the safe pattern (explicit origins) and UnsafeAllowOriginFunc for dynamic validation. Applied across all five locales (translated prose, identical code block). Co-Authored-By: Claude Opus 4.8 (1M context) --- site/src/content/docs/es/middleware/cors.md | 25 +++++++++++++++---- site/src/content/docs/ja/middleware/cors.md | 25 +++++++++++++++---- site/src/content/docs/middleware/cors.md | 25 +++++++++++++++---- .../src/content/docs/pt-br/middleware/cors.md | 25 +++++++++++++++---- .../src/content/docs/zh-cn/middleware/cors.md | 22 +++++++++++++--- 5 files changed, 98 insertions(+), 24 deletions(-) diff --git a/site/src/content/docs/es/middleware/cors.md b/site/src/content/docs/es/middleware/cors.md index 4349ee82..139e5514 100644 --- a/site/src/content/docs/es/middleware/cors.md +++ b/site/src/content/docs/es/middleware/cors.md @@ -117,8 +117,23 @@ CORSConfig{ } ``` -:::caution[Seguridad] -Nunca combines `AllowCredentials = true` con un wildcard `AllowOrigins`. Cuando necesites -validación dinámica de origin, usa `UnsafeAllowOriginFunc` y valida con cuidado: -los atacantes pueden registrar nombres de (sub)dominio hostiles. -::: +## Seguridad + +Un origin con wildcard (`AllowOrigins: []string{"*"}`) combinado con `AllowCredentials: true` +es peligroso: reflejaría el `Origin` de **cualquier** petición en +`Access-Control-Allow-Origin`, permitiendo que una página de cualquier sitio haga peticiones +cross-origin con credenciales a tu API (consulta [Exploiting CORS misconfigurations](https://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html)). + +Echo rechaza esta combinación en lugar de construir un middleware inseguro: `CORS` y +`CORSWithConfig` hacen **panic**, y `CORSConfig.ToMiddleware()` devuelve un error. Para permitir +peticiones con credenciales, enumera explícitamente los orígenes de confianza: + +```go +e.Use(middleware.CORSWithConfig(middleware.CORSConfig{ + AllowOrigins: []string{"https://example.com"}, + AllowCredentials: true, +})) +``` + +Para validación dinámica de origin, usa `UnsafeAllowOriginFunc` y valida cada origin con +cuidado: los atacantes pueden registrar nombres de (sub)dominio falsos u hostiles. diff --git a/site/src/content/docs/ja/middleware/cors.md b/site/src/content/docs/ja/middleware/cors.md index 77a80afc..89e4d3b4 100644 --- a/site/src/content/docs/ja/middleware/cors.md +++ b/site/src/content/docs/ja/middleware/cors.md @@ -117,8 +117,23 @@ CORSConfig{ } ``` -:::caution[セキュリティ] -`AllowCredentials = true` とワイルドカードの `AllowOrigins` を組み合わせてはいけません。 -動的な origin 検証が必要な場合は `UnsafeAllowOriginFunc` を使い、慎重に検証してください。 -攻撃者が悪意ある（サブ）ドメイン名を登録する可能性があります。 -::: +## セキュリティ + +ワイルドカード origin（`AllowOrigins: []string{"*"}`）と `AllowCredentials: true` の組み合わせは危険です。 +**任意**のリクエストの `Origin` をそのまま `Access-Control-Allow-Origin` に反射してしまい、 +どのサイトのページからでも認証情報付きのクロスオリジンリクエストを API に送れてしまいます +（[Exploiting CORS misconfigurations](https://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html) を参照）。 + +Echo は安全でないミドルウェアを構築せず、この組み合わせを拒否します。`CORS` と `CORSWithConfig` は **panic** し、 +`CORSConfig.ToMiddleware()` はエラーを返します。認証情報付きのリクエストを許可するには、 +信頼する origin を明示的に列挙してください： + +```go +e.Use(middleware.CORSWithConfig(middleware.CORSConfig{ + AllowOrigins: []string{"https://example.com"}, + AllowCredentials: true, +})) +``` + +動的な origin 検証が必要な場合は `UnsafeAllowOriginFunc` を使い、各 origin を慎重に検証してください。 +攻撃者が偽装または悪意ある（サブ）ドメイン名を登録する可能性があります。 diff --git a/site/src/content/docs/middleware/cors.md b/site/src/content/docs/middleware/cors.md index 9ad02467..fe935d49 100644 --- a/site/src/content/docs/middleware/cors.md +++ b/site/src/content/docs/middleware/cors.md @@ -117,8 +117,23 @@ CORSConfig{ } ``` -:::caution[Security] -Never combine `AllowCredentials = true` with a wildcard `AllowOrigins`. When you need -dynamic origin validation, use `UnsafeAllowOriginFunc` and validate carefully — -attackers may register hostile (sub)domain names. -::: +## Security + +A wildcard origin (`AllowOrigins: []string{"*"}`) combined with `AllowCredentials: true` +is dangerous: it would reflect **any** request's `Origin` back in +`Access-Control-Allow-Origin`, letting a page on any site make credentialed cross-origin +requests to your API (see [Exploiting CORS misconfigurations](https://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html)). + +Echo refuses this combination rather than building an insecure middleware: `CORS` and +`CORSWithConfig` **panic**, and `CORSConfig.ToMiddleware()` returns an error. To allow +credentialed requests, list the trusted origins explicitly: + +```go +e.Use(middleware.CORSWithConfig(middleware.CORSConfig{ + AllowOrigins: []string{"https://example.com"}, + AllowCredentials: true, +})) +``` + +For dynamic origin validation, use `UnsafeAllowOriginFunc` and validate each origin +carefully — attackers may register look-alike or hostile (sub)domain names. diff --git a/site/src/content/docs/pt-br/middleware/cors.md b/site/src/content/docs/pt-br/middleware/cors.md index 8f0c197f..2ca670c1 100644 --- a/site/src/content/docs/pt-br/middleware/cors.md +++ b/site/src/content/docs/pt-br/middleware/cors.md @@ -117,8 +117,23 @@ CORSConfig{ } ``` -:::caution[Segurança] -Nunca combine `AllowCredentials = true` com um wildcard `AllowOrigins`. Quando precisar -de validação dinâmica de origem, use `UnsafeAllowOriginFunc` e valide cuidadosamente — -atacantes podem registrar nomes de (sub)domínio hostis. -::: +## Segurança + +Um origin curinga (`AllowOrigins: []string{"*"}`) combinado com `AllowCredentials: true` +é perigoso: ele refletiria o `Origin` de **qualquer** requisição em +`Access-Control-Allow-Origin`, permitindo que uma página de qualquer site faça requisições +cross-origin com credenciais à sua API (veja [Exploiting CORS misconfigurations](https://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html)). + +O Echo recusa essa combinação em vez de construir um middleware inseguro: `CORS` e +`CORSWithConfig` causam **panic**, e `CORSConfig.ToMiddleware()` retorna um erro. Para permitir +requisições com credenciais, liste explicitamente as origens confiáveis: + +```go +e.Use(middleware.CORSWithConfig(middleware.CORSConfig{ + AllowOrigins: []string{"https://example.com"}, + AllowCredentials: true, +})) +``` + +Para validação dinâmica de origem, use `UnsafeAllowOriginFunc` e valide cada origem com +cuidado — atacantes podem registrar nomes de (sub)domínio falsos ou hostis. diff --git a/site/src/content/docs/zh-cn/middleware/cors.md b/site/src/content/docs/zh-cn/middleware/cors.md index 8ae797f3..b78c0492 100644 --- a/site/src/content/docs/zh-cn/middleware/cors.md +++ b/site/src/content/docs/zh-cn/middleware/cors.md @@ -117,7 +117,21 @@ CORSConfig{ } ``` -:::caution[安全] -永远不要把 `AllowCredentials = true` 与通配符 `AllowOrigins` 组合使用。需要动态 origin -验证时，请使用 `UnsafeAllowOriginFunc` 并仔细验证，攻击者可能注册恶意（子）域名。 -::: +## 安全 + +通配符 origin（`AllowOrigins: []string{"*"}`）与 `AllowCredentials: true` 组合使用非常危险： +它会把**任意**请求的 `Origin` 原样反射到 `Access-Control-Allow-Origin` 中，使得任意网站上的页面 +都能向你的 API 发起携带凭证的跨域请求（参见 [Exploiting CORS misconfigurations](https://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html)）。 + +Echo 会拒绝这种组合，而不是构建不安全的中间件：`CORS` 和 `CORSWithConfig` 会 **panic**， +`CORSConfig.ToMiddleware()` 会返回错误。要允许携带凭证的请求，请显式列出受信任的 origin： + +```go +e.Use(middleware.CORSWithConfig(middleware.CORSConfig{ + AllowOrigins: []string{"https://example.com"}, + AllowCredentials: true, +})) +``` + +需要动态 origin 验证时，请使用 `UnsafeAllowOriginFunc` 并仔细验证每个 origin—— +攻击者可能注册仿冒或恶意的（子）域名。