# @betterportal/auth-workos 中文文档

规范地址：https://npmcn.com/package/%40betterportal/auth-workos/

版本：11\.0\.9
npm 元数据更新时间：2026-11-07T08:30:20.676Z
中文译文更新时间：2026-11-09T20:34:10.045Z
软件包许可：\(AGPL-3\.0-only OR Commercial\)

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40betterportal/auth-workos
原文对照：https://npmcn.com/package/%40betterportal/auth-workos/?lang=original
项目主页：https://github.com/BetterCorp/BetterPortal#readme
源码仓库：https://github.com/BetterCorp/BetterPortal

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：298 kB，91 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-07-05T16:23:45.336Z
- 最新版本发布：2026-11-07T08:30:20.331Z
- 近 30 天下载量：1744（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：118（近 12 个月 118 个）

## 中文简介

为 Node.js 提供的更好的门户工作OS认证服务

## 安装

```sh
npm install @betterportal/auth-workos
```

也可以使用：`pnpm add @betterportal/auth-workos`、`yarn add @betterportal/auth-workos`、`bun add @betterportal/auth-workos`

## README

# 更好的门户工作OS Auth 服务

WorkOS AuthKit提供商为"更好的门户"服务. 该服务将用户重定向到WorkOS,与WorkOS节点SDK交换回调码服务器侧面,发行了BetterPortal令牌,并刷新了WorkOS刷新令牌的BP令牌.

每个应用程序服务配置需要:

-   `clientId`
-   `apiKey`

可选配置 :

-   `provider` 默认为 `authkit`
-   `connectionId`, (中文(简体) ), `organizationId`, (中文(简体) ), `domainHint`
-   `scopes`
-   `roleClaimPath` 默认为 `roles`
-   服务配置 `workosStatePath` 默认为 `./workos-state.json`; 将其设置为如 `/data/workos-state.json` 生产
-   服务配置 `syncIntervalSeconds` 默认为 `21600` 并每6小时重复一次暂停许可/角色同步

书记官处 `betterportal`。 。 。 .

OAuth 登录状态被存储为 SHA-256 指定待处理文件 `workosStatePath` 在交换回调代码之前解剖掉。 保留此目录可写入 。 复制品应当共享相同的持续路径,这样回调可以在任何复制品上完成;一个没有发行状态的复制品拒绝回调. 过期的待处理文件在以后的登录开始期间被清理,每份复制件的待处理状态限制为一万.

登记后和登记后目的地为应用所有 `app.auth.redirects` 查看在 tenants & Apps 中配置的引用,而不是提供者添加字段.

角色同步将BP作为真理的许可来源. WorkOS许可弹片是服务拥有的短键, `bp_<shortId>_<read|create|update|delete>`,将完整的房客/服务/景色绘图储存在 `workosStatePath`. 角色由 WorkOS 角色 satters 的每个应用程序镜像到 BP 应用角色.

通过标准显示角色同步端点 `auth.roles.sync.view`, (中文(简体) ), `auth.permissions.sync`,以及 `auth.roles.sync` 操作角色。 消费者发现他们公布的路径,而不是依赖于WorkOS路由名称.

服务使用 `@workos-inc/node` 11 在节点24上(SDK需要节点22.11+). 它的AuthKit,用户/角色/许可和SSO集成保留了现有的合同;这一服务没有使用SDK的Pipes API在11版中被修改.

更新依赖性后验证 SDK 集成 :

```bash
npm run build -w @betterportal/auth-workos
npm run test -w @betterportal/auth-workos
```

## 常见问题

### @betterportal/auth-workos 是什么？

为 Node\.js 提供的更好的门户工作OS认证服务

### 如何安装 @betterportal/auth-workos？

在项目目录运行 npm install @betterportal/auth-workos，或使用 pnpm add / yarn add / bun add。

### @betterportal/auth-workos 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @betterportal/auth-workos 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @betterportal/auth-workos 可以商用吗？

@betterportal/auth-workos 使用 \(AGPL-3\.0-only OR Commercial\) 许可。可在 AGPL-3\.0、Commercial 中任选其一遵守。以上为概括，不构成法律意见，请以许可原文为准。

### @betterportal/auth-workos 的下载量有多少？

根据 npm 官方下载统计，@betterportal/auth-workos 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,744 次，日均约 58 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @betterportal/auth-workos 还在维护吗？

最新版本 11\.0\.9 发布于 2026/11/07（2 天前）；至今共发布 118 个版本，其中过去 12 个月发布了 118 个；首次发布于 2026/07/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。