# @cimpress/simple-auth-wrapper 中文文档

规范地址：https://npmcn.com/package/%40cimpress/simple-auth-wrapper/

版本：11\.0\.1
npm 元数据更新时间：2026-08-07T07:30:06.191Z
中文译文更新时间：2026-11-09T16:11:53.171Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cimpress/simple-auth-wrapper
原文对照：https://npmcn.com/package/%40cimpress/simple-auth-wrapper/?lang=original
项目主页：https://gitlab.com/Cimpress-Technology/internal-open-source/component-library/mex-simple-auth-wrapper#readme
源码仓库：https://gitlab.com/Cimpress-Technology/internal-open-source/component-library/mex-simple-auth-wrapper

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

- 包体积（解压后）：182 kB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2017-12-05T18:08:32.838Z
- 最新版本发布：2026-08-07T07:30:05.949Z
- 近 30 天下载量：18165（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 4 个）

## 中文简介

一个简单的工具类来包装基本的 Auth0 功能

## 安装

```sh
npm install @cimpress/simple-auth-wrapper
```

也可以使用：`pnpm add @cimpress/simple-auth-wrapper`、`yarn add @cimpress/simple-auth-wrapper`、`bun add @cimpress/simple-auth-wrapper`

## README

# MEX 简单 Auth 包装器 v. 3

## 关于

这是Auth0的轻量级包装器,取消了写入并重写许多标准公用功能的需要.

看看这个 [更改日志](https://npmcn.com/CHANGELOG.md) 以查看最新变化.

## 使用

查看使用 Cimpress 客户端的中央登录执行此包装的示例 [单页应用程序样本](https://gitlab.com/Cimpress-Technology/orders/infrastructure/spa-s3-sample)

关于从嵌入式认证向集中式认证的迁移,见 [融入中央集权移徙](https://npmcn.com/package/%40cimpress/simple-auth-wrapper/docs/EMBEDDED_TO_CENTRALIZED_MIGRATION.md)

### 客户端配置

使用 [Cimpress 客户端配置](https://developer.cimpress.io/clients),创建单一页面App客户端配置. 此客户端ID 将用来配置包装 . 添加 `Allowed Callback URLs`, (中文(简体) ), `Allowed Logout URLs`,以及 `Allowed Web Origins` 与您的申请相对应。 如果您想要使用刷新符号, 请启用 `Enable Refresh Token Rotation` 并设定刷新符号寿命和刷新符号再使用间隔.

导入库并即时化一个新的认证帮助器,在域,受众,您的客户端ID中通过,使用RefreshTokens(可选)和Auth0的重定向Uri在认证后重定向到(在Auth0 v7中称为回调url). 你需要通过相对路线。 例如"/日志". 如果域和受众为空白,域将默认为 `cimpress.auth0.com0` 观众将默认为 `https://api.cimpress.io/`。您可能不需要手动设置这些 .

```
npm install @cimpress/simple-auth-wrapper
```

```javascript
import { centralizedAuth } from '@cimpress/simple-auth-wrapper';

const auth = new centralizedAuth(options); // see full list of supported options in centralizedauth.js
```

然后,以下内容可供您参考:

`ensureAuthentication(options)` 将手柄认证和登录结合起来。 这个单调可以用于页面负荷,它将尽所需要,确保用户得到认证. 此方法接受与 `login(options)` 方法.

`handleAuthentication()` 解析认证返回时url上的散列 。 此函数将自动将您重定向到通过登录的 URL 。 返回解析认证状态布尔的许诺 .

`login(options)` 用 Auth0 登录一个用户:首先检查SSO 会话是否存在,如果存在,则重新定向到集中登录页面。 返回解析认证状态布尔的许诺 。 以下列出您可使用此方法的选项 .

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `nextUri` | 字符串 | `"/"` | 如果用户无法通过 Single Sign On 获得新令牌, 则它们将被全部带走 [网络 Auth. 授权( )](https://auth0.com/docs/libraries/auth0js/v9#webauth-authorize-) 流出并会被带回这里 `nextUri` 路线. |
| `forceLogin` | 布尔 | `false` | 若为 `true`,用户的认证信息会被从本地Storage中移除,迫使他们经过整个 `webAuth.authorize()` 流量(而不是通过 Single Sign On 获得新的符号). |

`logout(nextUrl, logoutOfFederated)` 登录一个用户, 从本地存储中移除其符号和配置 。 将打开下一个URL中提供的 URL . 如果提供了可选的注册地址(Official Fosteria)并且该地址是真实的,则还将从身份提供者中登录用户。 注意: 这不是一个常用的用例, 大多数应用程序不需要提供这个参数 。 更多信息 [https://auth0.com/docs/logout (英语)](https://auth0.com/docs/logout)

#### 订阅事件

以下列出您可以订阅的不同事件 .

| 名称 | 说明 |
| --- | --- |
| `tokenExpired` | (注:具体版本) 此事件在用户的令牌过期时被触发. 如果用户在 localStorage 中的令牌在该事件订阅时已过期(即. `auth.on('tokenExpired', ...)`这件事情将立即发生. **如果你使用第九版和下面,你可以通过 `emitInitialTokenExpired` 10版及以上版本的构造器选项现在默认关闭.** 默认此事件会在实际到期前30秒发射出. 您可以通过 `expirationOffset` 构造器选项 。 也有可能向浏览器焦点开火. 这是由 `checkExpirationOnFocus` 构造器选项并存在,因为当用户的计算机入睡时,已过期的符号定时器可能不可靠. |

```javascript
import { centralizedAuth } from '@cimpress/simple-auth-wrapper';

const auth = new centralizedAuth(options);

auth.on('tokenExpired', () => {
  // This is invoked each time the current token in localStorage becomes expired.
  // This will also be immediately invoked if the token in localStorage is already expired. (configurable via emitInitialTokenExpired)
  console.log('The token in local storage is expired.');
});
```

### 代表团

代表团不再是核心包装器的一部分。 如果您有需要, 您可以加载并选择将其补丁到认证对象 :

```
import { centralizedAuth, Delegation } from '@cimpress/simple-auth-wrapper';

const auth = new centralizedAuth(options);

const delegationHandler = new Delegation(auth);

auth.buildDelegationHeader = delegationHandler.buildDelegationHeader;
```

这样你就能接触到:

`buildDelegationHeader(targetClientId)` 建立一些取回信头, 必要时获得代表团的标志 。 注:代表团被折旧,不建议使用。 我们建议使用访问符.

`getDelegationToken(targetClientId)` 为给定的目标客户端获得代表团的标志。 注:代表团被折旧,不建议使用。 我们建议使用访问符.

### 授权代码

这个 [授权代码](https://auth0.com/docs/api-auth/tutorials/authorization-code-grant) 可用于为用户取回更新令牌.

```javascript
import { AuthorizationCodeGrant } from '@cimpress/simple-auth-wrapper';
const authorizationCodeGrant = new AuthorizationCodeGrant(options);
```

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `clientID` | 字符串 | 无( 需要) | 授权代码 Grant 流程中使用的客户端ID |
| `redirectRoute` | 字符串 | "" "" (英语) | Auth0 路由将重定向到: `window.location.origin + redirectRoute` |
| `domain` | 字符串 | `cimpress.auth0.com` | Auth0 域名 |
| `audience` | 字符串 | `https://api.cimpress.io/` | 授权观众 |
| `scope` | 字符串 | `offline_access` | 您想要请求访问的范围 |

这样你就能接触到:

`login(options)` 启动授权代码Grant Flow,将用户重定向到集中锁页面.

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `nextUri` | 字符串 | `/` | 将用户带入流中并返回到此位置 `nextUri` 路线. |
| `authParams` | 对象 | {} | 可选择通过附加参数到 `/authorize` 由 auth0.js 创建 url. 对必须处理的案件有用 [向国内流离失所者发送额外数据](https://auth0.com/docs/connections/pass-parameters-to-idps#static-parameters)。 。 。 . |

`handleAuthentication(options)` 恢复授权代码授权流程。 应该在您的申请的底部,或 `redirectUri` 指定要继续流动。 返回承诺 `{ authorizationCode, redirectUri, nextUri }`

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `performRedirect` | 布尔 | 真实 | 指示包装是否应当重定向到指定的位置 `nextUri` |

### 授权代码流与代码交换的证明密钥( PKCE)

这个 [授权代码随 PKCE 流动](https://auth0.com/docs/flows/authorization-code-flow-with-proof-key-for-code-exchange-pkce) 可用于为用户取回更新令牌。 这个是用来配合 [会话 API](https://developer.cimpress.io/apis/auth/sessions-cimpress-io) 其中会话用于退出用户访问符.

#### 为什么从授权代码Grant改为授权代码CrantPKCE?

当公共客户端(如本地和单页应用程序)请求Access Tokens时,一些额外的安全顾虑(无法安全地存储客户端机密)被提出来,而授权代码流程本身并不能缓解.

为缓解这种情况,PKCE-增强授权代码流程引入了由调用应用程序所创建的一个可以由授权服务器验证的秘密;这个秘密被称为代码验证器. 此外,调用应用程序还创建了名为"代码挑战"的代码验证器的变换值并将此值通过HTTPS发送到获取授权代码. 这样一来,恶意攻击者只能截取授权代码,他们不能在没有代码验证器的情况下将其交换出一个令牌.

```javascript

import  {  AuthorizationCodeGrantPKCE  }  from  '@cimpress/simple-auth-wrapper';

const  authorizationCodeGrantPKCE  =  new  AuthorizationCodeGrantPKCE(options);

```

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `clientID` | 字符串 | 无( 需要) | 授权代码 Grant 流程中使用的客户端ID |
| `redirectRoute` | 字符串 | "" "" (英语) | Auth0 路由将重定向到: `window.location.origin + redirectRoute` |
| `domain` | 字符串 | `cimpress.auth0.com` | Auth0 域名 |
| `audience` | 字符串 | `https://api.cimpress.io/` | 授权观众 |
| `scope` | 字符串 | `offline_access` | 您想要请求访问的范围 |

这样你就能接触到:

`login(options)` 启动授权代码Grant Flow,将用户重定向到集中锁页面.

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `nextUri` | 字符串 | `/` | 将用户带入流中并返回到此位置 `nextUri` 路线. |

`handleAuthentication(options)` 恢复授权代码授权流程。 应该在您的申请的底部,或 `redirectUri` 指定要继续流动。 返回布尔值,表示用户是否成功完成了授权代码授权流程.

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `performRedirect` | 布尔 | 真实 | 指示包装是否应当重定向到指定的位置 `nextUri` |

`ensureAuthentication(options)` 将手柄认证和登录结合起来。 这个单调可以用于页面负荷,它将尽所需要,确保用户得到认证.

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `nextUri` | 字符串 | `/` | 将用户带入流中并返回到此位置 `nextUri` 路线. |
| `forceLogin` | 字符串 | `/` | 强制重定向用户到集中锁页面. |

`getProfile(sessionId)` 返回用户的配置信息,以交换会话Id。 我打给 [配置服务 API](https://developer.cimpress.io/apis/misc/profile-service--profile-cimpress-io-) 为了获取信息并避免多次拨打API,我们先将配置信息缓存到设定间隔(1小时)后再再次引用配置服务.

`logout(nextUri)` 关闭活动会话并清除本地存储。 登录用户出局后, 用户会被发送到“ nextUri” 指定的url 。 如果下一个Uri是相对路径, 用户将被发送到 `window.location.origin + nextUri`

`isLoggedIn(sessionId)` 返回当前会话是否活动.

#### 订阅事件

以下列出您可以订阅的不同事件 .

| 名称 | 说明 |
| --- | --- |
| `sessionExpired` | 当用户会话到期时会触发此事件 。 默认此事件会在实际到期前30秒发射出. 您可以通过 `sessionExpirationOffset` 构造器选项 。 也有可能向浏览器焦点开火. 这是由 `checkExpirationOnFocus` 构造器选项并存在,因为当用户的计算机入睡时会话已过期的定时器可能不可靠. |

```javascript
import { AuthorizationCodeGrantPKCE } from '@cimpress/simple-auth-wrapper';

const auth = new AuthorizationCodeGrantPKCE(options);

auth.on('sessionExpired', () => {
  console.log('The session has expired.');
});
```

### 分步认证

`initiateStepupLogin(nextUri, logoutOfFederated, ttl)` 此功能负责启动升级登录进程. 它需要以下参数:

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `nextUri` | 字符串 | `/` | 将用户带入流中并返回到此位置 `nextUri` 路线. |
| `logoutOfFederated` | 布尔 | `false` | 如果提供了可选的注册地址(Official Fosteria)并且该地址是真实的,则还将从身份提供者中登录用户。 注意: 这不是一个常用的用例, 大多数应用程序不需要提供这个参数 。 更多信息 [https://auth0.com/docs/logout (英语)](https://auth0.com/docs/logout) |
| `ttl` | 数目 | `undefined` | 是时候活着了,代表着 踏出标志的到期时间. |

`getStepUpExpiryTime()` 提供因认证的升级而导致的升级标志到期的时间.

## 常见问题

### @cimpress/simple-auth-wrapper 是什么？

一个简单的工具类来包装基本的 Auth0 功能

### 如何安装 @cimpress/simple-auth-wrapper？

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

### @cimpress/simple-auth-wrapper 支持 TypeScript 吗？

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

### @cimpress/simple-auth-wrapper 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cimpress/simple-auth-wrapper 可以商用吗？

@cimpress/simple-auth-wrapper 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cimpress/simple-auth-wrapper 的下载量有多少？

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

### @cimpress/simple-auth-wrapper 还在维护吗？

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