跳到主要内容
版本：3.10.x

使用 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. 在 API7 控制台中，进入 Organization > Settings。
  2. 点击 Add Login Option。
  3. 填写配置：
字段说明示例
Name登录页显示为“Login with {Name}”的名称Corporate LDAP
Provider选择 LDAP—
HostLDAP 服务器主机名或 IP 地址ldap.example.com
PortLDAP 服务器端口389
Base DN用户搜索的目录树根节点dc=example,dc=com
Bind DN用于 LDAP 搜索的服务账号可分辨名称cn=read-only-admin,dc=example,dc=com
Bind PasswordBind DN 服务账号的密码********
Identifier与登录用户名共同构成用户 DN 的属性uid
Use SSL为 LDAP 连接启用 TLS 加密false
SSL Verify验证 LDAP 服务器 TLS 证书（仅在启用 SSL 时适用）true
Timeout连接超时时间（秒）10
Attributes Mapping将 LDAP 属性映射至 API7 用户字段见下文

属性映射​

API7 字段LDAP 属性（OpenLDAP）LDAP 属性（Active Directory）
usernameuidsAMAccountName
emailmailmail
namecndisplayName

TLS 配置（可选）​

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

字段说明
Root CA Certificate用于验证 LDAP 服务器证书的 PEM 编码 CA 证书
Client Certificate用于 mTLS 认证的 PEM 编码客户端证书
Client Key用于 mTLS 认证的 PEM 编码客户端私钥
  1. 点击 Add。

第 2 步：验证 SSO 登录​

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

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

important

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

配置角色映射​

角色映射根据目录属性自动为 LDAP 用户分配 API7 角色。这要求 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，操作 Exact Match，值 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=admins,dc=example,dc=com

在 API7 中使用映射规则：属性 memberOf，操作 Contains String，值 admins。

提示

Active Directory 默认提供 memberOf。对于 OpenLDAP，可能需要启用 memberOf overlay。

第 2 步：在 API7 中启用角色映射​

  1. 在 API7 控制台中，进入 Organization > Settings。
  2. 选择 LDAP 登录选项。
  3. 启用 Role Mapping。
  4. 配置映射规则：
字段说明示例
Internal Role要分配的 API7 角色Super Admin
Role Attribute要匹配的 LDAP 属性名称title
Operation比较方法：Exact Match、Contains String、Exact Match in Array 或 Contains String in ArrayExact Match
Role Value期望的属性值admin
  1. 点击 Enable。

权限边界映射​

权限边界映射与角色映射的工作方式相同，但它将权限策略作为边界分配，而非附加角色。有关策略和边界的定义，请参阅权限策略和权限边界。在登录选项设置中启用 Permission Boundary Mapping，并采用相同的属性匹配方式配置映射规则。

删除登录选项​

注意

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

  1. 进入 Organization > Users，确认与该登录选项关联的用户。
  2. 进入 Organization > Settings。
  3. 在登录选项上点击 Delete。
备注

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

其他资源​