# @confighub/react-auth 中文文档

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

版本：0\.10\.12
npm 元数据更新时间：2026-11-10T16:03:56.875Z
中文译文更新时间：2026-11-10T15:22:38.551Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40confighub/react-auth
原文对照：https://npmcn.com/package/%40confighub/react-auth/?lang=original
项目主页：https://github.com/confighub/js-sdk/tree/main/packages/react-auth#readme
源码仓库：https://github.com/confighub/js-sdk

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

- 包体积（解压后）：154 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-07-07T08:43:06.034Z
- 最新版本发布：2026-11-10T16:03:56.470Z
- 近 30 天下载量：8396（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：109（近 12 个月 109 个）

## 中文简介

ConfigHub 浏览器应用软件(OIDC PKCE + RFC 8693 令牌交换)的反向认证提供者和钩子

## 安装

```sh
npm install @confighub/react-auth
```

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

## README

# @ conquighub/ react-auth (英语)

对浏览器应用进行认证的响应提供者和钩子 [配置图](https://confighub.com/) API (英语). 运行浏览器- 直接流端到结束 —— 运行时间发现, OIDC 授权代码 + PKCE 对抗已发现的 IDP, 然后 RFC 8693 硬币交换 薄荷 ConfigHub 硬币——手放回打字机 [`@confighub/api`](https://www.npmjs.com/package/@confighub/api) 客户端预线 与标志.

```tsx
import { ConfigHubAuthProvider, useAuth, useConfigHub } from '@confighub/react-auth';

<ConfigHubAuthProvider baseUrl="https://hub.confighub.com" clientId={CLIENT_ID}>
  <App />
</ConfigHubAuthProvider>;

function App() {
  const { status, user, login, logout } = useAuth();
  const api = useConfigHub(); // typed client, token already attached
  // await api.GET('/me'); await api.GET('/space/{space_id}/unit', { params: { path: { space_id } } });

  if (status === 'loading') return <p>…</p>;
  if (status !== 'authenticated') return <button onClick={login}>Log in</button>;
  return <button onClick={logout}>Sign out {user!.organizationId}</button>;
}
```

## 配置

-   `baseUrl` 例如,ConfigHub案. `https://hub.confighub.com`。 。 。 .
-   `clientId` 这个应用程序的注册 OAuth 客户端 ID,来自 `cub oauthclient create <name> --redirect-uri <origin>/`。 。 。 .
-   `callbackPath` (默认) `/`)——IDP重定向回 `{origin}{callbackPath}`, (中文(简体) ), 它就是重定向URI以注册。 它故意固定的:用户的页面 从PKCE旅行开始 `state` 然后在返回时恢复,故登录 从 `/space/x?tab=units` 回到那里,没有记录每条路.
-   `persist` (默认) `'session'`)——本届会议保留在 `sessionStorage`,所以一个 重新装入或内塔布导航不通过 IDP. Tab-scoped 进行回转 当标签关闭时,当符号过期时会掉入. `'none'` 放在记忆里 仅此而已,每一页的负载都会开始未经认证.
-   `onUnauthorized` (默认) `'login'`)——一个被否决的标志意味着什么. `'login'` 尝试 沉默的再校正; `'logout'` 只是放弃了会话。 应用时 `getAccessToken` 当一个数据客户端报告一个401时 结束 `handleUnauthorized` (下关.

IDP发行器和OIDC端点是从 `{baseUrl}/api/info`,所以请 同一构件运行于任何 ConfigHub 实例( 捆绑的 Ceycloak for Cloud, a) 企业的IdP).

## `useAuth()`

```ts
const { status, user, error, login, logout, reauthenticate, signInWithTicket, getToken } = useAuth();
```

-   `login(options?)` ——改道到IDP. `returnTo` 选择着陆路径 (默认:为当前之一). `organization` 是 Keycloak 组织别名, 已发送 作为 `organization:<alias>` 范围, 因此不提示多用户 。 左边 ,则使用此浏览器中上次成功登录的别名(记住) 每个客户 `localStorage`;一个简短的公用名称,而不是证书),所以一个新的 选项卡或在同一组织静默地登录后登录. `null` keycloak 提示。 两者都是应用程序的开关 组织:通过IdP新登录,即会员所在地 决定. `prompt: 'none' | 'login' | 'create'` 通过; `'create'` 打开 iDP的注册表,所以一个注册链接是 `login({ prompt: 'create' })`。 。 。 .
-   `logout(options?)` ——在本分页中忘记会话. `endSession: true` 也结束 (由RP启动的登录程序) `id_token_hint`),着陆 `postLogoutRedirectUri` (默认: 回调 URI),必须注册 为客户。 没有它,下一个登录 骑SSO饼干安静地。 虽然 页面导航到 IDP, 状态保留 `loading`因此,一个程序登录 自动打开 `unauthenticated` 不启动一个与日志相匹配的登录.
-   `reauthenticate()` ——标志停止工作:a `prompt=none` 来回旅行 会议已经安排好了。 状态为 `loading` 与此同时,没有 `unauthenticated`自动登录的应用程序 `unauthenticated` 不是种族 这个 如果 IdP 会话也走了, 页面会回来 `unauthenticated`时 没有身份提供商 没有什么可问的 状态去 直达 `unauthenticated`。 。 。 .
-   `signInWithTicket(ticket)` ——赎回单次使用票 `cub auth browser-session` (单位:千美元)`POST /auth/browser-session`)为会. 就是这样 一个浏览器在没有身份提供者的实例中签名 `/api/info` 通过广告显示 `AuthIssuer`· ; `login()` 拒绝方式 `NoIdentityProvider` 在这里。 会话后面没有 IDP, 所以当它过期时, 用户会运行 重新指挥.

## 外部反应

两个模块级函数将会话带入无法使用钩的代码,例如 数据客户端的请求设置 :

-   `getAccessToken()` ——当前符号,或未定义. 它从不返回过期的 符号:它启动提供者的恢复(每 `onUnauthorized`和未定义的返回, 页面从IdP那里回来.
-   `handleUnauthorized()` - 报告一个401。 仅需在它被拒绝之前 过期( 服务器密钥旋转, 取消会话); 过期由 `getAccessToken`. 已经开始恢复时不开放.

```ts
import { getAccessToken, handleUnauthorized } from '@confighub/react-auth';
import { configureConfigHub } from '@confighub/rtk-query';

configureConfigHub({ baseUrl, getToken: getAccessToken, onUnauthorized: handleUnauthorized });
```

## 坚挺姿态

铸币局保存在 `sessionStorage` 默认或内存 与 `persist: 'none'`永远 `localStorage`。瞬间 PKCE 状态已停放 `sessionStorage` 整个授权重定向。 被拒绝或过期的令牌触发 a 静态再校正(见 `onUnauthorized`)),需要实时的 IDP 会话;刷新 不使用指使符,所以指使符的寿命是没有指使符的页面最长的 转向.

`react` (18或19)是同龄人依赖关系.

## 常见问题

### @confighub/react-auth 是什么？

ConfigHub 浏览器应用软件\(OIDC PKCE \+ RFC 8693 令牌交换\)的反向认证提供者和钩子

### 如何安装 @confighub/react-auth？

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

### @confighub/react-auth 支持 TypeScript 吗？

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

### @confighub/react-auth 支持 ESM 还是 CommonJS？

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

### @confighub/react-auth 可以商用吗？

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

### @confighub/react-auth 的下载量有多少？

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

### @confighub/react-auth 还在维护吗？

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