API 设计 / 系统课时

实施字段级授权

实施字段级授权

本课把授权从“根 Resolver 里判断一次角色”细化到对象、字段和业务动作三个层次。你将实现可运行的 Apollo Server 示例:对象不可见时隐藏资源,敏感字段单独拒绝,修改动作再按所有权或管理员身份检查。

学习目标

  • 区分对象级、字段级与业务动作级授权各自保护的边界。
  • 在具体字段 Resolver 中执行最小权限检查,避免根节点授权被子字段绕过。
  • 设计拒绝策略,使不存在、不可见和无权修改等场景不会意外泄漏敏感信息。

为什么根 Resolver 检查不够

GraphQL 客户端可以自由选择字段。即使 Query.project 已确认用户能看到某个项目,也不代表该用户可以读取项目上的 secretNotes;同样,能读取对象也不代表能执行 renameProject。

GraphQL 对象字段与业务动作的分层授权

授权规则最好围绕资源和动作表达,例如“用户是否能查看这个项目”“用户是否能读取这个敏感字段”“用户是否能重命名这个项目”。这样规则可以复用,也更容易测试,而不是把大量 if (role === ...) 散在业务代码里。

实现三层授权

示例使用 Node.js 20+、Apollo Server 5 与 GraphQL.js 16.11+。为聚焦授权逻辑,x-demo-user 只用于模拟“认证层已经得到可信用户”;生产环境绝不能信任客户端直接声明用户名或角色。

bash
npm install @apollo/server@^5 graphql@^16.11

预期结果:

text
安装完成,npm 进程退出码为 0;added/audited 数量会随锁文件变化。

保存为 server.mjs:

js
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { GraphQLError } from 'graphql';

const users = new Map([
  ['alice', { id: 'u1', role: 'MEMBER' }],
  ['bob', { id: 'u2', role: 'MEMBER' }],
  ['admin', { id: 'u3', role: 'ADMIN' }],
]);

const projects = new Map([
  ['p1', {
    id: 'p1',
    name: 'Roadmap',
    ownerId: 'u1',
    memberIds: ['u1', 'u2'],
    secretNotes: 'Budget freeze',
  }],
]);

const typeDefs = `#graphql
  type Project {
    id: ID!
    name: String!
    ownerId: ID!
    secretNotes: String
  }

  type Query {
    project(id: ID!): Project
  }

  type Mutation {
    renameProject(id: ID!, name: String!): Project!
  }
`;

function requireUser(contextValue) {
  if (contextValue.user) return contextValue.user;
  throw new GraphQLError('需要有效身份', {
    extensions: { code: 'UNAUTHENTICATED' },
  });
}

function canSeeProject(user, project) {
  return user.role === 'ADMIN' || project.memberIds.includes(user.id);
}

function canRenameProject(user, project) {
  return user.role === 'ADMIN' || project.ownerId === user.id;
}

const resolvers = {
  Query: {
    project: (_, { id }, contextValue) => {
      const user = requireUser(contextValue);
      const project = projects.get(id);

      // 对象不可见时返回 null,避免向无权用户确认资源是否存在。
      if (!project || !canSeeProject(user, project)) return null;
      return project;
    },
  },

  Project: {
    secretNotes: (project, _, contextValue) => {
      const user = requireUser(contextValue);

      // 即使父对象可见,敏感字段仍要独立授权。
      if (user.role !== 'ADMIN') {
        throw new GraphQLError('无权读取 secretNotes', {
          extensions: { code: 'FORBIDDEN' },
        });
      }
      return project.secretNotes;
    },
  },

  Mutation: {
    renameProject: (_, { id, name }, contextValue) => {
      const user = requireUser(contextValue);
      const project = projects.get(id);

      if (!project || !canSeeProject(user, project)) {
        throw new GraphQLError('项目不存在', {
          extensions: { code: 'NOT_FOUND' },
        });
      }
      if (!canRenameProject(user, project)) {
        throw new GraphQLError('无权重命名项目', {
          extensions: { code: 'FORBIDDEN' },
        });
      }

      project.name = name;
      return project;
    },
  },
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
  includeStacktraceInErrorResponses: false,
});

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
  context: async ({ req }) => {
    const demoName = req.headers['x-demo-user'];
    const user = typeof demoName === 'string'
      ? users.get(demoName) ?? null
      : null;
    return { user };
  },
});

console.log(`Server ready at ${url}`);

启动服务:

bash
node server.mjs

预期输出:

text
Server ready at http://localhost:4000/

验证字段和动作授权

先让项目所有者 Alice 查询普通字段与敏感字段,再让 Bob 尝试重命名同一项目:

bash
curl -s http://localhost:4000/ -H 'content-type: application/json' -H 'x-demo-user: alice' --data '{"query":"query { project(id: \"p1\") { id name secretNotes } }"}'
curl -s http://localhost:4000/ -H 'content-type: application/json' -H 'x-demo-user: bob' --data '{"query":"mutation { renameProject(id: \"p1\", name: \"New Name\") { id name } }"}'

预期结果:

text
第一条请求:project.id 与 project.name 正常返回;secretNotes 为 null,并在 errors 中出现 extensions.code=FORBIDDEN。
第二条请求:renameProject 被拒绝,errors 中出现 extensions.code=FORBIDDEN,项目名称保持 Roadmap。

字段级拒绝发生在一个可空字段上,因此 GraphQL 可以把 secretNotes 置为 null,同时保留同一对象中已经成功解析的其他字段。如果敏感字段被声明为非空,错误可能触发 GraphQL 的 null bubbling,让更上层对象也变成 null,Schema 设计时要把这一行为纳入考虑。

让授权规则跟着数据边界走

对象级授权适合决定某条资源能否进入 GraphQL 结果,字段级授权适合保护同一对象中权限不同的属性,业务动作授权则保护“修改、发布、退款、审批”这类有副作用的能力。三者可以共享策略函数,但不应互相替代。

高敏感系统还应在服务层或数据层保留第二道授权边界,避免 GraphQL 之外的调用路径绕过检查。Resolver 负责把 GraphQL 字段和业务权限连接起来,但真正的安全边界不应只依赖“某个根 Resolver 已经检查过一次”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实施字段级授权

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通