# 使用 SAML 配置 SSO

本指南介绍如何使用 SAML 2.0 协议为 API7 控制台配置单点登录（SSO）。SAML SSO 允许用户通过企业身份提供商（IdP）进行认证，并在无需维护单独账户的情况下访问控制台。

## 工作原理[​](#工作原理 "工作原理的直接链接")

<!-- -->

1. 用户在控制台登录页选择 SAML 登录选项。
2. 控制台向 IdP 发送 SAML AuthnRequest。
3. 认证完成后，IdP 会将 SAMLResponse POST 到控制台的断言消费服务（ACS）URL。
4. 控制台验证 SAML 断言，提取用户属性，并创建或更新用户账户。
5. 如果配置了角色和权限边界映射，这些映射会在每次登录时应用。

## 前置条件[​](#前置条件 "前置条件的直接链接")

开始前，请确保你已具备：

* 正在运行且可访问控制台的 API7 网关部署。

* 符合 SAML 2.0 标准的身份提供商，例如 Microsoft Entra ID、Okta 或 Ping Identity。

* 来自 IdP 的以下信息：

  <!-- -->

  * **IdP Metadata URL**：提供 IdP SAML 元数据 XML 的 URL。
  * **属性名称**：`username`、`email` 以及所有角色相关属性的声明名称。

## 第 1 步：创建 SAML 登录选项[​](#第-1-步创建-saml-登录选项 "第 1 步：创建 SAML 登录选项的直接链接")

首先在 API7 中创建登录选项，以生成服务提供商（SP）元数据 URL，后续配置 IdP 时需要使用这些 URL。

1. 在 API7 控制台中，进入 **组织 > 设置**。
2. 点击 **新增登录选项**。
3. 填写配置：

| 字段                     | 描述                                             | 示例                                                                |
| ------------------------ | ------------------------------------------------ | ------------------------------------------------------------------- |
| **名称**                 | 登录页显示的名称，格式为 "使用 {Name} 登录"      | `Corporate SAML`                                                    |
| **提供商**               | 选择 `SAML`                                      | —                                                                   |
| **身份提供商元数据 URL** | IdP SAML 元数据 XML 的 URL                       | `https://login.microsoftonline.com/{tenant}/federationmetadata/...` |
| **服务提供商根 URL**     | 用户访问控制台的 URL                             | `https://dashboard.example.com`                                     |
| **实体 ID**              | SAML 联邦中 SP 的唯一标识。建议使用控制台 URL。  | `https://dashboard.example.com`                                     |
| **属性映射**             | 将 SAML 断言属性映射到 API7 用户字段             | 见下方提供商专用部分                                                |
| **登出时终止 IdP 会话**  | 退出时是否重定向到 IdP 进行 Single Logout（SLO） | `false`                                                             |

4. 点击 **新增**。

创建后，登录选项会显示以下自动生成的 URL：

| URL                 | 用途                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------ |
| **ACS URL**         | `https://<DASHBOARD_URL>/api/saml/<LOGIN_OPTION_ID>/acs`——IdP POST SAML 响应的端点         |
| **SLO URL**         | `https://<DASHBOARD_URL>/api/saml/<LOGIN_OPTION_ID>/slo`——Single Logout 回调端点           |
| **SP Metadata URL** | `https://<DASHBOARD_URL>/api/saml/<LOGIN_OPTION_ID>/metadata`——可导入 IdP 的 SP 元数据 XML |

备注

如果你没有提供自定义证书，API7 会自动生成自签名证书和私钥用于 SAML 请求签名。你也可以在登录选项配置中提供自定义 SP 证书和私钥。

## 第 2 步：配置 IdP[​](#第-2-步配置-idp "第 2 步：配置 IdP的直接链接")

使用第 1 步中的 ACS URL 和 Entity ID，在身份提供商中将 API7 控制台注册为服务提供商。

关于特定 IdP 的详细说明，请参阅下方[提供商专用配置](#provider-specific-configuration)部分。

## 第 3 步：验证 SSO 登录[​](#第-3-步验证-sso-登录 "第 3 步：验证 SSO 登录的直接链接")

1. 退出 API7 控制台。
2. 在登录页，你应看到一个新选项：**使用 {Name} 登录**。
3. 点击该选项，通过 IdP 完成认证。
4. 认证成功后，你会被重定向回控制台。

SSO 用户会出现在 **组织 > 用户** 下。默认情况下，该用户未分配任何角色。

important

在控制台中删除用户会移除其角色和权限边界，但该用户仍可再次作为新用户登录。若要完全撤销访问权限，请从 IdP 中移除该用户。

## 配置角色映射[​](#配置角色映射 "配置角色映射的直接链接")

角色映射会根据 SAML 断言属性自动为 SSO 用户分配 API7 角色。请配置 IdP，使其在 SAML 响应中包含角色相关属性，然后在 API7 中设置映射规则。

信息

自动角色映射优先于手动角色分配。启用映射后，用户下次登录时会覆盖任何手动更改。

### 启用角色映射[​](#启用角色映射 "启用角色映射的直接链接")

1. 在 API7 控制台中，进入 **组织 > 设置**。
2. 选择你的 SAML 登录选项。
3. 启用 **角色映射**。
4. 配置映射规则：

| 字段         | 描述                                                                                 | 示例          |
| ------------ | ------------------------------------------------------------------------------------ | ------------- |
| **内部角色** | 要分配的 API7 角色                                                                   | `Super Admin` |
| **角色属性** | SAML 断言属性名称（`Name` 或 `FriendlyName`，匹配时不区分大小写）                    | `Role`        |
| **操作**     | 比较方式：**精确匹配**、**包含字符串**、**数组中的精确匹配** 或 **数组中包含字符串** | **精确匹配**  |
| **角色值**   | 期望的属性值                                                                         | `admin`       |

5. 点击 **开启**。

### 权限边界映射[​](#权限边界映射 "权限边界映射的直接链接")

权限边界映射的工作方式与角色映射相同，但它将权限策略作为边界分配，而不是附加角色。有关策略和边界的定义，请参阅[权限策略和权限边界](https://docs.apiseven.com/api7-gateway/security-and-compliance/permission-policies-and-boundaries.md)。请在登录选项设置中启用 **权限边界映射**，并使用相同的属性匹配方式配置映射规则。

## 提供商专用配置[​](#provider-specific-configuration "提供商专用配置的直接链接")

### Microsoft Entra ID (Azure AD)[​](#microsoft-entra-id-azure-ad "Microsoft Entra ID (Azure AD)的直接链接")

#### IdP 设置[​](#idp-设置 "IdP 设置的直接链接")

1. 在 [Azure portal](https://portal.azure.com/) 中，进入 **Microsoft Entra ID > Enterprise applications**。

2. 点击 **New application > Create your own application**：

   <!-- -->

   * 输入名称，例如 `API7 Dashboard`。
   * 选择 **Integrate any other application you don't find in the gallery (Non-gallery)**。

3. 在 **Users and groups** 下，添加需要拥有 API7 SSO 访问权限的用户和组。

4. 在 **Single sign-on** 下，选择 **SAML** 并配置：

   <!-- -->

   * **Identifier (Entity ID)**：使用 API7 中的 Entity ID，例如 `https://dashboard.example.com`。
   * **Reply URL (ACS URL)**：使用 API7 中的 ACS URL，例如 `https://dashboard.example.com/api/saml/<LOGIN_OPTION_ID>/acs`。

5. 在 **SAML Signing Certificate** 部分找到 **App Federation Metadata URL**，并将其作为 API7 中的 **Identity Provider Metadata URL**。

#### 属性映射配置[​](#属性映射配置 "属性映射配置的直接链接")

Azure AD 默认使用完整 URI 格式的声明名称：

| API7 字段  | SAML 声明名称                                                        |
| ---------- | -------------------------------------------------------------------- |
| `username` | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`         |
| `email`    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
| `name`     | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`         |

#### 角色映射[​](#角色映射 "角色映射的直接链接")

1. 在 **App roles** 下创建角色，例如 `Admin`。
2. 在 **Enterprise applications > Users and groups** 下，将角色分配给用户。
3. 在 Azure 中，进入 **Single sign-on > Attributes & Claims**，并添加包含已分配角色的声明，例如声明名称 `Role`。
4. 在 API7 中使用映射规则：属性 `Role`，操作 **精确匹配**，值 `Admin`。

### Okta[​](#okta "Okta的直接链接")

#### IdP 设置[​](#idp-设置-1 "IdP 设置的直接链接")

1. 在 [Okta Admin Console](https://admin.okta.com/) 中，进入 **Applications > Applications**。

2. 点击 **Create App Integration** 并选择 **SAML 2.0**。

3. 配置 SAML 设置：

   <!-- -->

   * **Single sign-on URL**：使用 API7 中的 ACS URL，例如 `https://dashboard.example.com/api/saml/<LOGIN_OPTION_ID>/acs`。
   * **Audience URI (SP Entity ID)**：使用 API7 中相同的 Entity ID，例如 `https://dashboard.example.com`。
   * **Name ID format**：`EmailAddress` 或 `Unspecified`。

4. 在 **Attribute Statements** 下配置：

   <!-- -->

   * 将 `username` 映射到 `user.login`。
   * 将 `email` 映射到 `user.email`。
   * 将 `name` 映射到 `user.firstName + " " + user.lastName`。

5. 创建应用后，在 **Sign On** 标签页下找到 **Identity Provider metadata** URL。

6. 在 **Assignments** 标签页下将用户分配给该应用。

#### 属性映射配置[​](#属性映射配置-1 "属性映射配置的直接链接")

| API7 字段  | SAML 属性  |
| ---------- | ---------- |
| `username` | `username` |
| `email`    | `email`    |
| `name`     | `name`     |

#### 角色映射[​](#角色映射-1 "角色映射的直接链接")

1. 在 **Attribute Statements** 下添加 `role` 属性，例如映射到用户资料属性或组成员关系。
2. 在 API7 中使用映射规则：属性 `role`，操作 **精确匹配**，值 `admin`。

## 删除登录选项[​](#删除登录选项 "删除登录选项的直接链接")

注意

删除登录选项会移除与该选项关联的所有控制台用户。

1. 进入 **组织 > 用户**，确认哪些用户与该登录选项关联。
2. 进入 **组织 > 设置**。
3. 在登录选项上点击 **删除**。

备注

必须始终至少保留一个启用状态的登录选项。你不能删除或禁用最后一个仍启用的登录选项。

## 其他资源[​](#其他资源 "其他资源的直接链接")

* [使用 OIDC 配置 SSO](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-oidc.md)
* [使用 LDAP 实现单点登录](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-ldap.md)
* [控制台单点登录](https://docs.apiseven.com/api7-gateway/enterprise-features/dashboard-sso.md)
* [角色与权限策略](https://docs.apiseven.com/api7-gateway/security-and-compliance/role-based-access-control.md)
* [基于角色的访问控制（RBAC）](https://docs.apiseven.com/api7-gateway/security-and-compliance/role-based-access-control.md)
