# Auth0 SAML

{% hint style="success" %}
对应的[官方文档地址](https://bitwarden.com/help/article/saml-auth0/)
{% endhint %}

本文是**专门针对 Auth0** 用于配置 SAML 2.0 方式的 SSO 登录的帮助。有关其他 IdP 方式配置 SSO 登录的帮助，请参阅 [SAML 2.0 配置](/docs/admin-console/login-with-sso/sso-guides/generic-saml.md)。

配置需要在 Bitwarden 网页 App 和 Auth0 门户网站中同时进行。操作过程中，我们建议同时打开这两个界面，并按照文档记录的步骤顺序完成操作。

{% hint style="success" %}
**已经是 SSO 专家了吗？**跳过本文中的说明，然后下载示例配置，将里面的屏幕截图与您自己的配置进行比较。

**⬇️**[下载示例](https://bitwarden.com/assets/20UMzdVJ0bPm0ggsNF1QE5/e88a1f1e2ffbaddcf42c65d404916c23/saml-auth0-sample.zip)
{% endhint %}

## 在网页 App 中打开 SSO <a href="#open-sso-in-the-web-app" id="open-sso-in-the-web-app"></a>

登录到 Bitwarden [网页 App](https://bitwarden.com/help/getting-started-webvault/)，然后使用产品切换器打开管理控制台：

<div align="left" data-with-frame="true"><figure><img src="https://bitwarden.com/assets/2uxBDdQa6lu0IgIEfcwMPP/e3de3361749b6496155e25edcfdcf08b/2024-12-02_11-19-56.png?w=1013&#x26;fm=avif" alt=""><figcaption><p>产品切换器</p></figcaption></figure></div>

打开组织的**设置** → **单点登录**界面：

<div align="left" data-with-frame="true"><figure><img src="https://bitwarden.com/assets/20720mRAluo6crSdTiYJrn/1175889d7f6ab42fe7614f34cdd1dcdd/2024-12-04_09-41-15.png?w=1036&#x26;fm=avif" alt=""><figcaption><p>SAML 2.0 配置</p></figcaption></figure></div>

如果还没有为您的组织创建唯一的 **SSO 标识符**，请创建一个，然后从**类型**下拉菜单中选择 **SAML**。保持此界面打开，以方便参考。

如果愿意，您可以在此阶段关闭**设置唯一的 SP 实体 ID** 选项。这样做会从 SP 实体 ID 值中移除组织 ID，但大多数情况下都建议打开该选项。

{% hint style="success" %}
您可以选择性使用**成员解密选项**。了解如何开始使用[受信任设备 SSO](/docs/admin-console/login-with-sso/trusted-devices/about-trusted-devices.md) 和 [Key Connector](/docs/self-hosting/key-connector/about-key-connector.md)。
{% endhint %}

## 创建 Auth0 应用程序 <a href="#create-an-auth0-application" id="create-an-auth0-application"></a>

在 Auth0 门户中，使用应用程序菜单来创建一个 **Regular Web Application**：

{% embed url="<https://images.ctfassets.net/7rncvj1f8mw7/3EsE3HTVqocRvC1f2XSWbt/9077b5bc7801de7270372594e62b7aad/auth0-createapp.png?fm=webp&h=400&q=50&w=1040>" %}

点击 **Setting** 标签并配置以下信息，其中一些信息您需要从 Bitwarden 业务门户中获取：

{% embed url="<https://images.ctfassets.net/7rncvj1f8mw7/6MMUA6fh1HBgeEa1lCWXc5/4dc49064bcd846f5973595fed3f525e9/auth0-appsettings.png?fm=webp&h=569&q=50&w=860>" %}
Auth0 设置
{% endembed %}

| Auth0 设置                             | 描述                                                                                                                                                              |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                                 | 给此应用程序取一个专用于 Bitwarden 的名称。                                                                                                                                     |
| Domain                               | 请注意此值。在[后面的步骤中](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#identity-provider-configuration)您将需要它。                                              |
| Application Type                     | 选择 **Regular Web Application**。                                                                                                                                 |
| Token Endpoint Authentication Method | 选择 **Client Secret (Post)**，它将映射到[稍后配置](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#identity-provider-configuration)的 **Binding Type** 属性。      |
| Application Login URI                | <p>将此字段设置为从 Bitwarden SSO 配置界面中预先生成的 <strong>SP 实体 ID</strong>。<br><br>此自动生成的值可以从组织的<strong>设置</strong> → <strong>单点登录</strong>界面复制，并且会根据您的设置而有所不同。</p>         |
| Allowed Callback URLS                | <p>将此字段设置为从 Bitwarden SSO 配置界面中预先生成的<strong>断言消费者服务 (ACS) URL</strong>。<br><br>此自动生成的值可以从组织的<strong>设置</strong> → <strong>单点登录</strong>界面复制，并且会根据您的设置而有所不同。</p> |

### Grant Types

在 **Advanced Settings** → **Grant Types** 部分，确保选择了以下授权类型（可以预先选择）：

![应用程序授权类型](https://raw.githubusercontent.com/bitwarden/help/master/images/sso/cheatsheets/saml-auth0/auth0-advancedsettings.png)

### Certificates

在 **Advanced Settings** → **Certificates** 部分，复制或下载您的签名证书。你现在还不需要用它做任何事情，但需要[稍后引用](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#identity-provider-configuration)它。

![Auth0 证书](https://raw.githubusercontent.com/bitwarden/help/master/images/sso/cheatsheets/saml-auth0/auth0-certificate.png)

### Endpoints

&#x20;不需要在 **Advanced Settings** → **Endpoints** 部分编辑任何东西，但你需要这个 SAML 端点，以便[稍后引用](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#identity-provider-configuration)它。

{% hint style="info" %}
在较小的窗口中，**Endpoints** 选项卡可能会消失在浏览器的边缘。如果您找不到它，请单击 **Certificates** 选项卡，然后按右方向键键（→）。
{% endhint %}

![Auth0 端点](https://raw.githubusercontent.com/bitwarden/help/master/images/sso/cheatsheets/saml-auth0/auth0-endpoints.png)

## ~~配置 Auth0 规则~~ <a href="#configure-auth0-rules" id="configure-auth0-rules"></a>

~~创建规则来定制你的应用程序的 SAML 响应行为。虽然 Auth0 提供了~~[~~多个选项~~](https://auth0.com/docs/protocols/saml-protocol/customize-saml-assertions#saml-assertion-attributes)~~，但这里将只关注那些专门映射到 Bitwarden 的选项。要创建一个自定义 SAML 配置规则集，请使用 **Auth Pipeline → Rules** 菜单来 **Create**（创建）规则：~~

![Auth0 规则](https://raw.githubusercontent.com/bitwarden/help/master/images/sso/cheatsheets/saml-auth0/auth0-settings.png)

~~以下任何项目均可配置：~~

| 键                      | 描述                                                                                                                                                                                                                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signatureAlgorithm`   | <p>Auth0 使用此算法对 SAML 断言或响应进行签名。默认为 <code>rsa-sha1</code>，您也可以将值设置为 <code>rsa-sha256</code>。</p><p></p><p>如果您更改了这个值，您必须：</p><p>-将 <code>digestAlgorithm</code> 设置为 <code>sha256</code>。</p><p>-（在 Bitwarden 中）将 <strong>Minimum Incoming Signing Algorithm</strong> 设置为 <code>rsa-sha256</code>。</p>     |
| `digestAlgorithm`      | 此算法用于计算 SAML 断言或响应的摘要。默认为 `sha-1`。如果您更改了 `signatureAlgorithm` 的值，您还应该将此值设置为 `sha256`.                                                                                                                                                                                                                   |
| `signResponse`         | 默认，Auth0 将仅对 SAML 断言进行签名。将此属性设置为 `true` 可对 SAML 响应（而不是断言）进行签名。                                                                                                                                                                                                                                          |
| `nameIdentifierFormat` | 默认为 `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`。您可以将值设置为[任一 SAML NameID 格式](https://docs.oracle.com/cd/E19316-01/820-3886/ggwbz/index.html)。如果这样做了，请将 SP **Name ID Format** 字段更改为相应的选项（参阅[这里](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#service-provider-configuration)）。 |

~~使用像下面这样的 **Script**（脚本）来实现这些规则。如需帮助，请参阅~~ [~~Auth0 文档~~](https://auth0.com/docs/protocols/saml-protocol/customize-saml-assertions#customize-saml-assertions-with-rules)~~。~~

```systemd
function (user, context, callback) {
    context.samlConfiguration.signatureAlgorithm = "rsa-sha256";
    context.samlConfiguration.digestAlgorithm = "sha256";
    context.samlConfiguration.signResponse = "true";
    context.samlConfiguration.nameIdentifierFormat = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
    context.samlConfiguration.binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect";
    callback(null, user, context);
}
```

## 配置 Auth0 操作 <a href="#configure-auth0-actions" id="configure-auth0-actions"></a>

创建操作来自定义 Auth0 将在登录后流程中使用的逻辑，并规定与 Bitwarden 交换的参数。要创建必要的操作：

1、导航到 **Actions** → **Library** 然后选择 **Create Action** → **Build from scratch**。

2、为您的操作指定一个名称，例如 `Bitwarden SSO`，选择 **Login / Post Login** 触发器，选择 **Node 18 (Recommended)** 运行时选项，然后选择 **Create**。

3、在集成代码编辑器中，添加以下规则：

```yaml
exports.onExecutePostLogin = async (event, api) => {
    // Modify SAML configuration settings
    if (event.request.protocol === 'samlp') {
        api.saml.updateConfiguration({
            signatureAlgorithm: "rsa-sha256",
            digestAlgorithm: "sha256",
            signResponse: true,
            nameIdentifierFormat: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
            binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
        });
    }
};
```

4、选择 **Deploy**。

5、导航到 **Actions** → **Triggers** 然后选择 `post-login` 触发器。

6、将新操作拖放到 **Post Login** 流程中，然后选择 **Apply**。

配置上述操作时，您可以自定义以下任意属性以满足您的需求：

| 键                      | 描述                                                                                                                                                                                                                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signatureAlgorithm`   | <p>Auth0 使用此算法对 SAML 断言或响应进行签名。默认为 <code>rsa-sha1</code>，您也可以将值设置为 <code>rsa-sha256</code>。<br><br>如果您更改了这个值，您必须：<br>-将 <code>digestAlgorithm</code>  设置为 <code>sha256</code>。<br>-（在 Bitwarden 中）将 <strong>Minimum Incoming Signing Algorithm</strong> 设置为 <code>rsa-sha256</code>。</p>                |
| `digestAlgorithm`      | 此算法用于计算 SAML 断言或响应的摘要。将此值设置为 `sha-256`.                                                                                                                                                                                                                                                                 |
| `signResponse`         | 默认，Auth0 将仅对 SAML 断言进行签名。将此属性设置为 `true` 可对 SAML 响应（而不是断言）进行签名。                                                                                                                                                                                                                                          |
| `nameIdentifierFormat` | 默认为 `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`。您可以将值设置为[任一 SAML NameID 格式](https://docs.oracle.com/cd/E19316-01/820-3886/ggwbz/index.html)。如果这样做了，请将 SP **Name ID Format** 字段更改为相应的选项（参阅[这里](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#service-provider-configuration)）。 |

### 从规则迁移到操作 <a href="#migrate-from-rules-to-actions" id="migrate-from-rules-to-actions"></a>

2024 年 11 月 18 日，Auth0 将弃用规则。如果您当前正在使用本文档先前版本中描述的规则，则可以使用 Auth0 规则界面上的 **Migrate to Action** 按钮来简化此过程。如果您这样做：

* 不要关闭预先存在的规则。
* 请按照上述步骤 5 和 6 中的说明将新操作添加到您的 `post-login` 触发器中。

## 返回网页 App <a href="#back-to-the-web-app" id="back-to-the-web-app"></a>

至此，您已经在 Auth0 门户网站配置好了您所需要的一切。请返回 Bitwarden 网页 App 完成配置。

单点登录界面将配置分为两个部分：

* &#x20;**SAML 服务提供程序配置**将决定 SAML 请求的格式。
* &#x20;**SAML 身份提供程序配置**将决定用于 SAML 响应的预期格式。

### 服务提供程序配置 <a href="#service-provider-configuration" id="service-provider-configuration"></a>

除非您已配置了[自定义规则](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#configure-auth-0-rules)，否则您的服务提供重新配置就已经完成了。如果您配置了自定义规则或要对实现做进一步的更改，请编辑相关字段：

| 字段                                 | 描述                                                                                                                                           |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Name ID Format                     | [NameID Format](https://docs.oracle.com/cd/E19316-01/820-3886/ggvxx/index.html) 用于在 SAML 请求（`NameIDPolicy`）中指定。要忽略它，请设置为 **Not Configured**。 |
| Outbound Signing Algorithm         | 用于签名 SAML 请求的算法，默认为 `rsa-sha256`。                                                                                                            |
| Signing Behavior                   | SAML 请求是否/何时将被签名。默认，Auth0 不要求对请求进行签名。                                                                                                        |
| Minimum Incoming Signing Algorithm | Bitwarden 在 SAML 响应中接受的最小签名算法。选择 `rsa-sha256` 除非您配置了[自定义签名操作](#configure-auth0-actions)。                                                     |
| Want Assertions Signed             | Bitwarden 是否要求 SAML 断言被签名。默认，Auth0 对 SAML 断言进行签名，因此请选中此框，除非您配置了[自定义签名操作](#configure-auth0-actions)。                                          |
| Validate Certificates              | 通过受信任的 CA 使用来自 IdP 的受信任和有效证书时，请选中此框。除非在 Bitwarden SSO 登录 docker 镜像中配置了适当的信任链，否则自签名证书可能会失败。                                                   |

完成服务提供程序配置部分后，**保存**您的工作。

### 身份提供程序配置 <a href="#identity-provider-configuration" id="identity-provider-configuration"></a>

身份提供程序配置通常需要您返回 Auth0 门户以获取应用程序的值：

| 字段                                  | 描述                                                                                                                                                                                                                                           |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entity ID                           | 输入您的 Auth0 应用程序的 **Domain** 值（参考[此处](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#create-an-auth-0-application)），使用前缀 `urn:`，例如，`urn:bw-help.us.auth0.com`。                                                                   |
| Binding Type                        | 选择 **HTTP POST** 以匹配在您的 Auth0 应用程序中指定的 [Token Endpoint Authentication Method](#create-an-auth0-application) 的值。                                                                                                                              |
| Single Sign On Service URL          | 输入您的 Auth0 应用程序的 **SAML Protocol URL**（参阅 [Endpoints](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#endpoints)）。例如，`https://bw-help.us.auth0.com/samlp/HcpxD63h7Qzl420u8qachPWoZEG0Hho2`。                                      |
| Single Log Out Service URL          | SSO 登录当前还**不支持** SLO。该选项计划未来开发，但是您可以根据需要预先配置它。                                                                                                                                                                                               |
| Artifact Resolution Service URL     | 输入您的 Auth0 应用程序的 **SAML Metadata URL**（参阅 [Endpoints](/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md#endpoints)）。例如，`https://bw-help.us.auth0.com/samlp/metadata/HcpxD63h7Qzl420u8qachPWoZEG0Hho2`.                             |
| X509 Public Certificate             | <p>黏贴获取到的 <a href="/pages/-MZSki8OxI1AWzWVfUpd#certificates">Signing Certificate</a>，移除 <code>-----BEGIN CERTIFICATE-----</code>  和 <code>-----END CERTIFICATE-----</code>。<br><br>证书值区分大小写，多余的空格、回车符和其他多余的字符<strong>将导致证书验证失败</strong>。</p> |
| Outbound Signing Algorithm          | 选择 `rsa-sha256` 除非您配置了[自定义签名操作](#configure-auth0-actions)。                                                                                                                                                                                   |
| Disable Outbound Logout Requests    | SSO 登录当前还**不支持** SLO。该选项计划未来开发。                                                                                                                                                                                                              |
| Want Authentication Requests Signed | Auth0 是否要求 SAML 请求被签名。                                                                                                                                                                                                                       |

{% hint style="info" %}
填写 X509 证书时，请注意到期日期。必须续签证书，以防止向 SSO 最终用户提供的服务中断。如果证书已过期，管理员和所有者账户将始终可以使用电子邮箱地址和主密码登录。
{% endhint %}

完成身份提供程序配置部分后，**保存**您的工作。

{% hint style="success" %}
您可以通过激活单点登录身份验证策略来要求用户使用 SSO 登录。请注意，这需要先激活单一组织策略。[了解更多](/docs/admin-console/oversight-visibility/enterprise-policies.md)。
{% endhint %}

## 测试配置 <a href="#test-the-configuration" id="test-the-configuration"></a>

配置完成后，通过导航到 <https://vault.bitwarden.com> 或 [https://vault.bitwarden.eu](https://vault.bitwarden.eu/)，输入您的电子邮箱地址，然后选择**使用单点登录**按钮进行测试：

<div align="left" data-with-frame="true"><figure><img src="https://bitwarden.com/assets/3BdlHeogd42LEoG06qROyQ/c68021df4bf45d72e9d37b1fbf5a6040/login.png?w=517&#x26;fm=avif" alt=""><figcaption><p>登录选项界面</p></figcaption></figure></div>

输入[已配置的组织标识符](#open-sso-in-the-web-app)，然后选择**登录**。如果您的实施已成功配置，您将被重定向到 Auth0 的登录界面：

<div align="left" data-with-frame="true"><img src="https://raw.githubusercontent.com/bitwarden/help/master/images/sso/cheatsheets/saml-auth0/auth0-login.png" alt="Auth0 登录界面"></div>

使用您的 Auth0 凭据进行身份验证后，输入您的 Bitwarden 主密码以解密您的密码库！

{% hint style="info" %}
Bitwarden 不支持未经请求的响应，因此从您的 IdP 发起登录将导致错误。SSO 登录流程必须从 Bitwarden 发起。
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.ppgg.in/docs/admin-console/login-with-sso/sso-guides/auth0-saml.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.