@ crossmint/ 服务器- sdk
这个SDK提供了一套工具,在使用服务器侧渲染(SSR)的Crossmint驱动应用程序中认证用户. 它简化了处理认证令牌和管理用户会话的过程,从而更容易将认证整合到您 Next.js 应用程序中.
安装
要安装 SDK, 您可以使用 npm 或 线 :
npm install @crossmint/server-sdk
API 密钥和范围
使用服务器侧 API 密钥( S)sk_...) 从克罗斯明特控制台. 它需要什么样的范围取决于你所说的方法:
| 方法 | 范围 |
|---|---|
getSession, (中文(简体) ), handleCustomRefresh, (中文(简体) ), logout | 无 |
getUser | users.read |
getSession 使用 Crossmint 的公用密钥验证 JWT,并通过不检查瞄准镜的端点刷新会话. getUser 读取用户的配置文件,所以关键需要 users.read没有它, getUser 丢出一个 CrossmintAuthenticationError 与 status 403号.
使用量
要在您的应用程序中使用 SDK, 请遵循这些步骤 :
- 导入 SDK 到您的工程中 :
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";
const crossmint = createCrossmint({
apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
});
const crossmintAuth = CrossmintAuth.from(crossmint);
- 使用 SDK 认证用户 :
通过请求对象,SDK读取会话 cookie for you. 这和Node.js有关
(单位:千美元)IncomingMessage)并获取 API(Request请求,包括Next.js中间软件和路由处理器:
const { jwt, userId } = await crossmintAuth.getSession(request);
客户端 SDK 将会话存储在 cookie 中, 范围为您的项目 : crossmint-jwt-<projectId> 财务报告和审定财务报表
crossmint-refresh-token-<projectId>,项目ID来自您的 API 密钥. getSession(request) 读取
这些名字,并读 遗产 crossmint-jwt 财务报告和审定财务报表 crossmint-refresh-token 名称仅当没有显示范围饼干时.
A Next.js 服务器组件中没有请求对象 。 按名字读取饼干 getAuthCookieNames(projectId)
返回并传递到 getSession。项目ID来自您的 API 密钥 :
import { cookies } from "next/headers";
import { getAuthCookieNames, validateAPIKey } from "@crossmint/server-sdk";
const apiKeyResult = validateAPIKey(process.env.SERVER_CROSSMINT_API_KEY ?? "");
if (!apiKeyResult.isValid) {
throw new Error(apiKeyResult.message);
}
const cookieStore = await cookies();
const cookieNames = getAuthCookieNames(apiKeyResult.projectId);
const refreshToken = cookieStore.get(cookieNames.refreshToken)?.value;
if (refreshToken != null) {
const { jwt, userId } = await crossmintAuth.getSession({
jwt: cookieStore.get(cookieNames.jwt)?.value,
refreshToken,
});
}
- 获取用户配置文件
getSession 返回用户的ID。 要获得他们的电子邮件,电话号码或链接到的X账户,将ID传递到 getUser它需要 users.read 选项
import { CrossmintAuthenticationError } from "@crossmint/server-sdk";
try {
const user = await crossmintAuth.getUser(userId); // { id, email?, phoneNumber?, twitter? }
} catch (error) {
if (error instanceof CrossmintAuthenticationError) {
// error.status is 403 when the API key lacks users.read, 404 when the user has not signed in to this project
console.error(error.status, error.message);
}
throw error;
}
- 将认证材料存储在 cookie 中
如果您正在使用一个可访问响应对象的框架,可以通过将响应对象传递到 getSession 方法。 SDK 写有工程范围饼干名称( 日志也过期了未扫描的遗产 ) :
const { jwt, userId } = await crossmintAuth.getSession(request, response);
- 注销
await crossmintAuth.logout(request);
警卫
SDK允许您设定 httpOnly, (中文(简体) ), secure, (中文(简体) ), domain 财务报告和审定财务报表 sameSite 用于饼干的选项。 这样可以控制饼干的存储和传输方式. 将它与自定义的刷新路由组合在一起,您可以将认证材料存储在HttpOnly Cookie中,这些认证材料被绑定在提供路由的域上.
在创建自定义刷新路由时配置 CrossmintAuth 这样做 :
const crossmintAuth = CrossmintAuth.from(crossmint, {
cookieOptions: {
httpOnly: true,
sameSite: "Strict",
secure: true,
domain: ".example.com",
},
});
httpOnly 仅适用于刷新符号。 会话符号不会是 Http Only ,因为它在客户端中用于API 调用 .
设置自定义刷新路由
要设置自定义刷新路由, 您可以使用 handleCustomRefresh 方法。 这种方法会刷新符号并还原新的认证材料. 这样,认证材料可以被存储在被绑定在所提供路由域的饼干中.
在使用获取 API 的环境中 Request 财务报告和审定财务报表 Response 对象, handleCustomRefresh 返回响应对象 :
return await crossmintAuth.handleCustomRefresh(request);
在使用Node.js API的环境中,您还需要提供响应对象并结束响应:
await crossmintAuth.handleCustomRefresh(req, res);
res.end();
使用自定义刷新路由
您也可以提供自定义刷新路由 :
const crossmintAuth = CrossmintAuth.from(crossmint, {
refreshRoute: `${process.env.APP_URL || "http://localhost:3000"}/api/refresh`,
});
SDK将使用提供的路由,而不是Crossmint的刷新终点. 在服务器上, 将它配置为静态的、可信任的绝对 URL; 永远不要从收到的请求或请求中得出它 Host 头曰. 在生产中使用HTTPS. 服务器 SDK 验证刷新 JWT 的签名,过期,以及针对 Crossmint 的 JWKS 的项目受众,并从已验证的用户ID取出 sub 索赔.
设置自定义登录路径
使用时 HttpOnly cookie,登录不能发生客户端,因为它不能访问cookie. 可以设置自定义的登录路由来处理登录过程.
在使用获取 API 的环境中, logout 返回响应对象 :
return await crossmintAuth.logout(request);
在使用Node.js API的环境中,您还需要提供响应对象并结束响应:
await crossmintAuth.logout(req, res);
res.end();