# @defra/hapi-auth-oidc 中文文档

规范地址：https://npmcn.com/package/%40defra/hapi-auth-oidc/

版本：0\.6\.1
npm 元数据更新时间：2026-11-03T16:19:00.473Z
中文译文更新时间：2026-11-11T21:16:54.502Z
软件包许可：OGL-UK-3\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40defra/hapi-auth-oidc
原文对照：https://npmcn.com/package/%40defra/hapi-auth-oidc/?lang=original
项目主页：https://github.com/DEFRA/cdp-libraries/tree/main/packages/hapi-auth-oidc#readme
源码仓库：https://github.com/DEFRA/cdp-libraries

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

- 包体积（解压后）：66.4 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：8 个
- 首次发布：2026-02-11T09:44:36.304Z
- 最新版本发布：2026-11-03T16:19:00.069Z
- 近 30 天下载量：4593（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

一个轻量级的Node.js库,用于使用OIDC令牌和hopi服务器集成进行认证.

## 安装

```sh
npm install @defra/hapi-auth-oidc
```

也可以使用：`pnpm add @defra/hapi-auth-oidc`、`yarn add @defra/hapi-auth-oidc`、`bun add @defra/hapi-auth-oidc`

## README

# Hapi Auth OIDC (英语)

一个Hapi.js插件提供OpenID Connect(OIDC)认证,并有PKCE支持. 支持联邦的Cognitto活符,模拟活符测试,以及自动活符验证和刷新. 为服务器侧Hapi应用程序所设计.

## 特征

-   使用 PKCE 支持登录重定向到 OIDC 提供者
-   Auth callback 处理令牌验证
-   以可配置的早期刷新窗口自动刷新访问令牌
-   联邦通过Cognitto身份池提供象征性支持
-   请求装饰确保ValidToken、登录和处理回调
-   用于开发和测试环境的模拟OIDC供应商
-   窗体 post and question auth 回调支持
-   完整的可配置饼干选项

## 安装

```bash
npm install @defra/hapi-auth-oidc
```

## 使用量

### 从图书馆导入

所有公共功能、提供者和插件都从库入口导出 :

```js
import {
  HapiAuthOidcPlugin,
  CognitoTokenProvider,
  MockProvider,
  preLogin,
  postLogin,
  ensureValidToken
} from '@defra/hapi-auth-oidc'
```

或者,将整个库导入为命名空间 :

```js
import * as OIDC from '@defra/hapi-auth-oidc'
const plugin = OIDC.HapiAuthOidcPlugin
const tokenProvider = new OIDC.CognitoTokenProvider({...})
```

### 注册插件

```js
import Hapi from '@hapi/hapi'
import { AuthOidcPlugin } from './auth-oidc.js'

const server = Hapi.server({ port: 3000 })

await server.register(AuthOidcPlugin)
```

### 装饰请求

```js
server.route({
  method: 'GET',
  path: '/protected',
  handler: async (request, h) => {
    const { token, refreshed } = await request.ensureValidToken(
      request.auth.credentials
    )
    return { token }
  }
})
```

### 托肯刷新

独立使用 :

```js
import { ensureValidToken } from '@defra/hapi-auth-oidc'

const refreshedToken = await ensureValidToken(
  { accessToken, refreshToken },
  getOidcConfig,
  60000,
  oidcScope,
  logger
)
```

## 配置

### 插件选项

-   `oidc` - OIDC配置对象 :
    
    -   `clientId` - OIDC客户身份
    -   `discoveryUri` - OIDC 发现文件的 URL
    -   `authProvider` - 托肯供应商(`CognitoTokenProvider` 或者说 `MockProvider`(中文(简体) )
    -   `useHttp` - 布尔旗允许不安全的 HTTP 请求发现( 默认: 虚假)
    -   `loginCallbackUri` - OIDC 登录后重定向 URI
    -   `scope` - 以空间分隔的一串瞄准镜
    -   `externalBaseUrl` - 用于构建绝对回调URL的基础URL
    -   `defaultPostLoginUri` - 在登录后重新定向未另指明的URI(默认: `'/'`(中文(简体) )
    -   `earlyRefreshMs` - 令牌过期前毫秒提前刷新(默认:6000)
-   `cookieOptions` - 铁加密和安全的 Cookie 选项
    
    -   `password` - 用于铁加密的秘密(需要)
    -   `isSecure` - 只通过 HTTPS 发送 cookie( 默认: 真)
    -   `encoding` - 说吧 `'none' | 'base64' | 'base64json' | 'iron'` (默认 : `'iron'`(中文(简体) )
    -   `path` - Cookie 路径( 默认 ): `'/'`(中文(简体) )
    -   `isHttpOnly` - 客户端JS无法访问 Cookie(默认:真实)
    -   `isSameSite` - 说吧 `'Strict' | 'Lax' | 'None'` (默认 : `'Lax'`(中文(简体) )
    -   `ttl` - 以毫秒计的时间(可选)
    -   `domain` - Cookie域名( 可选)
    -   `ignoreErrors` - 忽略编码错误( 默认: 真)
    -   `clearInvalid` - 自动清除无效的 cookie( 默认: 真)

## 托肯供应商

### 认知托肯

-   AWS Cognito身份池的联邦标志提供商.
-   自动缓存令牌并在到期前刷新.
-   支持通过可选的早期刷新 `earlyRefreshMs`。 。 。 .

### 提供模拟器

-   用于开发/测试的简单模拟符号提供者.
-   返回一个已编码的硬码 .

## 示例使用

```js
import { config } from '../../../config/config.js'
import {
  CognitoTokenProvider,
  HapiAuthOidcPlugin,
  MockProvider
} from '@defra/hapi-auth-oidc'

const authProvider = config.get('isProduction')
  ? new CognitoTokenProvider({
      poolId: config.get('azureFederatedCredentials.identityPoolId'),
      logins: { 'cdp-portal-frontend-aad-access': 'cdp-portal-frontend' }
    })
  : new MockProvider({})

const oidcCookieConfig = config.get('hapi-auth-oidc.cookie')

export const AuthOidcPlugin = {
  plugin: HapiAuthOidcPlugin,
  options: {
    oidc: {
      clientId: config.get('azureClientId'),
      discoveryUri: config.get('oidcWellKnownConfigurationUrl'),
      authProvider,
      useHttp: config.get('isProduction'),
      loginCallbackUri: config.get('appBaseUrl') + '/auth/callback',
      scope: `api://${config.get('azureClientId')}/cdp.user openid profile email offline_access user.read`,
      externalBaseUrl: config.get('appBaseUrl')
    },
    cookieOptions: {
      isSecure: oidcCookieConfig.isSecure,
      password: oidcCookieConfig.password
    }
  }
}
```

## 常见问题

### @defra/hapi-auth-oidc 是什么？

一个轻量级的Node\.js库,用于使用OIDC令牌和hopi服务器集成进行认证\.

### 如何安装 @defra/hapi-auth-oidc？

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

### @defra/hapi-auth-oidc 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/defra\_\_hapi-auth-oidc 是否存在。

### @defra/hapi-auth-oidc 支持 ESM 还是 CommonJS？

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

### @defra/hapi-auth-oidc 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @defra/hapi-auth-oidc 可以商用吗？

@defra/hapi-auth-oidc 使用 OGL-UK-3\.0 许可。声明的许可为 OGL-UK-3\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @defra/hapi-auth-oidc 的下载量有多少？

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

### @defra/hapi-auth-oidc 还在维护吗？

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