# @asgardeo/auth-react 中文文档

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

版本：5\.6\.3
npm 元数据更新时间：2026-11-09T05:42:17.940Z
中文译文更新时间：2026-11-09T05:45:23.361Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：753 kB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=16\.8，react-dom \>=16\.8，@babel/runtime-corejs3 ^7\.11\.2
- 首次发布：2021-01-15T14:11:03.271Z
- 最新版本发布：2026-11-09T05:42:17.734Z
- 近 30 天下载量：6123（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：91（近 12 个月 6 个）

## 中文简介

Asgardeo Auth React SDK 用于反应应用.

## 安装

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

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

## README

# Asgardeo Auth 反应 SDK

> \[尖叫声\] **折旧通知**
> 
> Asgardeo Auth 反应 SDK 已经 **已贬值** 已经 **不再维持**。 。 。 .  
> 现在改为: [**@asgardeo/反应**](https://github.com/asgardeo/javascript/tree/main/packages/react),现在是官方的一部分 [**Asgardeo JavaScript SDK套件**](https://github.com/asgardeo/javascript)。 。 。 .
> 
> 请将您的工程迁移到新的 SDK , 以获取最新的更新、 特性和安全改进 .

![Builder](https://github.com/asgardeo/asgardeo-auth-react-sdk/workflows/Builder/badge.svg) [![Stackoverflow](https://img.shields.io/badge/Ask%20for%20help%20on-Stackoverflow-orange)](https://stackoverflow.com/questions/tagged/wso2is) [![Join the chat at https://discord.gg/wso2](https://img.shields.io/badge/Join%20us%20on-Discord-%23e01563.svg)](https://discord.gg/wso2) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/wso2/product-is/blob/master/LICENSE) [![Twitter](https://img.shields.io/twitter/follow/wso2.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=wso2)

* * *

## 目录

-   [导言](https://npmcn.com/package/%40asgardeo/auth-react/#readme-introduction)
-   [先决条件](https://npmcn.com/package/%40asgardeo/auth-react/#readme-prerequisite)
-   [开始](https://npmcn.com/package/%40asgardeo/auth-react/#readme-getting-started)
-   [使用 APIs](https://npmcn.com/package/%40asgardeo/auth-react/#readme-using-apis)
    -   [使用API的最佳做法](https://npmcn.com/package/%40asgardeo/auth-react/#readme-best-practices-when-using-apis)
    -   [`useAuthContext()` 钩子](https://npmcn.com/package/%40asgardeo/auth-react/#readme-useauthcontext-hook)
    -   [添加登录/ 日志按钮](https://npmcn.com/package/%40asgardeo/auth-react/#readme-add-a-loginlogout-button)
    -   [显示认证用户信息](https://npmcn.com/package/%40asgardeo/auth-react/#readme-show-authenticated-users-information)
    -   [添加运行](https://npmcn.com/package/%40asgardeo/auth-react/#readme-add-routing)
    -   [API 文档](https://npmcn.com/package/%40asgardeo/auth-react/#readme-api-documentation)
-   [应用程序样本](https://npmcn.com/package/%40asgardeo/auth-react/#readme-sample-apps)
-   [开发](https://npmcn.com/package/%40asgardeo/auth-react/#readme-develop)
-   [贡献](https://npmcn.com/package/%40asgardeo/auth-react/#readme-contribute)
-   [许可证](https://npmcn.com/package/%40asgardeo/auth-react/#readme-license)

## 导言

Asgardeo Auth React SDK 允许 React 应用程序使用 [OpenID 连接 - OIDC](https://openid.net/specs/openid-connect-core-1_0.html) 认证 [阿斯加多语Name](https://wso2.com/asgardeo) 作为消费者身份和获取管理提供商。 SDK 支持以下能力

-   [认证用户](https://npmcn.com/package/%40asgardeo/auth-react/#readme-add-a-loginlogout-button)
-   [显示认证用户信息](https://npmcn.com/package/%40asgardeo/auth-react/#readme-show-authenticated-users-information)
-   [获取额外的用户信息](https://npmcn.com/API.md#getbasicuserinfo)
-   [安全组件](https://npmcn.com/API.md#3-authenticatedcomponent)
-   [将 HTTP 请求发送到 Asgardeo](https://npmcn.com/API.md#httprequest)

## 先决条件 - 在 Asgardeo 登记您的申请

1.  注册到 [阿斯加多语Name](https://wso2.com/asgardeo) 并创建一个组织 如果你还没有一个。 您选择的组织名称将被称为 `<org_name>` 本文件全文.
2.  [在 Asgardeo 中注册一个单页应用程序](https://wso2.com/asgardeo/docs/guides/applications/register-single-page-app/#register-the-app) 以获取必要的密钥来整合您的应用程序。 你会得到一个 `client_ID` 从Asgardeo的应用程序,需要嵌入您的整合申请的后期.

## 开始

遵循此指南将 Asgardeo 集成到您自己的反应应用中 。 试出试样的应用程序,使用 [本指南](https://npmcn.com/SAMPLE_APPS.md)。 。 。 .

### 1\. 安装软件包

运行以下命令以安装 `@asgardeo/auth-react` 从 npm 注册.

```bash
npm install @asgardeo/auth-react --save
```

### 2\. 进口 [`AuthProvider`](https://npmcn.com/API.md#authprovider) 提供 [配置参数](https://npmcn.com/API.md#authreactconfig)

Asgardeo 反应 SDK 曝光 `AuthProvider` 组件,它帮助您将 Asgardeo 与您的应用程序结合.

首先导入 `AuthProvider` 构成部分从 `@asgardeo/auth-react.` 中定义了应用程序根组件.

> **说明** 通常反应app的根组件在索引.\* 文件中被定义.

```TypeScript
import { AuthProvider } from "@asgardeo/auth-react";
```

然后,用 `AuthProvider`。 。 。 .

```TypeScript
import React from "react";
import { AuthProvider } from "@asgardeo/auth-react";

const config = {
     signInRedirectURL: "https://localhost:3000/sign-in",
     signOutRedirectURL: "https://localhost:3000/dashboard",
     clientID: "<client_ID>",
     baseUrl: "https://api.asgardeo.io/t/<org_name>",
     scope: [ "openid","profile" ]
};

export const MyApp = (): ReactElement => {
    return (
        <AuthProvider config={ config }>
            <App />
        </AuthProvider>
    )
}
```

> **说明** 你可以提到 [详细情况 `AuthProvider` `config` 这里](https://npmcn.com/API.md#authreactconfig)

一旦根元件被AuthProvider所包裹, [`useAuthContext()` 钩子](https://npmcn.com/package/%40asgardeo/auth-react/#readme-useauthcontext-hook) 可以在应用程序的任何地方用于实施应用程序中的用户认证能力.

## 使用 APIs

### 使用API的最佳做法

Asgardeo Auth React SDK 建于顶部 [阿斯加德奥特SPA SDK](https://github.com/asgardeo/asgardeo-auth-spa-sdk)一个基础图书馆 因此,几乎所有来自 Auth SPA SDK 的可用API 都从 Asgardeo Auth React SDK 重新被输出,您不需要从基库导入依赖性到您的应用程序 .

-   应用程序依赖性中唯一应该列出的 SDK 是 `@asgardeo/auth-react`。 。 。 .
-   总是从中导入 API `@asgardeo/auth-react`。 。 。 .

> **3⁄4 ̄ ̧漯B** IDE 或编辑器自动导入有时会导入某些 API `@asgardeo/auth-spa`手动把它们换回来.

**单击这里获取提示 :** 从 Asgardeo React SDK 导入组件时

#### 做点什么

```TypeScript
import { AsgardeoSPAClient } from "@asgardeo/auth-react";
```

#### 当将 SDK 包含为依赖时 :

##### 做点什么

```json
// In package.json

dependencies: {
    "@asgardeo/auth-react": "^2.0.0"
}
```

* * *

### `useAuthContext()` 钩子

这个 `useAuthContext()` sDK提供的钩子可用于实施必要的认证功能并访问包含诸如认证用户唯一标识等信息的会话状态.

导入 `useAuthContext()` 钩从 `@asgardeo/auth-react`。 。 。 .

```Typescript
import { useAuthContext } from "@asgardeo/auth-react";
```

然后在您的组件中, 您可以访问上下文如下

```Typescript
const { state, signIn, signOut } = useAuthContext();
```

在应用程序中执行认证能力时,您需要的常用方法很少.

-   [`signIn`](https://npmcn.com/package/%40asgardeo/auth-react/API.md#signin) - 启动对Asgardeo的登录请求,处理响应以获取认证响应.
-   [`signOut`](https://npmcn.com/package/%40asgardeo/auth-react/API.md#signout) - 从Asgardeo登录用户,并清除SDK存储中的任何认证数据.
-   [`isAuthenticated`](https://npmcn.com/package/%40asgardeo/auth-react/API.md#isauthenticated) - 检查是否有经过认证的用户会话 。 根据结果可以决定更改应用程序视图/行为.
-   [`getBasicUserInfo`](https://npmcn.com/package/%40asgardeo/auth-react/API.md#getbasicuserinfo) - 从认证回复中获得认证用户的基本信息.
-   [`getDecodedIDToken`](https://npmcn.com/package/%40asgardeo/auth-react/API.md#getdecodedidtoken) - 解码 `id_token` 在认证回复中获取。 您可以从中获取更多信息, 如额外的用户属性 .
-   [`getIDToken`](https://npmcn.com/package/%40asgardeo/auth-react/API.md#getidtoken) - 拿来 `id_token` (JWT)在认证响应中获得.
-   [`getAccessToken`](https://npmcn.com/package/%40asgardeo/auth-react/API.md#getaccesstoken) - 拿来 `access_token` 在认证回复中获取.
-   [`refreshAccessToken`](https://npmcn.com/package/%40asgardeo/auth-react/API.md#refreshaccesstoken) - 拿来 `refresh_token` 在认证回复中获取.
-   [`getHttpClient`](https://npmcn.com/package/%40asgardeo/auth-react/API.md#gethttpclient) - 获取 Httpclient 实例, 以便您可以给后端打个电话, 客户端将在请求中附加必要的授权信头 .

这个 [`state`](https://npmcn.com/package/%40asgardeo/auth-react/API.md##authstateinterface) 对象将包含诸如用户是否正在登录、当前登录用户的用户名等属性.

> **说明** 你可以提到 [这里详细的 API 文档](https://npmcn.com/API.md)

* * *

### 添加登录/ 日志按钮

你可以用这个 `signIn()` 方法从 `useAuthContext()` 易于执行 **登录按钮**。 。 。 .

```Typescript
<button onClick={ () => signIn() }>Login</button>
```

与上述步骤类似,我们可以使用 `signOut()` 方法从 `useAuthContext()` 执行 **登录按钮**。 。 。 .

```Typescript
<button onClick={() => signOut()}>Logout</button>
```

正在点击 **登录按钮** 将把用户带入 Asgardeo 登录页面。 成功时 `signIn()`,用户会被重定向到应用程序(根据指定的 `signInRedirectURL`)和 `state.isAuthenticated` 将设定为 `true`。 。 。 .

正在点击 **注销按钮** 并重新定向到 `signOutRedirectURL` 编辑 `state.isAuthenticated` 将设定为 `false`。 。 。 .

> **说明** 而不是按钮,你可以使用 `signIn()` 打开 `signOut()` 从 SDK 执行应用程序中任何预设的用户经验的方法

你可以用这个 `state.isAuthenticated` 属性以检查用户的认证状态.

* * *

### 显示认证用户信息

下面的代码片段显示了该代码的用法: `state` 对象,连同 `signIn()` 财务报告和审定财务报表 `signOut()` 方法从上下文.

```Typescript
import React from "react";
import { useAuthContext } from "@asgardeo/auth-react";

function App() {

  const { state, signIn, signOut } = useAuthContext();

  return (
    <div className="App">
      {
        state.isAuthenticated
          ? (
            <div>
              <ul>
                <li>{state.username}</li>
              </ul>

              <button onClick={() => signOut()}>Logout</button>
            </div>
          )
          : <button onClick={() => signIn()}>Login</button>
      }
    </div>
  );
}

export default App;
```

* * *

### 添加运行

如果您的应用程序需要路由, SDK 提供多种方法来保障您的应用程序中的路径安全 。 你可以读更多关于 [这里的阿斯加德奥的路由能力](https://npmcn.com/API.md#securing-routes-with-asgardeo)。 。 。 .

* * *

### API 文档

除此之外,Asgardeo还提供一系列广泛的API,用于在您的反应应用中整合和使用Asgardeo. 你可以指一个 [这里详细的 API 文档](https://npmcn.com/API.md)。 。 。 .

## 应用程序样本

Asgardeo提供的试样反应Apps可以让你带Asgardeo去旋转,而无需自己设置应用程序. 你看见了 [如何在此设置样本应用程序](https://npmcn.com/SAMPLE_APPS.md)。 。 。 .

## 开发

### 先决条件

-   `Node.js` (第10版或以上).
-   `yarn` 软件包管理器.

### 安装依赖关系

该寄存器是一个单发寄存器. SDK 存储器见于 [独立](https://npmcn.com/lib/) 目录。 您可以在根部运行以下命令来安装依赖性 .

```bash
yarn build
```

## 贡献

请阅读 [对守则基础的贡献](http://wso2.github.io/) 详细介绍我们的行为守则和向我们提交拉动请求的程序.

### 报告问题

我们鼓励您报告问题、改进和特性要求 [Github 问题](https://github.com/asgardeo/asgardeo-auth-react-sdk/issues)。 。 。 .

重要:请注意,安全问题必须报告给Security@wso2com,而不是作为GitHub问题,以便达到适当的受众。 我们强烈建议在报告安全问题时遵循《第二安全标准报告准则》.

## 许可证

这个项目根据Apache许可证2.0获得许可. 见 [自由主义](https://npmcn.com/package/%40asgardeo/auth-react/LICENSE) 详细文件.

## 常见问题

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

Asgardeo Auth React SDK 用于反应应用\.

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

在项目目录运行 npm install @asgardeo/auth-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8）、react-dom（\>=16\.8）、@babel/runtime-corejs3（^7\.11\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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