# @boxyhq/saml20 中文文档

规范地址：https://npmcn.com/package/%40boxyhq/saml20/

版本：3\.1\.0
npm 元数据更新时间：2026-11-06T11:28:12.492Z
中文译文更新时间：2026-11-08T12:52:25.276Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：190 kB，51 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：5 个
- 首次发布：2021-08-22T21:18:56.147Z
- 最新版本发布：2026-11-06T11:28:12.130Z
- 近 30 天下载量：563573（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：121（近 12 个月 21 个）

## 中文简介

SAML 2. 0 节点符号解析器

## 安装

```sh
npm install @boxyhq/saml20
```

也可以使用：`pnpm add @boxyhq/saml20`、`yarn add @boxyhq/saml20`、`bun add @boxyhq/saml20`

## README

# SAML 2.0 解析器和验证器

![Build Status](https://github.com/ory/saml20/actions/workflows/node.js.yml/badge.svg)

一个用于Node.js的 SAML 2.0 库:它验证了 SAML 响应,并创建和剖析 Authn Requests, 登录消息和元数据. 它开始作为叉子 [萨姆尔20](https://github.com/leandrob/saml20) 从那时起,他背离了它。 Ory维护它,它出版于npm作为 [`@boxyhq/saml20`](https://www.npmjs.com/package/@boxyhq/saml20)。 。 。 .

## 安装

```bash
$ npm install @boxyhq/saml20
```

## 使用量

`validate()` 返回一个承诺.

### saml.validate( 缩写, 选项)

验证一个 SAML 响应(或一个孤独的 Assertion),并与用户的配置解析. 当一切失败的时候,它否认真理 `StatusCode`、缺失或无效的签名、过期的断言或失败的听众, `InResponseTo`, (中文(简体) ), `Recipient` 或者重新播放检查.

`rawResponse` 是 XML 作为字符串( 解码基数64) `SAMLResponse` 格式字段为先).

`options` (脚本 : `ValidateOptions`:

-   `publicKey`:可信任的IDP签名证书,作为Base64 DER或PEM. 几个证书(用于密钥旋转)用逗号分隔.
-   `thumbprint`:信任证书的 SHA-1 拇指印,逗号分隔. 证书本身取自 `KeyInfo` 的签名。 也通过 `publicKey` 或者说 `thumbprint`而不是两个.
-   `privateKey` (可选):解密a `EncryptedAssertion`。 。 。 .
-   `audience`:预期的观众,或被接受的观众名单. 每个 `AudienceRestriction` 在断言中,必须确切指明其中之一。 失败者 `Invalid audience.` 缺少或空值失败 `audience is required.`
-   `inResponseTo` (可选): `AuthnRequest` 此回复答案 。 设定时, 签名的内容必须带有相同的 `InResponseTo`; 缺少值失败。 失败者 `Invalid InResponseTo.`
-   `recipient` (可选). ACS URL的响应被张贴到,或者它可能已经张贴到的ACS URL列表(对于一个在几个地址接受响应的SP来说). 设定后,签名的内容必须命名(其中之一,每个候选人自行判断):签名 `Response/@Destination` 当任何携带者 `SubjectConfirmationData` 携带一个 `Recipient`,一个无记名确认书必须既取名,又在自己的范围内 `NotBefore`编号 :`NotOnOrAfter` 窗口(如此) `NotOnOrAfter` 需要为此而努力; `bypassExpiration` 跳过此窗口检查, 但不是 `Recipient` 两者中至少有一人必须在场。 一个空的 `Recipient` 计数为当前且从未匹配。 未签名者 `Response` 包装从不使用。 失败者 `Invalid Recipient.` 空字符串、 空列表或带有空条目的列表失败 `recipient must be a non-empty URL or a non-empty list of them.`
-   `assertionReplayValidator` (可选) : `(info) => boolean | Promise<boolean>`,在每张支票后打来 `{ assertionId, sessionIndex, notOnOrAfter, inResponseTo }` 从签名的断言。 返回时 `true` 如果该断言已经使用,则该反应作为回放被拒绝。 每个条目至少保存到 `notOnOrAfter` 加上10分钟,时钟摇摆 `validate()` 允许.
-   `bypassExpiration` (可选). 这种旗帜表示过期验证绕行(可用于测试,在生产环境中不推荐);
-   `allowedSignatureAlgorithms` 编号 : `allowedHashAlgorithms` (可选). 算法允许列表转发到 `validateSignature`,见下文.
-   `maxSignatureReferences` (可选). 上限 `SignedInfo/Reference` 页:1 `validateSignature`,见下文.

```javascript
const saml = require('@boxyhq/saml20').default;

const profile = await saml.validate(rawResponse, {
  publicKey: 'MIICDzCCAXygAwIBAgIQVWXAvbbQyI5Bc...',
  audience: 'https://sp.example.com',
  inResponseTo: requestId,
  recipient: 'https://sp.example.com/acs',
});

const { claims, issuer, sessionIndex, assertionId, notOnOrAfter } = profile;
```

错误是 `Error`s 有固定消息。 当原因更为具体(例如,为什么签名失败)时,错误是 `WrapError` 和原因在 `error.inner`。 。 。 .

### saml.parseIssuer( 缩写响应)

返回 `Issuer` 无法验证任何东西。 用它来找出一个响应的IP声称来自哪一个, 这样你就可以选择证书传递给 `validate()`。 。 。 .

```javascript
const issuer = saml.parseIssuer(rawResponse);
```

### saml.validate Signature(xml,公钥,指印,选项?)

验证 XML 签名于 `xml` 并返回已签名的 XML 。 从返回值而不是从 `xml`:只覆盖已签名的内容. 它在签名无效或无法检查时丢出; 不验证失败的签名 `invalid signature: the signature does not verify`。通过 `publicKey` (一个证书,或用逗号分隔若干个键旋转)或 `thumbprint`而不是两个.

`options` (可选)限制哪些算法被接受 :

-   `allowedSignatureAlgorithms` ——已接受 `SignatureMethod` (原始内容存档于2018-10-21). URIs.
-   `allowedHashAlgorithms` ——已接受 `DigestMethod` (原始内容存档于2018-10-21). URIs.

省略允许列表时, 默认设置从 `xml-crypto` 应用(RSA-SHA1,RSA-SHA256,RSA-SHA512和SHA-1,SHA-256,SHA-512摘要). 当给出一个时,一个使用任何其他算法的文档会被拒绝;一个空列表会拒绝一切.

-   `maxSignatureReferences` ——最大数量 `Reference` 签字时接受的要素 `SignedInfo` (默认16). 一个SAML的签名就有一个 天花板束缚着工作 `xml-crypto` 在核查之前 `SignatureValue`:每个引用都先被cononicalized,所以一个没有被约束的列表是未经认证的CPU拒绝服务. 超过上限的文件被拒绝 `invalid signature: SignedInfo declares N References; at most M are allowed`,在任何卡通化之前.

```javascript
var saml = require('@boxyhq/saml20').default;

var signedXml = saml.validateSignature(xml, publicKey, null, {
  allowedSignatureAlgorithms: [
    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512',
  ],
  allowedHashAlgorithms: [
    'http://www.w3.org/2001/04/xmlenc#sha256',
    'http://www.w3.org/2001/04/xmlenc#sha512',
  ],
});
```

## 升级到 2. 0

2.0 删除已贬值或波利斯不再使用的API:

-   只有包根可以被导入. `package.json` 现在有一个 `exports` 地图,所以软件包中的路径如下: `@boxyhq/saml20/dist/typings` 失败 `ERR_PACKAGE_PATH_NOT_EXPORTED` (与TS2307一起) `moduleResolution` `node16`, (中文(简体) ), `nodenext` 或者说 `bundler`) (中文(简体) ). 例如从根导入 `import type { SAMLProfile } from '@boxyhq/saml20'`。所有根输出都列在 `test/lib/compat.spec.ts`。 。 。 .
-   `parse()` 不见了 它在不检查签名,过期,观众或其他任何内容的情况下还原了一个剖面图,因此其输出可以被伪造. 使用 `validate()` 认证回复,以及 `parseIssuer()` 在验证前读取发行人(例如,选择IDP证书).
-   `decryptXml` 财务报告和审定财务报表 `PubKeyInfo` 不再从软件包根导出。 他们是内部帮手 `validate()` 财务报告和审定财务报表 `sign()`。 。 。 .
-   `hasValidSignature` 删除。 使用 `validateSignature()`,它也拒绝给予证书和拇指印.
-   `isMultiRootedXMLError` 删除。 以错误拒绝多根文档 `multirooted xml not allowed.`
-   `strictAudienceValidation` 观众总是被精确对比 在2.0之前,没有这个选项 `Audience` 仅仅从预期价值开始就被接受(`https://sp.example.com/metadata.evil.example` 通过了 `https://sp.example.com/metadata`) (中文(简体) ). 如果你依赖前缀匹配,通过所有接受的观众在 `audience` 换句话说.
-   `validateSignature()` 当签名无法校验时, 丢出它用来返回的地方 `null`。它现在要么返回签名的 XML ,要么丢出.
-   `audience` 需要时间。 在2.0之前,留它出去跳过观众检查,所以为其他信任同一IP的服务提供商发布的断言被接受.
-   `parseMetadata()`, (中文(简体) ), `parseSAMLRequest()`, (中文(简体) ), `parseLogoutRequest()` 财务报告和审定财务报表 `parseLogoutResponse()` 用相同的 XML 解析器解析为 `validate()` (单位:千美元)`@xmldom/xmldom`改为 `xml2js`。它们现在拒绝一个有多个根元素的文档。 文档使用的名称空间前缀而不声明它仍然被接受(前缀不参与结果),以及带有属性的证书元素. 文本和属性值得到线程和白空常态 XML 需要,所以用 CRLF 线程结尾粘贴的证书会在 LF 中返回 `publicKey` (数量) `thumbprint` 原文不变)。 例如, 解析器信件中存在错误的文档失败 `missing root element` 改为 `Non-whitespace before first tag.`,则 `&` 不开始引用( e)`a & b`失败 `Invalid XML.`
-   那个XML `request()`, (中文(简体) ), `createSAMLResponse()`, (中文(简体) ), `createLogoutRequest()`, (中文(简体) ), `createLogoutResponse()`, (中文(简体) ), `createIdPMetadataXML()` 财务报告和审定财务报表 `createSPMetadataXML()` 产品按序列排列 `xmlbuilder2` 改为 `xmlbuilder`。这些文档是相同的,只是已经存在于一个祖先范围内的命名空间声明不会在后人身上重复,带有空文本的元素写成 `<a></a>` 而不是说 `<a/>`A级 `saml:Assertion` 从 `createSAMLResponse()` 仍然声明它使用的每一个前缀,所以当它从它的 `samlp:Response`。 。 。 .

## 测试

```bash
$ npm test            # node:test with coverage
$ npm run typecheck   # type-checks lib/ and test/
$ npm run lint       # oxlint
```

修补者住在 `test/assets`。需要新有效性窗口的测试,或固定装置没有、构建和在辅助工具中签名的形状 `test/helpers/fixtures.ts`。 。 。 .

## 捐款

谢谢你花时间捐款! 贡献使得开放源码社区成为学习、激励和创造的惊人场所。 你所做的任何贡献都将造福所有人,并受到赞赏.

报告错误 [GitHub 问题](https://github.com/ory/saml20/issues)。请尝试创建以下错误报告:

-   _可复制._ 包括复制问题的步骤.
-   _具体._ 包括尽可能多的细节:哪个版本,什么环境等.
-   _独出一辙._ 不重复已打开的问题 .
-   _范围为单虫._ 每个报告一个错误.

## 报告安全问题

[负责任的披露](https://npmcn.com/package/%40boxyhq/saml20/SECURITY.md)

## 许可证

麻省理工学院

## 常见问题

### @boxyhq/saml20 是什么？

SAML 2\. 0 节点符号解析器

### 如何安装 @boxyhq/saml20？

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

### @boxyhq/saml20 支持 TypeScript 吗？

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

### @boxyhq/saml20 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @boxyhq/saml20 需要什么版本的 Node\.js？

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

### @boxyhq/saml20 可以商用吗？

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

### @boxyhq/saml20 的下载量有多少？

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

### @boxyhq/saml20 还在维护吗？

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