# 使用 LDAP 实现单点登录

本指南介绍如何使用 LDAP 协议为 API7 控制台配置单点登录（SSO）。OIDC 和 SAML 使用浏览器重定向，而 LDAP 认证会直接将用户凭证从控制台发送至 LDAP 服务器验证。

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

<!-- -->

1. 用户在控制台登录页通过 LDAP 登录选项输入用户名和密码。
2. 控制台使用已配置的 Bind DN（服务账号）连接 LDAP 服务器。
3. 控制台使用 Base DN 和 Identifier 属性搜索用户。
4. 找到用户后，控制台尝试以该用户身份并使用提供的密码进行绑定。
5. 认证成功后，控制台提取用户属性并创建或更新账户。
6. 如果已配置角色和权限边界映射，会在每次登录时应用。

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

开始前，请确保具备：

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

* 兼容 LDAP 的目录服务器（例如 OpenLDAP、Microsoft Active Directory 或 FreeIPA）。

* 对用户目录具有读取/搜索权限的服务账号（Bind DN）。

* 以下信息：

  <!-- -->

  * **Host and Port**：LDAP 服务器地址和端口（LDAP 默认 `389`，LDAPS 默认 `636`）。
  * **Base DN**：用于搜索用户的目录树根节点（例如 `dc=example,dc=com`）。
  * **Bind DN**：服务账号的可分辨名称（例如 `cn=read-only-admin,dc=example,dc=com`）。
  * **Identifier**：与登录用户名共同构成用户 DN 的唯一标识属性（例如 OpenLDAP 的 `uid`、Active Directory 的 `sAMAccountName`）。

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

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

| 字段         | 说明                                             | 示例                                   |
| ------------ | ------------------------------------------------ | -------------------------------------- |
| **名称**     | 登录页显示为“使用 {Name} 登录”的名称             | `Corporate LDAP`                       |
| **提供商**   | 选择 `LDAP`                                      | —                                      |
| **主机名**   | LDAP 服务器主机名或 IP 地址                      | `ldap.example.com`                     |
| **端口**     | LDAP 服务器端口                                  | `389`                                  |
| **Base DN**  | 用户搜索的目录树根节点                           | `dc=example,dc=com`                    |
| **Bind DN**  | 用于 LDAP 搜索的服务账号可分辨名称               | `cn=read-only-admin,dc=example,dc=com` |
| **绑定密码** | Bind DN 服务账号的密码                           | `********`                             |
| **标识符**   | 与登录用户名共同构成用户 DN 的属性               | `uid`                                  |
| **Use SSL**  | 为 LDAP 连接启用 TLS 加密                        | `false`                                |
| **SSL 验证** | 验证 LDAP 服务器 TLS 证书（仅在启用 SSL 时适用） | `true`                                 |
| **超时时间** | 连接超时时间（秒）                               | `10`                                   |
| **属性映射** | 将 LDAP 属性映射至 API7 用户字段                 | 见下文                                 |

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

| API7 字段  | LDAP 属性（OpenLDAP） | LDAP 属性（Active Directory） |
| ---------- | --------------------- | ----------------------------- |
| `username` | `uid`                 | `sAMAccountName`              |
| `email`    | `mail`                | `mail`                        |
| `name`     | `cn`                  | `displayName`                 |

### TLS 配置（可选）[​](#tls-配置可选 "TLS 配置（可选）的直接链接")

对于安全 LDAP 连接（LDAPS），启用 **Use SSL**，并可选择提供：

| 字段           | 说明                                        |
| -------------- | ------------------------------------------- |
| **根 CA 证书** | 用于验证 LDAP 服务器证书的 PEM 编码 CA 证书 |
| **客户端证书** | 用于 mTLS 认证的 PEM 编码客户端证书         |
| **Client Key** | 用于 mTLS 认证的 PEM 编码客户端私钥         |

4. 点击 **新增**。

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

1. 退出 API7 控制台。
2. 在登录页选择 **使用 {Name} 登录** 选项。
3. 输入 LDAP 用户名和密码。
4. 认证成功后，你将登录控制台。

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

important

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

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

角色映射根据目录属性自动为 LDAP 用户分配 API7 角色。这要求 LDAP 用户条目中可提供相关属性。

信息

自动角色映射优先于手动角色分配。映射启用时，用户下次登录会覆盖所有手动修改。

### 第 1 步：配置 LDAP 用户属性[​](#第-1-步配置-ldap-用户属性 "第 1 步：配置 LDAP 用户属性的直接链接")

角色映射依赖 LDAP 用户条目中的属性，常见方法有两种：

#### 用户属性[​](#用户属性 "用户属性的直接链接")

直接为用户分配属性。例如，添加值为 `admin` 的 `title` 属性：

```
dn: uid=alice,dc=example,dc=com

objectClass: inetOrgPerson

uid: alice

cn: Alice Johnson

mail: alice.johnson@example.com

title: admin
```

在 API7 中使用映射规则：属性 `title`，操作 **精确匹配**，值 `admin`。

#### 组成员资格[​](#组成员资格 "组成员资格的直接链接")

将用户加入 LDAP 组，并使用 `memberOf` 属性（OpenLDAP 需启用 `memberOf` overlay）：

```
dn: uid=alice,dc=example,dc=com

objectClass: inetOrgPerson

uid: alice

cn: Alice Johnson

mail: alice.johnson@example.com

memberOf: ou=developers,dc=example,dc=com

memberOf: ou=admins,dc=example,dc=com
```

在 API7 中使用映射规则：属性 `memberOf`，操作 **数组中包含字符串**，值 `admins`。

提示

Active Directory 默认提供 `memberOf`。对于 OpenLDAP，可能需要启用 [memberOf overlay](https://www.openldap.org/doc/admin26/overlays.html#Member%20Of)。

### 第 2 步：在 API7 中启用角色映射[​](#第-2-步在-api7-中启用角色映射 "第 2 步：在 API7 中启用角色映射的直接链接")

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

| 字段         | 说明                                                                                 | 示例          |
| ------------ | ------------------------------------------------------------------------------------ | ------------- |
| **内部角色** | 要分配的 API7 角色                                                                   | `Super Admin` |
| **角色属性** | 要匹配的 LDAP 属性名称                                                               | `title`       |
| **操作**     | 比较方法：**精确匹配**、**包含字符串**、**数组中的精确匹配** 或 **数组中包含字符串** | **精确匹配**  |
| **角色值**   | 期望的属性值                                                                         | `admin`       |

5. 点击 **开启**。

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

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

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

注意

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

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

备注

任何时候都必须至少保留一个已启用的登录选项。你无法删除或禁用最后一个已启用的登录选项。

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

* [使用 OIDC 配置 SSO](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-oidc.md)
* [使用 SAML 配置 SSO](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-saml.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)
