# @auth0/auth0-server-js 中文文档 规范地址：https://npmcn.com/package/%40auth0/auth0-server-js/ 版本：1\.17\.0 npm 元数据更新时间：2026-10-23T14:58:39.326Z 中文译文更新时间：2026-11-07T05:54:01.965Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40auth0/auth0-server-js 原文对照：https://npmcn.com/package/%40auth0/auth0-server-js/?lang=original 项目主页：https://github.com/auth0/auth0-auth-js#readme 源码仓库：https://github.com/auth0/auth0-auth-js ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.1 MB，9 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：2 个 - 首次发布：2025-03-28T13:12:29.537Z - 最新版本发布：2026-10-23T14:58:38.940Z - 近 30 天下载量：228857（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：24（近 12 个月 19 个） ## 中文简介 JavaScript 运行时间上的服务器- Side 应用程序认证 SDK ## 安装 ```sh npm install @auth0/auth0-server-js ``` 也可以使用：`pnpm add @auth0/auth0-server-js`、`yarn add @auth0/auth0-server-js`、`bun add @auth0/auth0-server-js` ## README 这个 `@auth0/auth0-server-js` 库允许在 JavaScript 运行时执行网络应用程序中的用户认证. 在您的应用程序中使用这个 SDK 可能不是微不足道的,因为它被设计为构建框架特定认证 SDK 的构件. ![Release](https://img.shields.io/npm/v/@auth0/auth0-server-js) ![Downloads](https://img.shields.io/npm/dw/@auth0/auth0-server-js) [![License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT) 📚 [文档](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-documentation) - 🚀 [开始](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-getting-started) - 💬 [反馈](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-feedback) ## 文档 - [实例](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-server-js/EXAMPLES.md) - 不同用法的例子. - [Docs 站点](https://auth0.com/docs) - 探索我们的文件网站 了解更多关于Auth0. ## 开始 - [1\. 安装SDK](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-1-install-the-sdk) - [2\. 创建 Auth0 SDK 客户端](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-2-create-the-auth0-sdk-client) - [3\. 仓库配置](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-3-configuring-the-store) - [无国籍存储](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-stateless-store) - [状态存储](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-stateful-store) - [4\. 在应用程序中添加登录(互动)](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-4-add-login-to-your-application-interactive) - [5\. 在应用程序中添加登录](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-5-add-logout-to-your-application) - [6\. 数据库连接(签名和更改密码)](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-6-database-connections-sign-up--change-password) - [7\. 匿名会议](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-7-anonymous-sessions) - [8\. 钥匙](https://npmcn.com/package/%40auth0/auth0-server-js/#readme-8-passkeys) ### 1\. 安装SDK ```shell npm i @auth0/auth0-server-js ``` 这个库需要Node.js 20 LTS和较新的LTS版本. ### 2\. 创建 Auth0 SDK 客户端 创建实例 `ServerClient`。此实例将被导入并用于我们需要访问认证方法的任何地方. ```ts import { ServerClient } from '@auth0/auth0-server-js'; const auth0 = new ServerClient({ domain: '', clientId: '', clientSecret: '', authorizationParams: { redirect_uri: '', }, }); ``` 这个 `AUTH0_DOMAIN`, (中文(简体) ), `AUTH0_CLIENT_ID`,以及 `AUTH0_CLIENT_SECRET` 可从 [Auth0 剪贴板](https://manage.auth0.com/) 一旦你创建了一个应用程序. **此申请必须是 `Regular Web Application`**。 。 。 . 这个 `AUTH0_REDIRECT_URI` 需要告诉 Auth0 在成功认证后返回的 URL, 例如 . `http://localhost:3000/auth/callback`您的应用程序需要处理此端点并呼叫 SDK `completeInteractiveLogin(url: string)` 以完成认证进程。 详情见下文. ### 3\. 仓库配置 这个 `auth0-server-js` 但是,SDK有一个内置的商店,用于交易和状态数据 **它必须提供 CookieHandler 执行** 这符合你的用法. 目标 `auth0-server-js` 即提供一个灵活的 API , 允许您使用您喜欢的任何存储机制, 但大多是设计与 cookie 和会话存储配合. SDK 方法接受可选 `storeOptions` 对象,可以用来传递存储方法的额外选项,如请求/响应对象,允许控制存储层中的 cookie. 就Web应用程序而言,这可归结为无国籍人或国家完整会话存储系统. #### 无国籍存储 在无国籍存储解决方案中,整个会话数据被存储在饼干中. 这是最简单的存储形式,但它有一些局限性,例如饼干的最大尺寸. 实施可能因选择的框架而异,这里是一个使用Fastify的例子: ```ts import { FastifyReply, FastifyRequest } from 'fastify'; import { CookieSerializeOptions } from '@fastify/cookie'; import { AbstractStateStore, AbstractTransactionStore, ServerClient, StateData, TransactionData } from '@auth0/auth0-server-js'; export interface StoreOptions { request: FastifyRequest; reply: FastifyReply; } export class FastifyCookieHandler implements CookieHandler { setCookie( name: string, value: string, options?: CookieSerializeOptions, storeOptions?: StoreOptions ): void { // Handle storeOptions being undefined if needed. storeOptions!.reply.setCookie(name, value, options || {}); } getCookie(name: string, storeOptions?: StoreOptions): string | undefined { // Handle storeOptions being undefined if needed. return storeOptions!.request.cookies?.[name]; } getCookies(storeOptions?: StoreOptions): Record { // Handle storeOptions being undefined if needed. return storeOptions!.request.cookies as Record; } deleteCookie(name: string, storeOptions?: StoreOptions): void { // Handle storeOptions being undefined if needed. storeOptions!.reply.clearCookie(name); } } const auth0 = new ServerClient({ transactionStore: new CookieTransactionStore({ secret: options.secret }, new FastifyCookieHandler()), stateStore: new StatelessStateStore({ secret: options.secret }, new FastifyCookieHandler()), }); ``` #### 状态存储 在状态存储中,会话数据被存储在服务器侧存储机制中,例如数据库. 这使得会话数据的规模有了更大的灵活性,但需要额外的基础设施来管理存储. 会话由存储在饼干中的独特标识符来识别,存储会读取,以从服务器侧存储取会话数据. 实施可能因选择的框架而异,这里是一个使用Fastify的例子: ```ts import type { FastifyReply, FastifyRequest } from "fastify"; import { CookieSerializeOptions } from '@fastify/cookie'; import { AbstractStateStore, LogoutTokenClaims, ServerClient, StateData, } from '@auth0/auth0-server-js'; export interface StoreOptions { request: FastifyRequest; reply: FastifyReply; } export class FastifyCookieHandler implements CookieHandler { setCookie( name: string, value: string, options?: CookieSerializeOptions, storeOptions?: StoreOptions, ): void { // Handle storeOptions being undefined if needed. storeOptions!.reply.setCookie(name, value, options || {}); } getCookie(name: string, storeOptions?: StoreOptions): string | undefined { // Handle storeOptions being undefined if needed. return storeOptions!.request.cookies?.[name]; } getCookies(storeOptions?: StoreOptions): Record { // Handle storeOptions being undefined if needed. return storeOptions!.request.cookies as Record; } deleteCookie(name: string, storeOptions?: StoreOptions): void { // Handle storeOptions being undefined if needed. storeOptions!.reply.clearCookie(name); } } const auth0 = new ServerClient({ transactionStore: new CookieTransactionStore({ secret: options.secret }, new FastifyCookieHandler()), stateStore: new StatefulStateStore({ secret: options.secret }, new FastifyCookieHandler()), }); ``` 请注意: `storeOptions` 在 SDK 的方法中是可选的,但在想要与框架交互设置 cookie 时需要. 这是如何通过 `storeOptions` 改为 `startInteractiveLogin()` 在快捷应用程序中: ```ts fastify.get('/auth/login', async (request, reply) => { const storeOptions = { request, reply }; const authorizationUrl = await auth0Client.startInteractiveLogin({}, storeOptions); reply.redirect(authorizationUrl.href); }); ``` 因为Web应用程序中的存储系统大多以饼干为基础 `storeOptions` 对象用来通过 `request` 财务报告和审定财务报表 `reply` (以快活为例) 对存储方法提出异议,允许控制存储层中的饼干. 预计它会传递给与SDK的每一次互动. ### 4\. 在应用程序中添加登录(互动) 在使用基于重定向的登录之前,确保 `authorizationParams.redirect_uri` 初始化 SDK 时配置 : ```ts const auth0 = new ServerClient({ // ... authorizationParams: { redirect_uri: '', }, // ... }); ``` 这个 `redirect_uri` 必须是绝对的 URL. 如果您需要计算每个请求的绝对重定向URI(例如,多域部署),则通过 `authorizationParams.redirect_uri` 改为 `startInteractiveLogin` 以覆盖已配置的默认值. > \[大 > 您需要注册 `AUTH0_REDIRECT_URI` 在您的 Auth0 应用程序中 **允许召回 URL** 通过 [Auth0 剪贴板](https://manage.auth0.com/)数字 : 要添加登录到任何应用程序, 请打电话 `startInteractiveLogin()`,然后将用户重定向到返回的 URL. 执行情况将因所使用的框架而异,但这里举出一个例子,说明在Fastify中,这种情况将是什么样子: ```ts fastify.get('/auth/login', async (request, reply) => { const authorizationUrl = await auth0Client.startInteractiveLogin({ // The redirect_uri can also be configured here. authorizationParams: { redirect_uri: '', }, }, { request, reply }); reply.redirect(authorizationUrl.href); }); ``` 一旦用户得到顺利的认证, Auth0 将会将用户重定向到提供的 `authorizationParams.redirect_uri` 在申请中需要处理. 执行情况将因所使用的框架而异,但需要的是: - 注册一个处理所配置的结束点 `authorizationParams.redirect_uri`。 。 。 . - 给SDK打电话 `completeInteractiveLogin(url)`,将其传递完整 URL,包括查询参数. 以下是在Fastify中这个样子的例子 `authorizationParams.redirect_uri` 配置为 `http://localhost:3000/auth/callback`数字 : ```ts fastify.get('/auth/callback', async (request, reply) => { await auth0Client.completeInteractiveLogin(new URL(request.url, options.appBaseUrl), { request, reply }); reply.redirect('/'); }); ``` ### 5\. 在应用程序中添加登录 为了从您的应用程序以及Auth0上登录用户,您可以调用 SDK 的 `logout()` 方法,并重定向用户返回返回的 URL. ```ts fastify.get('/auth/logout', async (request, reply) => { const logoutUrl = await auth0Client.logout({ returnTo: '' }, { request, reply }); reply.redirect(logoutUrl.href); }); ``` > \[大 > 您需要注册 `RETURN_TO` 在您的 Auth0 应用程序中 **允许登录 URL** 通过 [Auth0 剪贴板](https://manage.auth0.com/)数字 : ### 6\. 数据库连接(签名和更改密码) 这个 `ServerClient` 暴露一个 `database` 子客户端 `signUp` 财务报告和审定财务报表 `changePassword` 对Auth0的自助登记和密码重置请求 [数据库连接](https://auth0.com/docs/authenticate/database-connections)这些是: **纯通过** 操作到基础认证 API——它们确实 **没有** 读取或写入会话/状态存储,所以操作本身不需要存储选项. ```ts import { ServerClient, SignUpError, ChangePasswordError } from '@auth0/auth0-server-js'; // Register a new user try { const user = await auth0Client.database.signUp({ email: 'user@example.com', password: 'a-Str0ng-Password!', connection: 'Username-Password-Authentication', // Optional profile fields: username, givenName, familyName, name, nickname, picture, userMetadata }); console.log(user.id); // normalized identifier; may be undefined if the server omits one } catch (error) { if (error instanceof SignUpError) { console.error(error.code, error.message, error.cause); } } // Request a password-change email try { const message = await auth0Client.database.changePassword({ email: 'user@example.com', // or `username: 'jane'` for username-only connections connection: 'Username-Password-Authentication', // Optional: organization }); console.log(message); // plain-text confirmation from the server } catch (error) { if (error instanceof ChangePasswordError) { console.error(error.code, error.message); } } ``` > \[大 这叫大众 `/dbconnections/*` 端点,仅发送 `clientId` (从来不是客户的秘密). `changePassword` 决定: **纯文本** 确认字符串。 既不读又写会话/状态存储, 因此您可以在认证的请求上下文之外调用它们 。 域选择独立于会话状态:在静态模式下,构建器-配置 `domain` 在解析器(多租户)模式中 `domain` 解析器仍为每个调用——通过 `storeOptions` 这样它就可以选择预定租户. 关于全部选项和错误处理,见 [auth0-auth-js 数据库连接示例](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-auth-js/examples/database-connections.md) (基础数据库客户端相同)和可运行 [`examples/database-conns`](https://github.com/auth0/auth0-auth-js/tree/main/examples/database-conns) 样本. ### 7\. 匿名会议 这个 `ServerClient` 暴露一个 `anonymous` 给访客身份的子客户端, 以及您 API 的访问符, 在登录前。 配置一个 `anonymousStore` 打开它: ```ts import { StatelessAnonymousStore, ServerClient } from '@auth0/auth0-server-js'; const auth0 = new ServerClient({ // ... anonymousStore: new StatelessAnonymousStore({ secret: options.secret }, new FastifyCookieHandler()), }); // Give the visitor an anonymous identity and a token for your API. const tokenSet = await auth0.anonymous.createSession( { audience: '', metadata: { campaign: 'summer-sale' } }, { request, reply } ); // Later requests reuse the cached token, or mint a new one when it expired. const { accessToken } = await auth0.anonymous.getAccessToken({ audience: '' }, { request, reply }); ``` 匿名会话保存在自己的店里 所以 `getSession()` 财务报告和审定财务报表 `getUser()` 继续返回 `undefined` 直到访客真正登录. 打电话 `createSession()` 只有一次 `auth0.anonymous.getSession()` 显示访问者尚未开庭. `getAccessToken()` 服务缓存的令牌,仅在没有为请求的受众和范围提供缓存令牌时,或缓存已过期时,才能调用 Auth0 . 登入和登出都结束了你的匿名会话 每个登录方法在用户会话被写入后都会丢弃,以及 `auth0.logout()` 也洗干净了 读取 `auth0.anonymous.getSession()` **在此之前** 您需要匿名时完成登录 `sub` 将数据合并到用户账户中,或设置 `clearAnonymousSessionOnLogin: false` 保持会话,自己清理. > \[注\] 匿名会话在早期访问中,必须允许租户使用. > \[注\] `startInteractiveLogin()` 在登录时,通过会话传输票自动将活动匿名会话链接到用户。 对于不经过的登录方法 `/authorize` (单位:千美元)`passkey.complete()`, (中文(简体) ), `passkey.getToken()`, (中文(简体) ), `completePasswordless()`, (中文(简体) ), `loginBackchannel()`,类似地,链接是没有的——在您自己的应用程序中与匿名者合并 `sub`。 。 。 . 完整 API、 存储选项、 清除行为以及将匿名会话连接到登录时创建的用户的详细信息, 请参见 [EXAMPLES.md中的匿名会话部分](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-server-js/EXAMPLES.md#anonymous-sessions)。 。 。 . ### 8\. 钥匙 这个 `ServerClient` 暴露一个 `passkey` 子客户端可以注册并登录有密码的用户(WebAuthn). 一个密码流需要两个请求:一个启动它,另一个用浏览器的证书完成. 在两者之间,SDK保持流动,包括Auth0 `authSession`,在交易仓库中. ```ts // Start a signup, or a login with `auth0.passkey.startLogin()`, and return the result to the browser. const { authnParamsPublicKey, verificationRequired } = await auth0.passkey.startSignup( { email: 'user@example.com' }, { request, reply } ); // The browser passes `authnParamsPublicKey` to `navigator.credentials.create()` (`navigator.credentials.get()` // for a login) and sends the serialized credential back, together with the one-time codes Auth0 sent to the // identifiers in `verificationRequired`, if any. Exchange the credential for tokens and create the session: await auth0.passkey.complete({ credential, verification }, { request, reply }); ``` 下级 `passkey.register()`, (中文(简体) ), `passkey.challenge()` 财务报告和审定财务报表 `passkey.getToken()` 保持不流动状态并离开 `authSession` 您的应用程序。 只有在需要自己保持流动时才使用. 关于仪表板设置、标识符验证、错误处理以及两套方法的不同之处,请参见 [EXAMPLES.md中的密码部分](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-server-js/EXAMPLES.md#login-and-signup-using-passkeys)。 。 。 . ## 反馈 ### 捐款 我们赞赏反馈和对这次再投资的贡献! 在开始前,请阅读以下内容: - [Auth0的一般贡献准则](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md) - [Auth0 行为守则准则](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md) - [这个Repo的贡献指南](https://github.com/auth0/auth0-auth-js/blob/main/CONTRIBUTING.md) ### 提出问题 请提供反馈或报告错误 [提出我们的问题追踪器](https://github.com/auth0/auth0-auth-js/issues)。 。 。 . ## 脆弱性报告 请不要在公共 GitHub 问题跟踪器上报告安全漏洞 。 这个 [负责任的披露程序](https://auth0.com/responsible-disclosure-policy) 详细说明披露安全问题的程序. ## 什么是奥特? ![Auth0 Logo](https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png) Auth0是一个易于执行,可适应的认证和授权平台. 学习更多退房 [为什么是Auth0?](https://auth0.com/why-auth0) 这个项目根据麻省理工学院的许可证获得许可。 见 [自由主义](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-server-js/LICENSE) 需要更多信息的文件. ## 常见问题 ### @auth0/auth0-server-js 是什么？ JavaScript 运行时间上的服务器- Side 应用程序认证 SDK ### 如何安装 @auth0/auth0-server-js？ 在项目目录运行 npm install @auth0/auth0-server-js，或使用 pnpm add / yarn add / bun add。 ### @auth0/auth0-server-js 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @auth0/auth0-server-js 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @auth0/auth0-server-js 可以商用吗？ @auth0/auth0-server-js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @auth0/auth0-server-js 的下载量有多少？ 根据 npm 官方下载统计，@auth0/auth0-server-js 在 2026/10/07 – 2026/11/05 这 30 天内被下载 228,857 次，日均约 7,629 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @auth0/auth0-server-js 还在维护吗？ 最新版本 1\.17\.0 发布于 2026/10/23（15 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 19 个；首次发布于 2025/03/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。