--- title: "CORS 凭证允许配置" date: 2026-03-03 lastmod: 2026-03-03 description: "http.cors.allow-credentials 配置项用于控制是否允许在跨域请求中发送凭证信息。" tags: ["HTTP", "CORS", "跨域", "安全认证"] summary: "配置项作用 # http.cors.allow-credentials 配置项用于控制在跨域资源共享（CORS）响应中是否包含 Access-Control-Allow-Credentials 头。 当启用此配置时，浏览器可以在跨域请求中发送包含凭证的请求，如 Cookies、HTTP 认证信息或客户端 SSL 证书。 配置项属性 # 配置路径: http.cors.allow-credentials 数据类型: Boolean（布尔值） 默认值: false 是否可选: 是 作用域: NodeScope（节点级别） 配置项详解 # 工作机制 # CORS 凭证处理流程 浏览器发起跨域请求 │ ↓ 检查是否携带凭证 │ ├──────── 无凭证请求 │ ↓ │ 正常 CORS 处理 │ ↓ │ 返回数据 │ └──────── 有凭证请求 ↓ 服务器检查配置 │ ├──────── allow-credentials = false │ ↓ │ 拒绝请求 ❌ │ ↓ │ 浏览器阻止响应 │ └──────── allow-credentials = true ↓ 验证来源域名 │ ├──────── 来源匹配 ✅ │ ↓ │ 返回数据 + 凭证头 │ └──────── 来源不匹配 ❌ ↓ 拒绝请求 CORS 响应头对比 # allow-credentials = false (默认): 响应头: Access-Control-Allow-Origin: * （或不包含此头） 浏览器行为: - 不发送 cookies - 不发送认证信息 - 不接收 Set-Cookie allow-credentials = true: 响应头: Access-Control-Allow-Origin: https://example." --- ## 配置项作用 `http.cors.allow-credentials` 配置项用于控制**在跨域资源共享（CORS）响应中是否包含 `Access-Control-Allow-Credentials` 头**。 当启用此配置时，浏览器可以在跨域请求中发送包含凭证的请求，如 Cookies、HTTP 认证信息或客户端 SSL 证书。 ## 配置项属性 - **配置路径**: `http.cors.allow-credentials` - **数据类型**: `Boolean`（布尔值） - **默认值**: `false` - **是否可选**: 是 - **作用域**: NodeScope（节点级别） ## 配置项详解 ## 工作机制 ``` CORS 凭证处理流程 浏览器发起跨域请求 │ ↓ 检查是否携带凭证 │ ├──────── 无凭证请求 │ ↓ │ 正常 CORS 处理 │ ↓ │ 返回数据 │ └──────── 有凭证请求 ↓ 服务器检查配置 │ ├──────── allow-credentials = false │ ↓ │ 拒绝请求 ❌ │ ↓ │ 浏览器阻止响应 │ └──────── allow-credentials = true ↓ 验证来源域名 │ ├──────── 来源匹配 ✅ │ ↓ │ 返回数据 + 凭证头 │ └──────── 来源不匹配 ❌ ↓ 拒绝请求 ``` ## CORS 响应头对比 ``` allow-credentials = false (默认): 响应头: Access-Control-Allow-Origin: * （或不包含此头） 浏览器行为: - 不发送 cookies - 不发送认证信息 - 不接收 Set-Cookie allow-credentials = true: 响应头: Access-Control-Allow-Origin: https://example.com Access-Control-Allow-Credentials: true Vary: Origin 浏览器行为: - 发送 cookies - 发送认证信息 - 接收 Set-Cookie ``` ## 与 allow-origin 的关系 ``` 重要限制关系 allow-credentials = true 时: ↓ allow-origin 不能为 "*" ↓ 必须指定具体域名 错误配置 ❌: http.cors.allow-origin: "*" http.cors.allow-credentials: true （会导致配置错误） 正确配置 ✅: http.cors.allow-origin: "https://example.com" http.cors.allow-credentials: true ``` ## 配置建议 ## 默认配置（不涉及认证） ```yaml http: cors: enabled: true allow-origin: "*" allow-credentials: false # 默认值 ``` **建议**: 保持默认值 `false`。适用于不需要认证的公开 API。 ## 需要 Cookie 认证 ```yaml http: cors: enabled: true allow-origin: "https://myapp.example.com" allow-credentials: true ``` **建议**: 设置为 `true`。当需要使用基于 Cookie 的认证时使用。 ## 需要 JWT Token 认证 ```yaml http: cors: enabled: true allow-origin: "https://dashboard.example.com" allow-credentials: true ``` **建议**: 设置为 `true`。当需要通过 Authorization 头传递 Token 时使用。 ## 多域名支持 ```yaml http: cors: enabled: true allow-origin: "https://app1.example.com,https://app2.example.com" allow-credentials: true ``` **建议**: 设置为 `true`。允许多个前端域名访问认证 API。 ## 代码示例 ## easysearch.yml 基础配置 ```yaml http: cors: enabled: true allow-origin: "https://example.com" allow-credentials: true ``` ## 开发环境配置 ```yaml http: cors: enabled: true allow-origin: "http://localhost:3000" allow-credentials: true allow-headers: "X-Requested-With,Content-Type,Content-Length,Authorization" ``` ## 生产环境配置 ```yaml http: cors: enabled: true allow-origin: "https://app.example.com,https://admin.example.com" allow-credentials: true allow-headers: "X-Requested-With,Content-Type,Content-Length,Authorization" max-age: 3600 ``` ## 相关配置 | 配置项 | 作用 | 默认值 | |--------|------|--------| | `http.cors.enabled` | 是否启用 CORS | false | | `http.cors.allow-origin` | 允许的来源域名 | - | | `http.cors.allow-credentials` | 是否允许凭证 | false | | `http.cors.allow-headers` | 允许的请求头 | X-Requested-With,Content-Type,Content-Length | | `http.cors.allow-methods` | 允许的 HTTP 方法 | OPTIONS,HEAD,GET,POST,PUT,DELETE | | `http.cors.max-age` | 预检请求缓存时间 | 1728000 | ## 前端配置示例 ## Fetch API 配置 ```javascript // 启用凭证的跨域请求 fetch('https://easysearch.example.com/_cluster/health', { method: 'GET', credentials: 'include', // 必须设置 headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + token } }) .then(response => response.json()) .then(data => console.log(data)); ``` ## Axios 配置 ```javascript // Axios 全局配置 axios.defaults.withCredentials = true; // 单个请求配置 axios.get('https://easysearch.example.com/_cluster/health', { withCredentials: true, headers: { 'Authorization': 'Bearer ' + token } }) .then(response => console.log(response.data)); ``` ## XMLHttpRequest 配置 ```javascript const xhr = new XMLHttpRequest(); xhr.withCredentials = true; // 必须设置 xhr.open('GET', 'https://easysearch.example.com/_cluster/health'); xhr.setRequestHeader('Authorization', 'Bearer ' + token); xhr.send(); ``` ## 使用场景 ## 推荐启用 allow-credentials 的场景 - **Cookie 认证**: 使用 Cookie 进行用户身份验证 - **Session 管理**: 需要维护用户会话状态 - **JWT Token**: 通过 Authorization 头传递 Token - **SSO 集成**: 单点登录系统集成 - **受保护 API**: 需要认证的内部 API ## 推荐禁用 allow-credentials 的场景 - **公开 API**: 不需要认证的公开数据接口 - **静态资源**: 公开的静态数据访问 - **只读操作**: 不涉及数据修改的查询接口 - **第三方集成**: 不需要认证的第三方服务集成 ## 安全注意事项 ## 常见配置错误 ``` 错误 1: allow-origin 为 "*" 且 allow-credentials 为 true http.cors.allow-origin: "*" http.cors.allow-credentials: true 问题: 浏览器会拒绝这种配置 解决: 指定具体域名 错误 2: 未配置 allow-origin http.cors.enabled: true http.cors.allow-credentials: true 问题: 没有指定允许的来源 解决: 必须配置 allow-origin 错误 3: 前端未设置 credentials // 前端代码 fetch(url) // 缺少 credentials: 'include' 问题: 即使服务器允许，浏览器也不会发送凭证 解决: 前端必须设置 withCredentials 或 credentials: 'include' ``` ## 安全最佳实践 ``` 1. 限制允许的来源 http.cors.allow-origin: "https://trusted.example.com" 2. 最小权限原则 http.cors.allow-credentials: true (仅在需要时启用) 3. 明确指定允许的头部 http.cors.allow-headers: "Content-Type,Authorization" 4. 设置合理的缓存时间 http.cors.max-age: 3600 (减少预检请求) 5. 使用 HTTPS http.cors.allow-origin: "https://example.com" (使用 https://) 6. 定期审计 定期检查 CORS 配置是否符合业务需求 ``` ## 注意事项 1. **与 allow-origin 的配合**: 启用 `allow-credentials` 时，`allow-origin` 必须指定具体域名，不能使用 `*`。 2. **前端配置**: 前端应用必须设置 `withCredentials: true` 或 `credentials: 'include'`。 3. **预检请求**: 启用凭证后，浏览器会发送 OPTIONS 预检请求。 4. **Cookie 限制**: 只有配置了 `allow-origin` 的域名才能接收和发送 Cookie。 5. **动态更新**: 此配置支持动态更新，修改后立即生效。 6. **安全性考虑**: 谨慎启用此配置，确保只允许可信的来源域名。 7. **Vary 头**: 服务器会自动添加 `Vary: Origin` 响应头。 8. **浏览器支持**: 现代浏览器都支持 CORS 凭证模式。 9. **认证方案**: 此配置需要与认证方案配合使用（Basic Auth、Bearer Token 等）。 10. **日志监控**: 监控 CORS 相关的错误日志，及时发现配置问题。