API 设计 / 系统课时

实现请求身份认证

实现请求身份认证

本课把“客户端带着凭证访问 GraphQL”落实为可运行的请求级认证链路:从 HTTP 头读取 Bearer Token,完成密码学验证,再只把 user.id 与 user.role 注入 contextValue,让后续 Resolver 基于可信身份做授权。

学习目标

  • 区分凭证提取、令牌验证与请求级 Context 注入的职责边界。
  • 使用 Apollo Server 5 与 jose 验证 JWT,并生成最小身份对象。
  • 正确处理缺失、格式错误和无效令牌,而不是直接信任客户端声明。

认证链路应该放在哪里

GraphQL 的认证入口通常位于 HTTP 集成层,而不是散落在每个 Resolver 中。服务器每次收到请求时读取 Authorization,验证令牌签名以及 issuer、audience、有效期等约束,成功后再生成请求独享的 contextValue。

Bearer Token 到请求级 Context 的认证数据流

Context 的职责是共享“本次请求已经确认过的信息”,不是存放整份用户档案。把访问令牌、刷新令牌、密码散列或不必要的个人字段塞进 Context,会扩大日志泄漏和误用风险。对大多数 Resolver,id、角色或权限集合已经足够。

实现最小 JWT 认证

示例使用 Node.js 20+、Apollo Server 5、GraphQL.js 16.11+ 与 jose。先安装依赖:

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

预期结果:

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

保存下面代码为 server.mjs。示例为了便于本地运行使用 HS256 共享密钥;生产环境通常应接入 OIDC/JWKS 或其他可轮换的非对称密钥体系。

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

const rawSecret = process.env.JWT_SECRET;
if (!rawSecret) throw new Error('JWT_SECRET is required');
const secret = new TextEncoder().encode(rawSecret);

const typeDefs = `#graphql
  type User {
    id: ID!
    role: String!
  }

  type Query {
    publicPing: String!
    me: User!
  }
`;

async function authenticate(authorization) {
  if (!authorization) return { user: null, authError: null };

  const match = /^Bearer\s+(.+)$/i.exec(authorization);
  if (!match) return { user: null, authError: 'MALFORMED_CREDENTIALS' };

  try {
    const { payload } = await jwtVerify(match[1], secret, {
      algorithms: ['HS256'],
      issuer: 'anystack-demo',
      audience: 'graphql-api',
    });

    if (typeof payload.sub !== 'string') {
      return { user: null, authError: 'MISSING_SUBJECT' };
    }

    // 只保留 Resolver 真正需要的最小身份信息。
    const role = payload.role === 'ADMIN' ? 'ADMIN' : 'USER';
    return { user: { id: payload.sub, role }, authError: null };
  } catch {
    return { user: null, authError: 'INVALID_TOKEN' };
  }
}

function requireUser(contextValue) {
  if (contextValue.user) return contextValue.user;

  throw new GraphQLError('需要有效身份', {
    extensions: {
      code: 'UNAUTHENTICATED',
      reason: contextValue.authError ?? 'MISSING_TOKEN',
    },
  });
}

const resolvers = {
  Query: {
    publicPing: () => 'pong',
    me: (_, __, contextValue) => requireUser(contextValue),
  },
};

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

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
  context: async ({ req }) => authenticate(req.headers.authorization),
});

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

启动服务:

bash
JWT_SECRET='dev-secret-change-me' node server.mjs

预期输出:

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

发送一个已认证请求

为了只验证认证链路,可以用同一密钥即时签发一个 10 分钟有效的测试令牌,再请求 me。令牌本身是动态值,因此不打印到终端。

bash
TOKEN=$(JWT_SECRET='dev-secret-change-me' node --input-type=module -e "import { SignJWT } from 'jose'; const key=new TextEncoder().encode(process.env.JWT_SECRET); console.log(await new SignJWT({role:'USER'}).setProtectedHeader({alg:'HS256'}).setSubject('user-42').setIssuer('anystack-demo').setAudience('graphql-api').setExpirationTime('10m').sign(key));")
curl -s http://localhost:4000/ -H 'content-type: application/json' -H "authorization: Bearer $TOKEN" --data '{"query":"query { me { id role } }"}'

预期输出:

json
{"data":{"me":{"id":"user-42","role":"USER"}}}

把 Authorization 删除后再次查询 me,Resolver 会返回 UNAUTHENTICATED。如果请求携带格式错误或验签失败的令牌,Context 仍不会获得用户身份,并会记录对应的认证失败原因。

生产环境的边界

身份认证与业务授权应分开:认证层回答“你是谁”,字段和业务动作的授权层回答“你能做什么”。不要因为根查询已经验过令牌,就假设其下所有字段都能返回。

对于 OIDC 访问令牌,除签名外还应验证受信任的发行者、目标受众、过期时间,并根据密钥轮换策略获取 JWKS。若使用服务端 Session,同样应先验证会话有效性,再把最小用户标识注入请求级 Context;不要让客户端直接提交 userId 或 role 来冒充认证结果。

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

目录与阅读设置

阅读设置

17

记录一个想法

实现请求身份认证

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

登录哪都通