CORS 凭证允许配置

配置项作用 #

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

配置建议 #

默认配置（不涉及认证） #

http:
  cors:
    enabled: true
    allow-origin: "*"
    allow-credentials: false  # 默认值

建议: 保持默认值 false。适用于不需要认证的公开 API。

需要 Cookie 认证 #

http:
  cors:
    enabled: true
    allow-origin: "https://myapp.example.com"
    allow-credentials: true

建议: 设置为 true。当需要使用基于 Cookie 的认证时使用。

需要 JWT Token 认证 #

http:
  cors:
    enabled: true
    allow-origin: "https://dashboard.example.com"
    allow-credentials: true

建议: 设置为 true。当需要通过 Authorization 头传递 Token 时使用。

多域名支持 #

http:
  cors:
    enabled: true
    allow-origin: "https://app1.example.com,https://app2.example.com"
    allow-credentials: true

建议: 设置为 true。允许多个前端域名访问认证 API。

代码示例 #

easysearch.yml 基础配置 #

http:
  cors:
    enabled: true
    allow-origin: "https://example.com"
    allow-credentials: true

开发环境配置 #

http:
  cors:
    enabled: true
    allow-origin: "http://localhost:3000"
    allow-credentials: true
    allow-headers: "X-Requested-With,Content-Type,Content-Length,Authorization"

生产环境配置 #

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

相关配置 #

前端配置示例 #

Fetch API 配置 #

// 启用凭证的跨域请求
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 配置 #

// 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 配置 #

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 相关的错误日志，及时发现配置问题。