4.3. 轻量级目录访问协议(LDAP)和 Active Directory

红帽构建的 Keycloak 包括 LDAP/AD 供应商。您可以在一个红帽构建的 Keycloak 域中进行多个不同的 LDAP 服务器，并将 LDAP 用户属性映射到红帽构建的 Keycloak 通用用户模型中。

默认情况下，红帽构建的 Keycloak 会映射用户名、电子邮件、名字和用户帐户姓氏，但您也可以配置额外的映射。红帽构建的 Keycloak 的 LDAP/AD 供应商支持使用 LDAP/AD 协议和存储、编辑和同步模式进行密码验证。

4.3.1. 配置联邦 LDAP 存储

流程

点菜单中的 User Federation。
用户联邦
单击 Add LDAP provider。
红帽构建的 Keycloak 会进入 LDAP 配置页面。

4.3.2. 存储模式

红帽构建的 Keycloak 将用户从 LDAP 导入到红帽 Keycloak 用户数据库的本地构建。用户数据库的这个副本会按需同步，或通过定期后台任务同步。同步密码存在一个例外。红帽构建的 Keycloak 永不导入密码。密码验证总是在 LDAP 服务器上发生。

同步的优点在于，所有红帽构建的 Keycloak 功能都高效工作，因为任何需要的额外用户数据都会存储在本地。缺点是，当红帽构建的 Keycloak 首次查询特定用户时，红帽构建的 Keycloak 都会执行对应的数据库插入。

您可以将导入与 LDAP 服务器同步。当 LDAP 映射器始终从 LDAP 而不是数据库读取特定属性时，导入同步是不必要的。

您可以在红帽构建的 Keycloak 中使用 LDAP，而无需将用户导入到红帽 Keycloak 用户数据库中。LDAP 服务器备份红帽构建的 Keycloak 运行时使用的通用用户模型。如果 LDAP 不支持红帽构建的 Keycloak 功能需要的数据，该功能将无法正常工作。这种方法的优点是，您没有将 LDAP 用户的副本导入并同步到红帽 Keycloak 用户数据库的资源使用情况。

LDAP 配置页面中的 Import Users 开关控制此存储模式。要导入用户，请将此开关切换到 ON。

注意

如果禁用 Import Users，则无法将用户配置集属性保存到红帽构建的 Keycloak 数据库中。另外，除了映射到 LDAP 的用户配置文件元数据外，您无法保存元数据。这个元数据可以包括角色映射、组映射和其他元数据，具体取决于 LDAP 映射器的配置。

当您试图更改非 LDAP 映射用户数据时，无法进行用户更新。例如，除非用户的 启用 标记映射到 LDAP 属性，否则您无法禁用 LDAP 映射的用户。

4.3.3. 编辑模式

用户和管理员可以通过管理控制台修改用户元数据、用户以及管理员。LDAP 配置页面中的 Edit Mode 配置定义了用户的 LDAP 更新特权。

READONLY: 您无法更改用户名、电子邮件、名字、姓氏和其他映射的属性。红帽构建的 Keycloak 会在用户尝试更新这些字段时显示错误。不支持密码更新。
WRITABLE: 您可以更改用户名、电子邮件、名字、姓氏和其他映射的属性和密码，并将它们自动与 LDAP 存储同步。
未同步: 红帽构建的 Keycloak 存储了红帽构建的 Keycloak 本地存储中的用户名、电子邮件、名字、姓氏和密码，因此管理员必须将此数据同步回 LDAP。在这个模式中，红帽构建的 Keycloak 部署可以在只读 LDAP 服务器中更新用户元数据。这个选项也适用于将用户从 LDAP 导入到 Keycloak 用户数据库的本地红帽构建。

注意

当红帽构建的 Keycloak 创建 LDAP 供应商时，红帽构建的 Keycloak 还会创建一组初始 LDAP 映射器。红帽构建的 Keycloak 根据 Vendor、Edit Mode 和 Import Users 交换机的组合来配置这些映射程序。例如，当编辑模式是 UNSYNCED 时，红帽构建的 Keycloak 会将映射器配置为从数据库读取特定用户属性，而不是从 LDAP 服务器读取。但是，如果您稍后更改了编辑模式，则映射器的配置不会改变，因为无法检测 UNSYNCED 模式中的配置更改。在创建 LDAP 提供商时决定 Edit Mode本备注也适用于 Import Users 开关。

4.3.4. 其他配置选项

控制台显示名称: 在管理控制台中显示的供应商名称。
优先级: 查找用户或添加用户时供应商的优先级。
同步注册: 如果您希望红帽构建的 Keycloak 创建的新用户添加到 LDAP，请将此切换切换到 ON。
允许 Kerberos 身份验证: 使用从 LDAP 调配的用户数据，在域中启用 Kerberos/SPNEGO 身份验证。如需更多信息，请参阅 Kerberos 部分。
其他选项: 将鼠标指针悬停在管理控制台中工具提示上，以查看这些选项的更多详细信息。

4.3.5. 通过 SSL 连接到 LDAP

当您配置到 LDAP 存储的安全连接 URL （例如ldaps://myhost.com:636）时，红帽构建的 Keycloak 使用 SSL 与 LDAP 服务器通信。在红帽构建的 Keycloak 服务器端配置信任存储，以便红帽构建的 Keycloak 可以信任到 LDAP 的 SSL 连接 - 请参阅配置 Truststore 章节。

Use Truststore SPI 配置属性已弃用。它通常应保留为 Always。

4.3.6. 将 LDAP 用户同步到红帽构建的 Keycloak

如果您设置了 Import Users 选项，LDAP Provider 会处理将 LDAP 用户导入到红帽 Keycloak 本地数据库的红帽构建中。当用户第一次登录时，或作为用户查询的一部分返回（例如，使用管理控制台中的 search 字段），LDAP 供应商会将 LDAP 用户导入到红帽 Keycloak 数据库的构建中。在身份验证过程中，会验证 LDAP 密码。

如果要将所有 LDAP 用户同步到红帽构建的 Keycloak 数据库，请在 LDAP 供应商配置页面中配置和启用 Sync Settings。

存在两种类型的同步：

定期完全同步: 这个类型将所有 LDAP 用户同步到红帽构建的 Keycloak 数据库。在红帽构建的 Keycloak 中已存在 LDAP 用户，但在 LDAP 中有所不同，直接在红帽构建的 Keycloak 数据库中更新。
定期更改的用户同步: 同步时，红帽构建的 Keycloak 只会创建或更新用户在最后一次同步后创建或更新的用户。

同步的最佳方法是，在第一次创建 LDAP 提供程序时单击 Synchronize all users，然后设置更改的用户定期同步。

4.3.7. LDAP 映射器

LDAP 映射器是由 LDAP 提供程序触发 的监听程序。它们提供 LDAP 集成的另一个扩展点。在以下情况下触发 LDAP 映射器：

用户使用 LDAP 登录。
用户最初注册。
管理控制台查询用户。

当您创建 LDAP Federation 供应商时，红帽构建的 Keycloak 会自动为 此 供应商提供一组映射程序。这个集合可由用户更改，用户也可以开发映射程序或更新/删除现有的映射程序。

用户属性映射程序: 这个映射程序指定将哪些 LDAP 属性映射到红帽构建的 Keycloak 用户的属性。例如，您可以将 mail LDAP 属性配置为红帽构建的 Keycloak 数据库中的 email 属性。对于这个映射程序实现，始终有一个一对一的映射。
fullName Mapper: 这个 mapper 指定用户的全名。红帽构建的 Keycloak 将名称保存在 LDAP 属性中（通常为 cn），并将名称映射到红帽构建的 Keycloak 数据库中的 firstName 和 lastname 属性。使用 cn 包含用户的完整名称对于 LDAP 部署很常见。

注意

当您在红帽构建的 Keycloak 和 Sync Registrations 中为 LDAP 供应商注册新用户时，fullName 映射器允许回退到用户名。在使用 Microsoft Active Directory (MSAD)时，这个回退很有用。MSAD 的常见设置是将 cn LDAP 属性配置为 fullName，同时使用 cn LDAP 属性作为 LDAP 供应商配置中的 RDN LDAP Attribute。使用这个设置时，红帽构建的 Keycloak 会返回用户名。例如，如果您创建了红帽构建的 Keycloak 用户 "john123"，并将 firstName 和 lastName 留空，那么 fullname 映射器会将 "john123" 保存为 LDAP 中的 cn 的值。当您为 firstName 和 lastName 输入 "John Doe" 时，fullname mapper 会将 LDAP cn 更新至 "John Doe" 值，因为回退到用户名是不必要的。

硬编码的属性映射程序: 这个映射程序为与 LDAP 链接的每个红帽构建的 Keycloak 用户添加一个硬编码的属性值。这个映射程序也可以强制为 enabled 或 emailVerified 用户属性强制使用值。
角色映射程序: 这个映射程序配置从 LDAP 到红帽构建的 Keycloak 角色映射的角色映射。单个角色映射器可以将 LDAP 角色（通常是 LDAP 树的特定分支中的组）映射到与指定客户端的域角色或客户端角色对应的角色。您可以为同一 LDAP 供应商配置更多角色映射程序。例如，您可以指定从 ou=main,dc=example,dc=org map 到 realm 角色映射下的组的角色映射，以及 ou=finance,dc=example,dc=org map 到客户端 finance 的客户端角色映射的角色映射。
硬编码的角色映射映射程序: 这个映射程序向来自 LDAP 供应商的每个红帽构建的 Keycloak 用户授予指定的红帽构建的 Keycloak 角色。
组群映射程序: 这个映射程序将 LDAP 组从 LDAP 树的分支映射到红帽构建的 Keycloak 中的组。这个映射程序还会将用户组映射从 LDAP 传播到红帽构建的 Keycloak 中的用户组映射中。
MSAD 用户帐户映射程序: 这个映射程序特定于 Microsoft Active Directory (MSAD)。它可以将 MSAD 用户帐户状态集成到红帽构建的 Keycloak 帐户状态，如启用的帐户或过期密码。这个映射程序使用 userAccountControl、和 pwdLastSet LDAP 属性，特定于 MSAD，不是 LDAP 标准。例如，如果 pwdLastSet 的值为 0， 则红帽构建的 Keycloak 用户必须更新其密码。结果是添加到用户的 UPDATE_PASSWORD 所需的操作。如果 userAccountControl 的值为 514 （禁用帐户），则禁用 Keycloak 用户的红帽构建。
证书映射程序: 这个映射器映射 X.509 证书。红帽构建的 Keycloak 将其与 X.509 身份验证和完整证书结合使用，以 PEM 格式 作为身份源。这个映射程序的行为与 User Attribute Mapper 类似，但红帽构建的 Keycloak 可以过滤存储 PEM 或 DER 格式的证书的 LDAP 属性。使用这个 映射程序启用 Always Read Value from LDAP。

将基本红帽构建的 Keycloak 用户属性（如用户名、名名、姓氏和电子邮件）映射到对应的 LDAP 属性的用户属性映射器。您可以扩展它们，并提供自己的额外属性映射。管理控制台提供了工具提示，以帮助配置对应的映射程序。

4.3.8. 密码散列

当红帽构建的 Keycloak 更新密码时，红帽构建的 Keycloak 以纯文本格式发送密码。此操作与更新内置红帽构建的 Keycloak 数据库中的密码不同，红帽构建的 Keycloak 哈希和 salt 密码会将其发送到数据库。对于 LDAP，红帽构建的 Keycloak 依赖于 LDAP 服务器来哈希和 salt 密码。

默认情况下，LDAP 服务器（如 MSAD、RHDS 或 FreeIPA 哈希）和 salt 密码。其他 OpenLDAP 或 ApacheDS 等 LDAP 服务器以纯文本形式存储密码，除非您使用 LDAPv3 密码修改扩展操作，如 RFC3062 所述。在 LDAP 配置页面中启用 LDAPv3 密码修改扩展操作。详情请查看 LDAP 服务器文档。

警告

使用 ldapsearch 和 base64 解码 userPassword 属性值，始终通过检查更改的目录条目来验证用户密码是否被正确哈希，而不是以纯文本形式存储。

4.3.9. 故障排除

对于 org.keycloak.storage.ldap 类别，可以将日志级别增加到 TRACE。使用此设置时，许多日志记录消息都会发送到 TRACE 级别中的服务器日志，包括所有查询的日志记录到 LDAP 服务器以及用于发送查询的参数。在用户论坛或 JIRA 上创建任何 LDAP 问题时，请考虑使用启用的 TRACE 日志记录附加服务器日志。如果太大，良好的替代方案是将来自服务器日志的代码片段仅包含包含消息（在操作过程中添加到日志中），这会导致您出现问题。

当您创建 LDAP 供应商时，从以下位置开始，服务器日志中会出现一条信息：

Creating new LDAP Store for the LDAP storage provider: ...

它显示了您的 LDAP 供应商的配置。在询问问题或报告错误之前，最好包含此消息来显示您的 LDAP 配置。最终，可以用一些占位符值替换您不希望包含的一些配置更改。一个例子是 bindDn=some-placeholder。对于 connectionUrl，也可以自由替换它，但通常情况下包括使用的协议(ldap 和 ldaps)会很有用。同样，包含 LDAP 映射器配置的详情，这在 DEBUG 级别会显示如下信息：

Mapper for provider: XXX, Mapper name: YYY, Provider: ZZZ ...

请注意，这些消息仅显示启用了 DEBUG 日志记录。

要跟踪性能或连接池问题，请考虑将 LDAP 提供程序的属性 Connection Pool Debug Level 的值设置为值 all。这将通过包含的日志记录为 LDAP 连接池添加大量其他消息到服务器日志中。这可用于跟踪与连接池或性能相关的问题。

注意

更改连接池配置后，您可能需要重启红帽构建的 Keycloak 服务器，以强制实施 LDAP 供应商连接的重新初始化。

如果服务器重启后没有显示连接池的消息，这可能表示连接池无法用于您的 LDAP 服务器。

对于报告 LDAP 问题的情况，您可以考虑将部分 LDAP 树与目标数据附加，这会导致您的环境出现问题。例如，如果某些用户的登录需要很多时间，您可以考虑显示各种"group"条目的 成员属性 计数的 LDAP 条目。在这种情况下，如果这些组条目在红帽构建的 Keycloak 中映射到某些组 LDAP 映射器（或 Role LDAP Mapper）等，则添加这些组条目可能很有用。