# @authress/login 中文文档

规范地址：https://npmcn.com/package/%40authress/login/

版本：2\.7\.509
npm 元数据更新时间：2026-11-06T11:57:04.152Z
中文译文更新时间：2026-11-07T06:11:37.743Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40authress/login
原文对照：https://npmcn.com/package/%40authress/login/?lang=original
项目主页：https://authress.io/
源码仓库：https://github.com/Authress/authress-login.js

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

- 包体积（解压后）：342 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2023-03-16T10:59:35.516Z
- 最新版本发布：2026-11-06T11:57:03.762Z
- 近 30 天下载量：66001（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：184（近 12 个月 53 个）

## 中文简介

Authress 认证的通用登录 sdk 服务 。 为用户身份、认证和信使验证提供管理下的认证.

## 安装

```sh
npm install @authress/login
```

也可以使用：`pnpm add @authress/login`、`yarn add @authress/login`、`bun add @authress/login`

## README

![Authress media banner](https://authress.io/static/images/linkedin-banner.png)

# Authress 登录 UIS 的 SDK

[![](https://badge.fury.io/js/@authress%2Flogin.svg)](https://www.npmjs.com/package/@authress/login) [![](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://npmcn.com/package/%40authress/login/LICENSE) [![](https://img.shields.io/badge/Community-Authress-fbaf0b.svg)](https://authress.io/community)

用于javascript应用网站和用户身份认证的Authress通用登录SDK. 曾经作为服务供应商Authress 在 [https://authress.io (英语)](https://authress.io/)。 。 。 .

## 使用量

```sh
npm install @authress/login
```

然后要求软件包:

```js
import { LoginClient } from '@authress/login';
```

### 解决问题的使用

楼层或另一个捆绑工的麻烦,检查一下 [构建工具排除出错页面](https://npmcn.com/package/%40authress/login/docs/troubleshooting.md)。 。 。 .

## 开始

### 第 0 部分: 设置 Authress 登录

你会想创造:

-   至少一个提供者连接 - https://authress.io/app/#/manage?焦点=连接
-   一个代表您网络应用的应用程序 - https://authress.io/app/#/manage?焦点=应用程序

### 第一部分:Web App UI

在每次路由更改检查中都查看用户是否存在,如果用户没有将其重定向到登录提示.

```js
import { LoginClient } from '@authress/login';

// What is my applicationId => https://authress.io/app/#/manage?focus=applications
// What is my authressApiUrl? => https://authress.io/app/#/setup?focus=domain
const loginClient = new LoginClient({ authressApiUrl: 'https://login.application.com', applicationId: 'YOUR_APPLICATION_ID' });
const isUserLoggedIn = await loginClient.userSessionExists();
if (!isUserLoggedIn) {
  window.location.assign('/login');
}
```

在您的应用程序的登录屏幕中, 当用户选择如何登录时, 引导它们到那里 。 另指定您希望 Authress 在登录后将用户重定向到何处 。 默认这是用户当前位置 .

```js
await loginClient.authenticate({ connectionId: 'SELECTED_CONNECTION_ID', redirectUrl: window.location.href });
// Or if you know which tenant the user wants to log in with:
await loginClient.authenticate({ tenantLookupIdentifier: 'tenant-subdomain.app.com', redirectUrl: window.location.href });
return;
```

然后让用户登录的用户访问令牌用于下一部分的授权:

```js
const userToken = await loginClient.ensureToken();
```

### 第2部分:服务API中的用户认证

要认证您服务 API 中的用户, 由库在 `Part 1` 需要传递给您的服务。 标准是从登录卡中拉出,然后放入一个 `Authorization` 页眉 :

```js
const userToken = await loginClient.ensureToken();
const result = await fetch('https://api.application.com/v1/route', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${userToken}`
  }
})
```

在服务 API 侧,拉入 Authress 服务客户端库,然后验证访问符.

-   首先安装相伴库 : `npm install authress-sdk`
-   然后验证从授权信头收到的符号 :

```js
import { TokenVerifier } from '@authress/sdk';

try {
  // Grab authorization token from the request header, the best way to do this will be framework specific.
  const userToken = request.headers['Authorization'];
  // Specify your custom domain for tokens. Configurable at https://authress.io/app/#/manage?focus=applications
  const userIdentity = await TokenVerifier('https://login.application.com', userToken);
} catch (error) {
  console.log('User is unauthorized', error);
  return { statusCode: 401 };
}
```

### 平台扩展登录

平台扩展的目标是方便您的平台扩展开发者与Authress登录. 装入 `ExtensionClient` 在你的Javascript UI SDK, 通过在 `extensionId`。 。 。 .

```js
import { ExtensionClient } from '@authress/login';

// What is my custom Domain? => https://authress.io/app/#/setup?focus=domain
// What is my extensionId => https://authress.io/app/#/manage?focus=extensions
const extensionClient = new ExtensionClient('https://login.application.io', extensionId);

// redirectUrl is where the extension would like to return the user to after login
// * This method will redirect the user to the Authress Login UI screen with an auth code
const { accessToken } = await extensionClient.login(redirectUrl);

// .... After login the user is redirected to the redirectUrl
// * So try the login again:
const { accessToken } = await extensionClient.login(redirectUrl);

// * Or get the user claims from the token
await userData = await this.getUserIdentity();
```

## 高级

究竟这些方法是如何运作的以及何时应使用这些方法? 我们已就下列每一方法提供了一些先进的指导:

[方法文件](https://npmcn.com/package/%40authress/login/docs/advanced.md)

## 捐款

如果你有兴趣为@authress/login SDK做出贡献 [捐款](https://npmcn.com/package/%40authress/login/docs/contibution.md) 向导.

## 常见问题

### @authress/login 是什么？

Authress 认证的通用登录 sdk 服务 。 为用户身份、认证和信使验证提供管理下的认证\.

### 如何安装 @authress/login？

在项目目录运行 npm install @authress/login，或使用 pnpm add / yarn add / bun add。

### @authress/login 支持 TypeScript 吗？

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

### @authress/login 支持 ESM 还是 CommonJS？

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

### @authress/login 需要什么版本的 Node\.js？

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

### @authress/login 可以商用吗？

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

### @authress/login 的下载量有多少？

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

### @authress/login 还在维护吗？

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