# @darioackermann/saml2-js 中文文档

规范地址：https://npmcn.com/package/%40darioackermann/saml2-js/

版本：7\.1\.0
npm 元数据更新时间：2025-03-31T15:17:02.433Z
中文译文更新时间：2026-11-11T11:43:48.763Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：247 kB，49 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：^18\.18\.0 \|\| ^20\.9\.0 \|\| \>=21\.1\.0
- 运行依赖：8 个
- 首次发布：2022-08-12T09:33:13.299Z
- 最新版本发布：2025-03-31T15:17:02.260Z
- 近 30 天下载量：2434（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

SAML 2. 0 节点帮助

## 安装

```sh
npm install @darioackermann/saml2-js
```

也可以使用：`pnpm add @darioackermann/saml2-js`、`yarn add @darioackermann/saml2-js`、`bun add @darioackermann/saml2-js`

## README

# @darioackermann/saml2-js (英语)

`@darioackermann/saml2-js` 是一个节点模块,它将 SAML 协议的复杂性归纳在一个易于使用的界面后。 它通过帮助您执行 SAML 协议的服务提供商来实现这一点. 它目前没有实施作为身份提供者的特征.

## 分叉通知

**这是叉子 [聪明/ saml2-js](https://github.com/Clever/saml2/)** 我会确保 依赖定期更新。 扩展现有功能的PR是受欢迎的.

## 使用量

安装方式 [无](https://www.npmjs.com/)。 。 。 .

```bash
  npm install @darioackermann/saml2-js --save
```

包含 SAML 库 .

```javascript
  var saml2 = require('@darioackermann/saml2-js');
```

## 文档

这个库输出出两个构造器.

-   [`ServiceProvider`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider) - 代表依赖信任的服务提供者 [`IdentityProvider`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 用于SAML流中的认证和授权.
-   [`IdentityProvider`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) - 代表一个认证SAML流量用户的在线服务.

**说明:** 可以在 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider), (中文(简体) ), [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider),和/或按方法。 对于在多处设置的选项,它们按以下顺序被推翻: 方法基础 _覆盖_ [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 哪个 _覆盖_ [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .

### 服务提供者( 选项)

代表依赖信任的服务提供商 [`IdentityProvider`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 用于SAML流中的认证和授权.

#### 选项

一个可以包含以下选项的对象。 所有选项都是字符串, 除非另有说明 。 见 [说明](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-note_options) 需要更多关于选项的信息.

-   `entity_id` - 说吧 **需求** - 服务提供者的独特标识符,经常是元数据文件的URL.
-   `private_key` - 说吧 **需求** - (PEM格式字符串) - 服务提供商的私人密钥.
-   `certificate` - 说吧 **需求** - (PEM格式字符串) - 服务商的证书.
-   `assert_endpoint` - 说吧 **需求** - 服务提供者的URL申明终点.
-   `alt_private_keys` – (Array of PEM格式字符串) - 试图解密响应时需要使用的额外私钥. 用于为旧证书在翻转后添加后相容性 .
-   `alt_certs` - (Array of PEM格式字符串) - 在 SAML 元数据中曝光的额外证书. 用于为翻转提供新证书 .
-   `audience` - (String或RegExp) - 如果设定,至少其中一种 `<Audience>` 数值 `<AudienceRestriction>` sAML 认证响应的条件必须匹配。 默认为 `entity_id`。 。 。 .
-   `notbefore_skew` – (数量) – 计算 IdP 和 SP 之间的时钟 skew , 请先于当前时间( 根据我们的时钟) 接受条件不早的反应 。 默认为 1 。 设定为0,以达到最佳安全,但不能容忍时钟摇晃.
-   `force_authn` - (Boolean) - 如果真实, 强制重新认证用户, 即使用户与 SSO 会话 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider)。也可以在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或按方法进行.
-   `auth_context` - 指定 `AuthnContextClassRef`。也可以按方法配置.
-   `nameid_format` - 名称标识格式。 这也可以按每方法配置.
-   `sign_get_request` 如果是真的,请在请求上签名 此选项也可以配置在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或按方法进行.
-   `allow_unencrypted_assertion` 如果是真的,允许不加密的断言。 此选项也可以配置在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或按方法进行.

#### 返回以下函数

-   [`create_login_request_url(IdP, options, cb)`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-create_login_request_url) - 获得一个URL启动登录.
-   [`redirect_assert(IdP, options, cb)`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-redirect_assert) - 如果登录尝试有效,则获得一个 SAML 响应对象,用于重定向绑定.
-   [`post_assert(IdP, options, cb)`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-post_assert) - 如果登录尝试有效, 则获取一个 SAML 响应对象, 用于邮局绑定 .
-   [`create_logout_request_url(IdP, options, cb)`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-create_logout_request_url)\- 创建 SAML 请求 URL 启动用户登录.
-   [`create_logout_response_url(IdP, options, cb)`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-create_logout_response_url) - 创建 SAML 响应 URL 确认成功 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 启动登录 .
-   [`create_metadata()`](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-create_metadata) - 返回初始 SAML 配置中使用的 XML 元数据 .

#### 示例

```javascript

  var sp_options = {
    entity_id: "https://sp.example.com/metadata.xml",
    private_key: fs.readFileSync("key-file.pem").toString(),
    certificate: fs.readFileSync("cert-file.crt").toString(),
    assert_endpoint: "https://sp.example.com/assert",
    force_authn: true,
    auth_context: { comparison: "exact", class_refs: ["urn:oasis:names:tc:SAML:1.0:am:password"] },
    nameid_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
    sign_get_request: false,
    allow_unencrypted_assertion: true
  }

  // Call service provider constructor with options
  var sp = new saml2.ServiceProvider(sp_options);

  // Example use of service provider.
  // Call metadata to get XML metatadata used in configuration.
  var metadata = sp.create_metadata();

```

#### 服务提供者函数定义

##### 创建 login request url( IdP, 选项, cb)

获取一个 URL 启动登录 .

提出下列论点:

-   `IdP` - 说吧 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider)
-   `options` - 一个可以包含以下选项的对象。 所有选项都是字符串, 除非另有说明 。 见 [说明](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-note_options) 需要更多关于选项的信息.
    -   `relay_state` - SAML中继状态.
    -   `auth_context` - 指定 `AuthnContextClassRef`。也可以在 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .
    -   `nameid_format` - 名称标识格式。 此选项也可以配置在 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .
    -   `force_authn`\- (Boolean) - 如果真实, 强制重新认证用户, 即使用户与 SSO 会话 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider)。也可以在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或者说 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .
    -   `sign_get_request` 如果是真的,请在请求上签名 此选项也可以配置在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或者说 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .
-   `cb(error, login_url, request_id)` - 以请求的登录 URL 和 ID 调用回话 .

##### 重定向 sassert( IdP, 选项, cb)

如果登录尝试有效, 则获得一个 SAML 响应对象, 用于重定向绑定 .

提出下列论点:

-   `IdP` - 说吧 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider)
-   `options` - 一个可以包含以下选项的对象。 所有选项都是字符串, 除非另有说明 。 见 [说明](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-note_options) 需要更多关于选项的信息.
    -   `request_body` - (Object) - 包含解析的查询字符串参数的对象. 此对象应包含其中任一对象的值 `SAMLResponse` 或者说 `SAMLRequest`。 。 。 .
    -   `allow_unencrypted_assertion` 如果是真的,允许不加密的断言。 此选项也可以配置在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或者说 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .
    -   `require_session_index` - (Boolean) - 如果虚假,允许断言有效,而不包含 `SessionIndex` 属性 `AuthnStatement` 节点.
-   `cb(error, response)` - 回电了 [请求答复](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-assert_response)。 。 。 .

SAML 声明回复的例子 :

```javascript
{ response_header:
   { id: '_abc-1',
     destination: 'https://sp.example.com/assert',
     in_response_to: '_abc-2' },
  type: 'authn_response',
  user:
   { name_id: 'nameid',
     session_index: '_abc-3',
     assertion_id: '_123',
     attributes:
      { 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname': [ 'Test' ] } } }
```

##### 后塞( IdP, 选项, cb)

如果登录尝试有效, 获取 SAML 响应对象, 用于邮局绑定 .

提出下列论点:

-   `IdP` - 说吧 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider)
-   `options` - 一个可以包含以下选项的对象。 所有选项都是字符串, 除非另有说明 。 见 [说明](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-note_options) 需要更多关于选项的信息.
    -   `request_body` - (Object) - 包含解析的查询字符串参数的对象. 此对象应包含其中任一对象的值 `SAMLResponse` 或者说 `SAMLRequest`。 。 。 .
    -   `allow_unencrypted_assertion` 如果是真的,允许不加密的断言。 此选项也可以配置在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或者说 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .
    -   `require_session_index` - (Boolean) - 如果虚假,允许断言有效,而不包含 `SessionIndex` 属性 `AuthnStatement` 节点.
    -   `audience` - (String或RegExp) - 如果设定,至少其中一种 `<Audience>` 数值 `<AudienceRestriction>` sAML 认证响应的条件必须匹配。 默认为 `entity_id`。 。 。 .
    -   `notbefore_skew` – (数量) – 计算 IdP 和 SP 之间的时钟 skew , 请先于当前时间( 根据我们的时钟) 接受条件不早的反应 。 默认为 1 。 设定为0,以达到最佳安全,但不能容忍时钟摇晃.
-   `cb(error, response)` - 回电了 [请求答复](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-assert_response)。 。 。 .

##### 创建 logout request url( IdP, 选项, cb)

创建 SAML 请求 URL 启动用户登录 .

提出下列论点:

-   `IdP` - 说吧 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider)。注释:可以通过 `sso_logout_url` 而不是IdP。 (笑声).
-   `options` - 一个可以包含以下选项的对象。 所有选项都是字符串, 除非另有说明 。 见 [说明](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-note_options) 需要更多关于选项的信息.
    -   `name_id` - 名称标识格式。 这也可以按每方法配置.
    -   `session_index` - 用于创建登录请求的会话索引.
    -   `allow_unencrypted_assertion` 如果是真的,允许不加密的断言。 此选项也可以配置在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或者说 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .
    -   `sign_get_request` 如果是真的,请在请求上签名 此选项也可以配置在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或者说 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .
    -   `relay_state` - SAML中继状态.
-   `cb(error, request_url)` - 回电请求登录请求url.

##### 创建 logout reswer url( IdP, 选项, cb)

创建 SAML 响应 URL 确认成功 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 启动登录 .

提出下列论点:

-   `IdP` - 说吧 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider)。注释:可以通过 `sso_logout_url` 而不是IdP。 (笑声).
-   `options` - 一个可以包含以下选项的对象。 所有选项都是字符串, 除非另有说明 。 见 [说明](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-note_options) 需要更多关于选项的信息.
    -   `in_response_to` - 请求的识别码,这是回应。 应对照任何发送的身份证进行核对.
    -   `sign_get_request` 如果是真的,请在请求上签名 此选项也可以配置在 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider) 或者说 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider)。 。 。 .
    -   `relay_state` - SAML中继状态.
-   `cb(error, response_url)` - 呼唤回 与登录响应url.

##### 创建数据( m)

返回初始 SAML 配置中使用的 XML 元数据 .

### 身份提供者( 选项)

代表一个认证SAML流中用户的在线服务.

返回时没有函数,只有函数可以传递给 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider) 函数.

#### 选项

一个可以包含以下选项的对象。 所有选项都是字符串, 除非另有说明 。 见 [说明](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-note_options) 需要更多关于选项的信息.

-   `sso_login_url` - 说吧 **需求** - 在登录请求中使用的登录 URL.
-   `sso_logout_url` - 说吧 **需求** - 登录url在登录请求中使用.
-   `certificates` - 说吧 **需求** -(PEM格式字符串或PEM格式字符串的数组) - 身份提供者的证书或证书(证书数量).
-   `force_authn` - (Boolean) - 如果真实, 强制重新认证用户, 即使用户与 SSO 会话 [报告](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-IdentityProvider)。也可以在 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider) 或按方法进行.
-   `sign_get_request` 如果是真的,请在请求上签名 也可以在 \[[战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider) 或按方法进行.
-   `allow_unencrypted_assertion` 如果是真的,允许不加密的断言。 此选项也可以配置在 [战略计划](https://npmcn.com/package/%40darioackermann/saml2-js/#readme-ServiceProvider) 或按方法进行.

#### 示例

```javascript

  // Initialize options object
  var idp_options = {
    sso_login_url: "https://idp.example.com/login",
    sso_logout_url: "https://idp.example.com/logout",
    certificates: [fs.readFileSync("cert-file1.crt").toString(), fs.readFileSync("cert-file2.crt").toString()],
    force_authn: true,
    sign_get_request: false,
    allow_unencrypted_assertion: false
  };

  // Call identity provider constructor with options
  var idp = new saml2.IdentityProvider(idp_options);

  // Example usage of identity provider.
  // Pass identity provider into a service provider function with options and a callback.
  sp.post_assert(idp, {}, callback);

```

## 示例: 快速执行

库用户需要执行一组 URL 端点,这里就是一个例子 [表达式](http://expressjs.com/) 结束点.

```javascript
var saml2 = require('saml2-js');
var fs = require('fs');
var express = require('express');
var app = express();
// If you're using express <4.0:
// var bodyParser = require('body-parser');
// app.use(bodyParser.urlencoded({
//   extended: true
// }));
app.use(express.urlencoded());

// Create service provider
var sp_options = {
  entity_id: "https://sp.example.com/metadata.xml",
  private_key: fs.readFileSync("key-file.pem").toString(),
  certificate: fs.readFileSync("cert-file.crt").toString(),
  assert_endpoint: "https://sp.example.com/assert"
};
var sp = new saml2.ServiceProvider(sp_options);

// Create identity provider
var idp_options = {
  sso_login_url: "https://idp.example.com/login",
  sso_logout_url: "https://idp.example.com/logout",
  certificates: [fs.readFileSync("cert-file1.crt").toString(), fs.readFileSync("cert-file2.crt").toString()]
};
var idp = new saml2.IdentityProvider(idp_options);

// ------ Define express endpoints ------

// Endpoint to retrieve metadata
app.get("/metadata.xml", function(req, res) {
  res.type('application/xml');
  res.send(sp.create_metadata());
});

// Starting point for login
app.get("/login", function(req, res) {
  sp.create_login_request_url(idp, {}, function(err, login_url, request_id) {
    if (err != null)
      return res.send(500);
    res.redirect(login_url);
  });
});

// Variables used in login/logout process
var name_id, session_index;

// Assert endpoint for when login completes
app.post("/assert", function(req, res) {
  var options = {request_body: req.body};
  sp.post_assert(idp, options, function(err, saml_response) {
    if (err != null)
      return res.send(500);

    // Save name_id and session_index for logout
    // Note:  In practice these should be saved in the user session, not globally.
    name_id = saml_response.user.name_id;
    session_index = saml_response.user.session_index;

    res.send("Hello #{name_id}! session_index: #{session_index}.");
  });
});

// Starting point for logout
app.get("/logout", function(req, res) {
  var options = {
    name_id: name_id,
    session_index: session_index
  };

  sp.create_logout_request_url(idp, options, function(err, logout_url) {
    if (err != null)
      return res.send(500);
    res.redirect(logout_url);
  });
});

app.listen(3000);

```

## 常见问题

### @darioackermann/saml2-js 是什么？

SAML 2\. 0 节点帮助

### 如何安装 @darioackermann/saml2-js？

在项目目录运行 npm install @darioackermann/saml2-js，或使用 pnpm add / yarn add / bun add。

### @darioackermann/saml2-js 支持 TypeScript 吗？

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

### @darioackermann/saml2-js 支持 ESM 还是 CommonJS？

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

### @darioackermann/saml2-js 需要什么版本的 Node\.js？

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

### @darioackermann/saml2-js 可以商用吗？

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

### @darioackermann/saml2-js 的下载量有多少？

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

### @darioackermann/saml2-js 还在维护吗？

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