15分钟上手：Apollo Server集成Passkey认证中间件实战

15分钟上手：Apollo Server集成Passkey认证中间件实战

【免费下载链接】hanko Auth and user management for the passkey era 项目地址: https://gitcode.com/GitHub_Trending/ha/hanko

为什么需要Passkey时代的GraphQL认证？

传统JWT认证面临密钥泄露、Token劫持等风险，而Hanko提供的基于WebAuthn（Web认证）标准的Passkey（密码钥匙）认证，通过公钥加密实现无密码登录，彻底解决密码安全痛点。本文将手把手教你如何在Apollo Server中集成Hanko认证中间件，构建符合FIDO2标准的安全GraphQL网关。

核心依赖与项目结构

Hanko提供前端SDK与后端API的完整认证生态，关键模块包括：

• 前端认证交互：frontend/frontend-sdk/src/Hanko.ts
• 后端会话管理：backend/session/session.go
• WebAuthn协议实现：backend/webauthn/

Step 1：安装Hanko前端SDK

通过npm引入Hanko SDK，实现Passkey注册与认证流程：

npm install @teamhanko/hanko-frontend-sdk

初始化Hanko客户端连接后端API：

import { Hanko } from "@teamhanko/hanko-frontend-sdk";

const hanko = new Hanko("https://your-hanko-api.com", {
  timeout: 15000,
  sessionCheckInterval: 30000
});

Step 2：实现Apollo认证中间件

创建hankoAuthMiddleware.ts，验证GraphQL请求中的Hanko会话令牌：

import { ApolloServerPlugin, GraphQLRequestContext } from "@apollo/server";
import { Hanko } from "@teamhanko/hanko-frontend-sdk";

export const hankoAuthPlugin: ApolloServerPlugin = {
  async requestDidStart(context: GraphQLRequestContext) {
    const token = context.request.http?.headers.get("authorization")?.split(" ")[1];
    if (!token) throw new Error("Unauthorized");

    const hanko = new Hanko("https://your-hanko-api.com");
    const session = await hanko.validateSession();
    if (!session.valid) throw new Error("Invalid session");

    context.contextValue = { userId: session.userID };
  }
};

Step 3：配置Apollo Server集成

在Apollo Server初始化时注册认证插件：

import { ApolloServer } from "@apollo/server";
import { hankoAuthPlugin } from "./hankoAuthMiddleware";

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [hankoAuthPlugin]
});

通过上下文对象在Resolver中获取认证用户ID：

const resolvers = {
  Query: {
    profile: (_, __, { userId }) => {
      return getUserProfile(userId); // 使用Hanko验证后的用户ID
    }
  }
};

Step 4：前端Passkey认证流程

使用Hanko SDK发起Passkey认证，获取会话令牌后附加到GraphQL请求头：

// 获取会话令牌
const token = hanko.getSessionToken();

// Apollo Client配置
const client = new ApolloClient({
  uri: "/graphql",
  headers: { authorization: `Bearer ${token}` },
  cache: new InMemoryCache()
});

安全最佳实践

1. 会话管理：通过backend/session/session.go实现令牌轮换与超时控制
2. 跨域设置：在backend/config/config_server.go中配置CORS白名单
3. 审计日志：启用backend/audit_log/logger.go记录认证事件

完整代码示例

• 认证中间件源码：examples/express/middleware/hankoAuth.ts
• Apollo配置示例：examples/express/server.ts

通过这种方式，你的GraphQL服务将获得与GitHub、Google同源的Passkey认证能力，同时保持与现有Apollo生态的无缝集成。下一步可探索Hanko的多因素认证（MFA）与用户元数据管理功能，构建更完整的身份系统。

【免费下载链接】hanko Auth and user management for the passkey era 项目地址: https://gitcode.com/GitHub_Trending/ha/hanko