# @digicatapult/tsoa-oauth-express 中文文档

规范地址：https://npmcn.com/package/%40digicatapult/tsoa-oauth-express/

版本：2\.0\.88
npm 元数据更新时间：2026-10-31T21:32:25.532Z
中文译文更新时间：2026-11-01T00:37:23.622Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40digicatapult/tsoa-oauth-express
原文对照：https://npmcn.com/package/%40digicatapult/tsoa-oauth-express/?lang=original
项目主页：https://github.com/digicatapult/tsoa-oauth-express#readme
源码仓库：https://github.com/digicatapult/tsoa-oauth-express

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

- 包体积（解压后）：38.4 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：express ^5\.3\.0
- 首次发布：2024-05-13T16:37:40.075Z
- 最新版本发布：2026-10-31T21:32:25.203Z
- 已发布版本数：214（近 12 个月 29 个）

## 中文简介

使用OAuth2 JWT令牌的TSOA身份验证处理程序

## 安装

```sh
npm install @digicatapult/tsoa-oauth-express
```

也可以使用：`pnpm add @digicatapult/tsoa-oauth-express`、`yarn add @digicatapult/tsoa-oauth-express`、`bun add @digicatapult/tsoa-oauth-express`

## README

# tsoa-oauth-express

此库可以轻松实现OAuth2身份验证 [tsoa](https://tsoa-community.github.io/docs/) 在 [表达](http://expressjs.com/)． 要使用此库，首先将其添加为 `npm` 依赖于现有的 `tsoa` 应用程序。

```sh
npm i @digicatapult/tsoa-oauth-express
```

您的身份验证文件（请参阅tsoa关于身份验证设置的文档） [在这里](https://tsoa-community.github.io/docs/authentication.html))将需要包含如下内容：

```ts
import type express from 'express'
import type * as jwt from 'jsonwebtoken'

import mkExpressAuthentication, { AuthOptions } from '@digicatapult/tsoa-oauth-express'

// module options
const options: AuthOptions = {
  ...
}

export const expressAuthentication = mkExpressAuthentication(options)
```

的地方 `options` Value是具有以下类型和属性的对象：

```ts
interface AuthOptions {
  securityName?: string
  verifyOptions?: jwt.VerifyOptions & { complete?: false }
  jwksUri: () => Promise<string>
  getAccessToken: (req: express.Request) => Promise<string | undefined>
  getScopesFromToken: (decoded: string | jwt.JwtPayload) => Promise<string[]>
  tryRefreshTokens: (req: express.Request) => Promise<boolean>
}
```

| 财产 | 要求 | 描述 |
| --- | --- | --- |
| jwksUri | `true` | 解析为 `uri` 对于您的身份提供者 `jwks` 配置 |
| getAccessToken | `true` | 类解析JWT `Request`． 例如，这可能来自an `authorization` 页眉或 `cookie` 基于需求 |
| getScopesFromToken | `true` | 解析为所提供令牌支持的OAuth范围数组 |
| securityName | `false` | `OpenAPI` 要保护的安全方案名称 |
| verifyOptions | `false` | `jsonwebtoken` 验证选项。看到 [jsonwebtoken文档](https://www.npmjs.com/package/jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback) 有关详细信息, |
| tryRefreshTokens | `false` | 执行令牌刷新。解析为 `true` 否则刷新成功 `false`． 默认情况下，它总是解析为 `false` |

## 例子

包存储库中包含一个使用OAuth客户机-凭据流对机器对机器（m2m） API进行身份验证的示例实现。它由两个部分组成，一个是预配置的 `Keycloak` 可以被实例化的实例 `docker compose` 作为我们的身份提供者和下面的示例应用程序 [/。](https://npmcn.com/package/%40digicatapult/tsoa-oauth-express/example) 它实现了 `tsoa` 服务器。欲了解更多信息，请参阅 [Tsoa认证文档](https://tsoa-community.github.io/docs/authentication.html) 我们的身份验证处理程序示例在 [/ / authentication.ts示例](https://npmcn.com/package/%40digicatapult/tsoa-oauth-express/example/authentication.ts).

首先打开 `Keycloak` 实例，从存储库根目录执行：

```sh
docker compose up -d
```

这将自动预配置一个名为 `example` 客户端保密 `example`． 然后我们可以通过执行以下命令来获取一个m2m令牌：

```sh
curl --request POST \
  --url 'http://localhost:3080/realms/example/protocol/openid-connect/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=example \
  --data client_secret=example
```

属性中返回一个JSON对象，该对象带有JWT验证令牌 `access_token` 属性的形式为 `eyJhbGci...r8TIOfRQ`.

然后可以使用以下命令运行示例服务器：

```sh
npm run example
```

该服务器监听端口3000并公开两条路由 `/authenticated` 和 `/unauthenticated` 其中只有第一条路由需要认证令牌。例如，我们可以调用

```sh
curl http://localhost:3000/unauthenticated
```

哪个应该返回类似的东西

```json
{ "message": "This route is unauthenticated", "authenticated": false }
```

但是调用经过验证的路由(`curl http://localhost:3000/authenticated`)将返回一个错误

```json
{ "message": "unauthenticated" }
```

提供JWT认证令牌作为认证头的一部分：

```sh
curl http://localhost:3000/authenticated --header 'authorization: bearer eyJhbGci...r8TIOfRQ'
```

导致调用成功：

```json
{ "message": "This route is authenticated", "authenticated": true }
```

## 常见问题

### @digicatapult/tsoa-oauth-express 是什么？

使用OAuth2 JWT令牌的TSOA身份验证处理程序

### 如何安装 @digicatapult/tsoa-oauth-express？

在项目目录运行 npm install @digicatapult/tsoa-oauth-express，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：express（^5\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @digicatapult/tsoa-oauth-express 支持 TypeScript 吗？

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

### @digicatapult/tsoa-oauth-express 支持 ESM 还是 CommonJS？

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

### @digicatapult/tsoa-oauth-express 可以商用吗？

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

### @digicatapult/tsoa-oauth-express 还在维护吗？

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