API 设计 / 系统课时
实现请求身份认证
实现请求身份认证
本课把“客户端带着凭证访问 GraphQL”落实为可运行的请求级认证链路:从 HTTP 头读取 Bearer Token,完成密码学验证,再只把 user.id 与 user.role 注入 contextValue,让后续 Resolver 基于可信身份做授权。
学习目标
- 区分凭证提取、令牌验证与请求级 Context 注入的职责边界。
- 使用 Apollo Server 5 与
jose验证 JWT,并生成最小身份对象。 - 正确处理缺失、格式错误和无效令牌,而不是直接信任客户端声明。
认证链路应该放在哪里
GraphQL 的认证入口通常位于 HTTP 集成层,而不是散落在每个 Resolver 中。服务器每次收到请求时读取 Authorization,验证令牌签名以及 issuer、audience、有效期等约束,成功后再生成请求独享的 contextValue。

Context 的职责是共享“本次请求已经确认过的信息”,不是存放整份用户档案。把访问令牌、刷新令牌、密码散列或不必要的个人字段塞进 Context,会扩大日志泄漏和误用风险。对大多数 Resolver,id、角色或权限集合已经足够。
实现最小 JWT 认证
示例使用 Node.js 20+、Apollo Server 5、GraphQL.js 16.11+ 与 jose。先安装依赖:
npm install @apollo/server@^5 graphql@^16.11 jose@^6预期结果:
安装完成,npm 进程退出码为 0;added/audited 数量会随锁文件变化。保存下面代码为 server.mjs。示例为了便于本地运行使用 HS256 共享密钥;生产环境通常应接入 OIDC/JWKS 或其他可轮换的非对称密钥体系。
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}`);启动服务:
JWT_SECRET='dev-secret-change-me' node server.mjs预期输出:
Server ready at http://localhost:4000/发送一个已认证请求
为了只验证认证链路,可以用同一密钥即时签发一个 10 分钟有效的测试令牌,再请求 me。令牌本身是动态值,因此不打印到终端。
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 } }"}'预期输出:
{"data":{"me":{"id":"user-42","role":"USER"}}}把 Authorization 删除后再次查询 me,Resolver 会返回 UNAUTHENTICATED。如果请求携带格式错误或验签失败的令牌,Context 仍不会获得用户身份,并会记录对应的认证失败原因。
生产环境的边界
身份认证与业务授权应分开:认证层回答“你是谁”,字段和业务动作的授权层回答“你能做什么”。不要因为根查询已经验过令牌,就假设其下所有字段都能返回。
对于 OIDC 访问令牌,除签名外还应验证受信任的发行者、目标受众、过期时间,并根据密钥轮换策略获取 JWKS。若使用服务端 Session,同样应先验证会话有效性,再把最小用户标识注入请求级 Context;不要让客户端直接提交 userId 或 role 来冒充认证结果。