4.3. 轻量级目录访问协议(LDAP)和 Active Directory
红帽构建的 Keycloak 包括 LDAP/AD 供应商。您可以在一个红帽构建的 Keycloak 域中联合多个不同的 LDAP 服务器，并将 LDAP 用户属性映射到红帽构建的 Keycloak 通用用户模型中。
默认情况下，Red Hat build of 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
- 您无法更改用户名、电子邮件、名字、姓氏和其他映射的属性。Red Hat build of Keycloak 会显示用户尝试更新这些字段时的错误。不支持密码更新。
- WRITABLE
- 您可以更改用户名、电子邮件、名字、姓氏和其他映射的属性和密码，并将它们与 LDAP 存储自动同步。
- 未同步
- Red Hat build of Keycloak 将更改存储在红帽构建的 Keycloak 本地存储中的用户名、电子邮件、姓氏、姓氏和密码，因此管理员必须将此数据同步回 LDAP。在这个模式中，红帽构建的 Keycloak 部署可以在只读 LDAP 服务器上更新用户元数据。当将 LDAP 中的用户导入到本地红帽构建的 Keycloak 用户数据库时，也会应用这个选项。
当红帽构建的 Keycloak 创建 LDAP 供应商时，红帽构建的 Keycloak 也会创建一组初始 LDAP 映射程序。红帽构建的 Keycloak 根据 供应商、编辑模式 和 导入用户 交换机的组合配置这些映射程序。例如，当编辑模式为 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 本地数据库中。当用户首次登录时，或作为用户查询的一部分返回（例如，使用 admin 控制台中的 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 用户的属性。例如，您可以将
mailLDAP 属性配置为红帽构建的 Keycloak 数据库中email属性。对于此映射程序实施，一对一映射始终存在。 - fullName Mapper
-
此映射程序指定用户全名。Red Hat build of Keycloak 将名称保存在 LDAP 属性中（通常为
cn），并将名称映射到红帽构建的 Keycloak 数据库中的firstName和lastname属性。使cn包含用户的完整名称对于 LDAP 部署是通用的。
当您为 LDAP 供应商注册红帽构建的 Keycloak 和 Sync Registrations 为 ON 时，fullName 映射程序允许回退到用户名。使用 Microsoft Active Directory (MSAD)时，这个回退很有用。MSAD 的常见设置是将 cn LDAP 属性配置为 fullName，同时将 cn LDAP 属性用作 LDAP 供应商配置中 RDN LDAP Attribute。在这个版本中，红帽构建的 Keycloak 会返回用户名。例如，如果您创建红帽构建的 Keycloak 用户 "john123" 并将 firstName 和 lastName 留空，则 fullname mapper 会将 "john123" 保存为 LDAP 中 cn 的值。当您为 firstName 和 lastName 输入 "John Doe" 时，fullname mapper 会将 LDAP cn 更新为 "John Doe" 值，因为不需要回退到用户名。
- 硬编码属性映射程序
-
这个映射程序为每个与 LDAP 链接的 Keycloak 用户构建添加了一个硬编码属性值。此映射器也可以强制为
启用或电子邮件的用户属性强制值。 - 角色映射程序
-
这个映射程序将角色映射从 LDAP 配置为红帽构建的 Keycloak 角色映射。单个角色映射器可以将 LDAP 角色（通常是从 LDAP 树的特定分支的组）映射到与指定客户端的域角色或客户端角色对应的角色中。您可以为同一 LDAP 供应商配置更多角色映射程序。例如，您可以指定
ou=main,dc=example,dc=org下的组的角色映射，映射到 realm 角色映射，以及ou=finance,dc=example,dc=org下的组的角色映射，映射到客户端finance的客户端角色映射。 - 硬编码角色映射程序
- 这个映射程序为来自 LDAP 供应商的每个红帽构建的 Keycloak 用户授予指定的红帽构建的 Keycloak 角色。
- 组映射程序
- 这个映射程序将 LDAP 组从 LDAP 树分支映射到红帽构建的 Keycloak 中的组。这个映射程序也会将用户组映射从 LDAP 传播到红帽构建的 Keycloak 中的用户组映射。
- MSAD 用户帐户映射程序
-
这个映射程序特定于 Microsoft Active Directory (MSAD)。它可以将 MSAD 用户帐户状态集成到红帽构建的 Keycloak 帐户状态中，如启用的帐户或过期密码。此映射程序使用
userAccountControl，以及pwdLastSetLDAP 属性，特定于 MSAD，不是 LDAP 标准。例如，如果pwdLastSet的值为 0，则红帽构建的 Keycloak 用户必须更新其密码。结果是添加到用户的 UPDATE_PASSWORD 所需操作。如果userAccountControl的值为514（禁用帐户），则禁用红帽 Keycloak 用户的构建。 - 证书映射程序
-
这个映射程序映射 X.509 证书。Red Hat build of Keycloak 将其与 X.509 身份验证一起使用，使用
PEM 格式的完整证书作为身份源。这个映射程序的行为与User Attribute Mapper类似，但红帽构建的 Keycloak 可以过滤存储 PEM 或 DER 格式的 LDAP 属性。使用这个映射程序从 LDAP 启用 Read Value。
将 Keycloak 用户属性的基本红帽构建的用户属性（如 username、firstname、lastname、lastname 和 email）映射到对应的 LDAP 属性。您可以扩展它们，并提供自己的附加属性映射。Admin Console 提供了工具提示，可帮助配置对应的映射程序。
4.3.8. 密码哈希
当红帽构建的 Keycloak 更新密码时，Red Hat build of Keycloak 会以纯文本格式发送密码。此操作与更新内置红帽 Keycloak 数据库的密码不同，其中红帽构建的 Keycloak 哈希和 salt 在将其发送到数据库前。对于 LDAP，红帽构建的 Keycloak 依赖于 LDAP 服务器来哈希和 salt 密码。
默认情况下，LDAP 服务器，如 MSAD、RHDS 或 FreeIPA 哈希和 salt 密码。其他 LDAP 服务器（如 OpenLDAP 或 ApacheDS）将密码以纯文本形式保存，除非您使用 LDAPv3 密码修改扩展操作，如 RFC3062 所述。在 LDAP 配置页面中启用 LDAPv3 密码修改扩展操作。如需了解更多详细信息，请参阅 LDAP 服务器的文档。
使用 ldapsearch 和 base64 解码 userPassword 属性值，始终验证用户密码是否已正确散列化，而不会以纯文本形式存储。
4.3.9. 配置连接池
要在管理 LDAP 连接并处理多个连接时提高性能，您可以启用连接池。通过这样做，当连接关闭时，它将返回到池以备将来使用，从而减少了创建新连接的成本。
LDAP 连接池配置使用以下系统属性进行配置：
| Name | 描述 |
|---|---|
|
| 可共用的空格分隔验证类型的身份验证类型。有效类型包括 "none", "simple", 和 "DIGEST-MD5" |
|
| 整数表示在最初为身份创建连接时要创建的每个连接身份的连接数的字符串 |
|
| 代表可同时维护的每个连接身份的最大连接数的整数表示 |
|
| 代表应同时维护的每个连接身份的首选连接数的整数字符串 |
|
| 代表闲置连接可能保留在池中的毫秒数的字符串代表，而不会关闭并从池中移除。 |
|
| 可共用的空格分隔协议协议类型的列表。有效类型是 "plain" 和 "ssl" |
|
| 指示要生成的调试输出级别的字符串。有效值为 "fine" （追踪连接创建和删除）和"all" （所有调试信息） |
如需了解更多详细信息，请参阅 Java LDAP 连接池配置 文档。
要设置这些属性，您可以设置 JAVA_OPTS_APPEND 环境变量：
export JAVA_OPTS_APPEND=-Dcom.sun.jndi.ldap.connect.pool.initsize=10 -Dcom.sun.jndi.ldap.connect.pool.maxsize=50
4.3.10. 故障排除
将类别 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 mappers 配置详情会很有用，这在 DEBUG 级别中会显示如下信息：
Mapper for provider: XXX, Mapper name: YYY, Provider: ZZZ ...
请注意，这些消息仅显示启用的 DEBUG 日志记录。
-
要跟踪性能或连接池问题，请考虑将 property
com.sun.jndi.ldap.connect.pool.debug的值设置为all。此更改向服务器日志添加许多其他消息，其中包含用于 LDAP 连接池的日志记录。因此，您可以跟踪与连接池或性能相关的问题。如需了解更多详细信息 ，请参阅配置连接池。
更改连接池配置后，您可能需要重启红帽构建的 Keycloak 服务器来强制实施 LDAP 供应商连接的重新初始化。
如果服务器重启后没有更多用于连接池的消息，这可能表明连接池无法用于 LDAP 服务器。
-
对于报告 LDAP 问题，您可以考虑将 LDAP 树的某些部分与目标数据一起附加，这会导致您的环境出现问题。例如，如果登录某些用户需要大量时间，您可以考虑附加他的 LDAP 条目，显示各种"group"条目的
成员属性计数。在这种情况下，如果这些组条目被映射到红帽构建的 Keycloak 中的某个组 LDAP 映射器（或 Role LDAP Mapper），则添加可能会很有用。
