GraphQL 安全全面指南

1. GraphQL 基础概念

1.1 GraphQL 简介

GraphQL 是由 Facebook 创造并开源的一种用于 API 的查询语言，具有以下核心特点：

• 精确数据获取：请求所需数据，不多不少
• 单一请求获取多资源：通过一次请求获取应用所需所有数据
• 强类型系统：基于类型和字段组织，提供清晰错误信息

1.2 核心组成部分

1. Type：描述数据模型，包括标量(Scalar)和对象(Object)类型
2. Schema：描述接口获取数据的逻辑
3. Query：查询类型，包括：
   • Query（查询）
   • Mutation（更改）
   • Subscription（订阅）
4. Resolver：描述每个查询的解析逻辑

1.3 GraphQL vs RESTful

• 单路由形态，查询内容由前端请求决定
• 不依赖 HTTP 协议，有自己的解析引擎
• 前后端分离更明显

2. GraphQL 安全风险与防护

2.1 身份认证与权限控制不当

风险表现

• 未授权访问敏感接口
• 越权访问高危操作接口

示例攻击

query GetAllUsers {
  users {
    _id
    username
    password
    idCard
    mobilePhone
    email
  }
}

防护措施

• 将授权逻辑委托给业务逻辑层
• 对所有 Query 和 Mutation 实施细粒度权限控制

2.2 信息泄露（内省机制）

风险表现

• 通过内省查询获取全量 API 信息
• 暴露废弃字段和测试字段

内省查询示例

# 查询所有可用对象
{
  __schema {
    types {
      name
    }
  }
}

# 查询指定对象的所有字段（包括废弃字段）
{
  __type(name: "User") {
    name
    fields(includeDeprecated: true) {
      name
      isDeprecated
      type {
        name
      }
    }
  }
}

防护措施

• 生产环境禁用或限制内省功能
• 定期审查和清理废弃字段
• 实现字段级别的访问控制

2.3 自动绑定与非预期字段

风险表现

• 字段扩展导致敏感信息意外暴露
• 废弃字段仍可被查询利用

防护措施

• 实施字段级别的权限控制
• 彻底移除而非仅标记废弃敏感字段
• 定期审计 Schema 定义

3. GraphQL 认证实现方案

3.1 独立认证终端（RESTful）

• 使用 JWT 等标准认证机制
• GraphQL 路由加入认证中间件
• 开放独立登录/注册 RESTful 接口

3.2 GraphQL 内认证

• 构建专门的 login Query
• 返回中包含认证 Token
• 示例 Schema：

type Query {
  login(
    username: String!
    password: String!
  ): LoginMsg
}

type LoginMsg {
  message: String
  token: String
}

3.3 权限控制实现

• 在 Resolver 中检查上下文用户权限
• 示例 Node.js 实现：

users: (root, args, context) => {
  if (!context.user || !context.user.roles.includes('admin')) 
    throw new ForbiddenError("You must be an administrator");
  return User.getAll();
}

4. GraphQL 注入防护

4.1 注入风险

• 直接拼接用户输入导致语句结构改变
• SQL/NoSQL 注入风险

4.2 安全实践

• 使用参数化查询而非字符串拼接
• 正确使用变量传递参数：

query GetUser($name: String {
  user(username: $name) {
    _id
    username
    email
  }
}

• 对所有输入进行严格验证和清理

5. 拒绝服务防护

5.1 风险表现

• 嵌套查询导致无限循环
• 深度查询消耗大量资源

5.2 防护措施

• 限制查询深度（示例 Node.js 实现）：

import depthLimit from 'graphql-depth-limit';

const server = new ApolloServer({
  // ...其他配置
  validationRules: [depthLimit(10)]
});

• 避免设计可循环引用的类型结构
• 实施查询复杂度分析

6. 其他安全注意事项

1. CSRF 防护：

   • GraphQL 支持 GET 和 POST 方法
   • 需实施与传统 Web 应用相同的 CSRF 防护措施

2. 生产环境配置：

   • 禁用 GraphiQL 等调试工具
   • 关闭开发模式下的详细错误信息

3. 类型系统安全：

   • 充分利用 GraphQL 强类型系统进行输入验证
   • 自定义标量类型进行严格数据校验

4. 日志与监控：

   • 记录所有 GraphQL 查询
   • 监控异常查询模式

7. 最佳实践总结

1. 认证与授权：

   • 实施端到端认证
   • 细粒度权限控制（类型/字段级别）

2. 输入处理：

   • 永远不信任客户端输入
   • 使用变量而非拼接查询

3. 信息暴露：

   • 严格控制内省功能
   • 彻底移除而非仅标记废弃敏感字段

4. 资源保护：

   • 限制查询深度和复杂度
   • 实施速率限制

5. 安全开发：

   • 定期审计 Schema 定义
   • 保持 GraphQL 引擎更新

8. 参考资源

1. GraphQL 官方学习文档
2. GraphQL 安全基础
3. GraphQL 安全概述与测试技巧
4. GraphQL 认证指南
5. Apollo 安全指南