# @axa-fr/oidc-client-service-worker 中文文档

规范地址：https://npmcn.com/package/%40axa-fr/oidc-client-service-worker/

版本：7\.29\.8
npm 元数据更新时间：2026-10-15T05:31:40.051Z
中文译文更新时间：2026-11-07T11:08:56.853Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40axa-fr/oidc-client-service-worker
原文对照：https://npmcn.com/package/%40axa-fr/oidc-client-service-worker/?lang=original
项目主页：https://github.com/AxaFrance/oidc-client#readme
源码仓库：https://github.com/AxaFrance/oidc-client

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

- 包体积（解压后）：278 kB，103 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-07-22T17:12:26.259Z
- 最新版本发布：2026-10-15T05:31:39.222Z
- 近 30 天下载量：181279（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：261（近 12 个月 37 个）

## 中文简介

OpenID 连接和 OAuth 认证服务工作者

## 安装

```sh
npm install @axa-fr/oidc-client-service-worker
```

也可以使用：`pnpm add @axa-fr/oidc-client-service-worker`、`yarn add @axa-fr/oidc-client-service-worker`、`bun add @axa-fr/oidc-client-service-worker`

## README

# @axa-fr/oidc-客户端-服务-工作

服务员 [`@axa-fr/oidc-client`](https://npmcn.com/package/%40axa-fr/oidc-client/README.md) 财务报告和审定财务报表 [`@axa-fr/react-oidc`](https://npmcn.com/package/%40axa-fr/react-oidc/README.md)它截取了OIDC的信号响应, 默认情况下在工人记忆中保留访问和刷新令牌,并添加访问 符合您信任域配置的请求的符号.

大多数应用程序应该安装一个客户端软件包,而不是使用此软件包 直接包。 客户负责工人登记和沟通.

-   [如何运作](https://npmcn.com/package/%40axa-fr/oidc-client-service-worker/#readme-how-it-works)
-   [开始](https://npmcn.com/package/%40axa-fr/oidc-client-service-worker/#readme-getting-started)
-   [信任域](https://npmcn.com/package/%40axa-fr/oidc-client-service-worker/#readme-trusted-domains)
-   [部署和解决问题](https://npmcn.com/package/%40axa-fr/oidc-client-service-worker/#readme-deployment-and-troubleshooting)
-   [议定书参考](https://npmcn.com/package/%40axa-fr/oidc-client-service-worker/#readme-protocol-reference)

## 如何运作

```mermaid
flowchart LR
    App["Browser application"] --> Client["OIDC client or React bindings"]
    Client <-->|"Messages and token placeholders"| Worker["OIDC service worker"]
    Worker <-->|"Token requests and responses"| Provider["OIDC provider"]
    App -->|"API request"| Worker
    Worker -->|"Access token on trusted requests"| API["Trusted API"]
    Config["OidcTrustedDomains.js"] --> Worker
```

应用程序可以使用符名元数据而不接收真实访问或 刷新符号 . `showAccessToken: true` 明确暴露访问符 应用程序 JavaScript 同时将刷新符号保存在工人中.

> \[大 托肯隔离并不妨碍XSS或CSRF. 仍然可以输入代码 申请中经认证的请求。 使用限制性内容安全 政策,防止脚本注射, 并强制授权您的 API .

## 开始

1.  安装和配置 [香草客户端](https://npmcn.com/package/%40axa-fr/oidc-client/README.md#getting-started) 或者说 [反应绑定](https://npmcn.com/package/%40axa-fr/react-oidc/README.md#getting-started)。 。 。 .
    
2.  创建您的应用程序的公共资产目录, 如果它不存在, 那么 运行您安装的客户端的复制命令 :
    
    ```sh
    # Vanilla client
    node ./node_modules/@axa-fr/oidc-client/bin/copy-service-worker-files.mjs public
    
    # React — use this instead
    node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public
    ```
    
    替换 `public` 如果您的框架服务于另一个目录的静态文件. 命令覆盖 `OidcServiceWorker.js` 但保留一个已存在的 `OidcTrustedDomains.js`。 。 。 .
    
3.  替换样本条目为 `public/OidcTrustedDomains.js` 与您的提供者 和API URL,如下所述.
    
4.  将这些字段添加到您的 OIDC 客户端配置 :
    
    ```js
    const configuration = {
      ...oidcConfiguration,
      service_worker_relative_url: '/OidcServiceWorker.js',
      service_worker_only: true,
    };
    ```
    
    与 `service_worker_only: true`,认证需要工人的支持. 准备吧 `false` 只有您接受返回到 JavaScript 可访问浏览器时 当工人无法工作时,储存.
    
5.  在您的应用程序中添加相应的复制命令 `postinstall` 剧本. 例如,对反应:
    
    ```json
    {
      "scripts": {
        "postinstall": "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public"
      }
    }
    ```
    
    将这与现有的安装步骤合并,而不是取而代之. 调用复制的工人 每一个客户端升级.
    

## 信任域

保持提供者端点和 API 目的地分离 :

```js
const trustedDomains = {
  default: {
    oidcDomains: [/^https:\/\/identity\.example\.com(?:\/|$)/],
    accessTokenDomains: [/^https:\/\/api\.example\.com(?:\/|$)/],
  },
};
```

`default` 是默认客户端配置名称。 添加匹配条目 每名客户端或 `OidcProvider`这些规则使用正则表达匹配, 包括当规则是弦。 锁定模式, 逃避主机名点, 以及 包含一个主机或路径边界,以使外观的 URL 不匹配. 包含 OIDC 实际终点来源 如果您的提供者服务于来自不同的发现、 标志或用户信息 师曰. 只允许接收此配置的 API 目的地 访问符; 不将演示许可列表复制到生产中 .

使用 `oidcClient.fetchWithTokens(fetch)` 在香草应用中或 `useOidcFetch()` 在反应。 特别是, `allowMultiTabLogin: true` **需求** oIDC 获取 包装器:其占位符识别出工人必须注入的符号的标签. 一个平地 `fetch` 无法提供这些信息.

见 [客户端的服务-工作指南](https://npmcn.com/package/%40axa-fr/oidc-client/README.md#service-worker-support) 附加选项,包括 DPoP、访问的可见度和请求 处理.

## 部署和解决问题

-   在 HTTPS 上同时服务您的应用程序来源的 JavaScript 文件 (当地东道主支持发展).
-   工人必须控制使用它的页面。 在源头为它服务 是最简单的设置;在子路径下托管时要说明工人的范围.
-   将文件作为 JavaScript 服务,而不是用于 SPA 路由的 HTML 倒置 . 如果 注册失败 .
-   保持工人版本与客户端对齐. 编辑可信域文件, 未生成 `OidcServiceWorker.js`。 。 。 .
-   如果 API 请求返回 401, 请检查活动的配置名称, 匹配 `accessTokenDomains` 条目,以及您是否正在使用 OIDC 获取包装. API还必须接受该标志的发行者,受众,和范围.
-   在改变工人资产后,检查哪个工人版本控制了您的页面; 已经打开的标签可能仍由年长的工人控制.

这个 [财务问题](https://npmcn.com/package/FAQ.md) 涵盖更广泛的安全和一体化问题.

## 议定书参考

大多数应用程序不需要直接发送工人信息. 习惯 一体化, [`PROTOCOL.md`](https://npmcn.com/package/%40axa-fr/oidc-client-service-worker/PROTOCOL.md) 描述已版本的消息 信封、有效载荷、代号占位符、存储密钥和兼容性保证.

协议常数和类型从 `@axa-fr/oidc-client-service-worker/protocol` 并再由 `@axa-fr/oidc-client`。 。 。 .

用于源开发, 使用根 [贡献命令](https://npmcn.com/package/README.md#contribute) 和已死的锁文件。 保持本套件的Vitest和覆盖版本对齐.

[回到项目概况](https://npmcn.com/package/README.md)

## 常见问题

### @axa-fr/oidc-client-service-worker 是什么？

OpenID 连接和 OAuth 认证服务工作者

### 如何安装 @axa-fr/oidc-client-service-worker？

在项目目录运行 npm install @axa-fr/oidc-client-service-worker，或使用 pnpm add / yarn add / bun add。

### @axa-fr/oidc-client-service-worker 支持 TypeScript 吗？

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

### @axa-fr/oidc-client-service-worker 支持 ESM 还是 CommonJS？

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

### @axa-fr/oidc-client-service-worker 可以商用吗？

@axa-fr/oidc-client-service-worker 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @axa-fr/oidc-client-service-worker 的下载量有多少？

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

### @axa-fr/oidc-client-service-worker 还在维护吗？

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