4.3. 轻量级目录访问协议(LDAP)和 Active Directory
红帽单点登录包括 LDAP/AD 供应商。您可以在一个 Red Hat Single Sign-On realm 中联合多个不同的 LDAP 服务器，并将 LDAP 用户属性映射到 Red Hat Single Sign-On 通用用户模型中。
默认情况下，红帽单点登录映射用户帐户的用户名、电子邮件、名字和姓氏，但您也可以配置其他 映射。Red Hat Single Sign-On 的 LDAP/AD 供应商支持使用 LDAP/AD 协议和存储、编辑和同步模式验证密码验证。
4.3.1. 配置联合 LDAP 存储
流程
点菜单中的 User Federation。
用户联合
- 从 Add Provider 列表中选择 ldap。Red Hat Single Sign-On 为您提供了 LDAP 配置页面。
4.3.2. 存储模式
Red Hat Single Sign-On 将用户从 LDAP 导入到本地 Red Hat Single Sign-On 用户数据库。这个用户数据库的副本会按需同步，或者通过定期后台任务同步。同步密码存在异常。Red Hat Single Sign-On 不会导入密码。密码验证始终出现在 LDAP 服务器上。
同步的优点在于，所有红帽单点登录功能都高效工作，因为任何需要的额外用户数据都存储在本地。缺点是，每次 Red Hat Single Sign-On 首次查询特定用户时，Red Hat Sign-On 都会执行对应的数据库插入。
您可以将导入与 LDAP 服务器同步。当 LDAP 映射总是从 LDAP 而不是数据库读取特定属性时，导入同步是不必要的。
您可以将 LDAP 与 Red Hat Single Sign-On 一起使用，无需将用户导入到 Red Hat Single Sign-On 用户数据库中。LDAP 服务器备份 Red Hat Single Sign-On 运行时使用的通用用户模型。如果 LDAP 不支持 Red Hat Single Sign-On 功能需要的数据，则该功能将无法正常工作。这种方法的优势在于，您不能将 LDAP 用户副本导入和同步至 Red Hat Single Sign-On 用户数据库中的资源使用。
在 LDAP 配置页面中的 Import Users 切换会控制这个存储模式。要导入用户，请将此开关切换到 ON。
如果您禁用 Import Users，则无法将用户配置集属性保存到 Red Hat Single Sign-On 数据库中。另外，除了映射到 LDAP 的用户配置集元数据外，您无法保存元数据。这个元数据可以根据 LDAP 映射、映射程序和其他元数据包含角色映射、组映射和其他元数据。
当您试图更改非LDAP 映射的用户数据时，无法更新用户更新。例如，除非用户的 已启用 标记映射到 LDAP 属性，否则您无法禁用 LDAP 映射用户。
4.3.3. 编辑模式
用户和管理员可以通过 帐户控制台和管理员修改用户元数据、用户，并通过管理控制台 修改用户元数据。LDAP 配置页面中的 Edit Mode 配置定义了用户的 LDAP 更新权限。
- READONLY
- 您不能更改用户名、电子邮件、名字、姓氏和其他映射的属性。Red Hat Single Sign-On 向用户尝试更新这些字段时显示错误。不支持密码更新。
- 可写
- 您可以更改用户名、电子邮件、名字、姓氏和其他映射的属性和密码，并将它们与 LDAP 存储自动同步。
- UNSYNCED
- Red Hat Single Sign-On 存储了对 Red Hat Single Sign-On 本地存储的用户名、电子邮件、姓氏和密码的更改，因此管理员必须将此数据同步回 LDAP。在这个模式中，Red Hat Single Sign-On 部署可以更新只读 LDAP 服务器上的用户元数据。当将用户从 LDAP 导入到本地 Red Hat Single Sign-On 用户数据库时，此选项也适用。
当 Red Hat Single Sign-On 创建 LDAP 提供程序时，红帽单点登录还会创建一组初始 LDAP 映射程序。Red Hat Single Sign-On 根据 Vendor, Edit Mode, and Import Users 的组合来配置这些映射程序。例如，在编辑模式为 UNSYNCED 时，Red Hat Single Sign-On 会将映射程序配置为从数据库读取特定用户属性，而不是从 LDAP 服务器中读取特定用户属性。但是，如果您稍后更改了编辑模式，则映射程序的配置不会改变，因为无法检测到 UNSYNCED 模式的配置是否已更改。在创建 LDAP 提供商时决定 Edit Mode此备注也适用于 Import Users 交换机。
4.3.4. 其他配置选项
- 控制台显示名称
- 要在 admin 控制台中显示的供应商名称。
- 优先级
- 查找用户或添加用户时的供应商的优先级。
- 同步注册
- 如果您希望由 Red Hat Single Sign-On 创建的新用户切换为 ON。
- 允许 Kerberos 身份验证
- 使用从 LDAP 置备的用户数据在域中启用 Kerberos/SPNEGO 身份验证。如需更多信息，请参阅 Kerberos 部分。
- 其他选项
- 将鼠标指针悬停在 Admin Console 中的工具提示上，以查看有关这些选项的更多详情。
4.3.5. 通过 SSL 连接到 LDAP
当您为 LDAP 存储配置安全连接 URL （例如ldaps://myhost.com:636）时，Red Hat Single Sign-On 使用 SSL 与 LDAP 服务器通信。在 Red Hat Single Sign-On 服务器端配置信任存储，以便 Red Hat Single Sign-On 可以信任到 LDAP 的 SSL 连接。
使用 Truststore SPI 为 Red Hat Single Sign-On 配置全局信任存储。有关配置全局信任存储的更多信息，请参阅 服务器安装和配置指南。如果您没有配置 Truststore SPI，则信任存储会回退到 Java 提供的默认机制，后者可以是 javax.net.ssl.trustStore 系统属性提供的文件，或者 JDK 中的 cacerts 文件（如果设置系统属性）。
使用 Truststore SPI 配置属性在 LDAP 联合供应商配置中，控制信任存储 SPI。默认情况下，Red Hat Single Sign-On 会将 属性设置为 仅适用于 ldaps，这对于大多数部署来说是足够的。如果连接到 LDAP 的连接 URL 仅以 ldaps 开始，Red Hat Single Sign-On 使用 Truststore SPI。
4.3.6. 将 LDAP 用户同步到红帽单点登录
如果您设置了 Import Users 选项，LDAP 提供程序将 LDAP 用户导入到 Red Hat Single Sign-On local 数据库中。当用户第一次登录时，LDAP 供应商将 LDAP 用户导入到 Red Hat Single Sign-On 数据库并验证 LDAP 密码。当用户第一次登录时，用户才是 Red Hat Single Sign-On 导入用户的唯一时间。如果单击 Admin Console 中的 Users 菜单并点击 View all users 按钮，则您只看到红帽单点登录至少验证的 LDAP 用户。Red Hat Single Sign-On 以这种方式导入用户，因此此操作不会触发整个 LDAP 用户数据库的导入。
如果要将所有 LDAP 用户同步到 Red Hat Single Sign-On 数据库，在 LDAP 提供程序配置页面中配置和启用 Sync Settings。
存在两种类型的同步：
- 定期完全同步
- 此类型将所有 LDAP 用户同步到 Red Hat Single Sign-On 数据库中。已存在于 Red Hat Single Sign-On 的 LDAP 用户，但在 LDAP 中有所不同，直接更新 Red Hat Sign-On 数据库中。
- 定期更改的用户同步
- 同步时，Red Hat Single Sign-On 会在最近一次同步后创建或更新用户。
您第一次创建 LDAP 供应商时，最好单击 Synchronize all 用户，然后设置更改用户的定期同步。
4.3.7. LDAP 映射器
LDAP 映射器是由 LDAP 提供程序触发 的监听程序。它们为 LDAP 集成提供了另一个扩展点。当以下情况时触发 LDAP 映射：
- 用户使用 LDAP 登录。
- 用户最初注册。
- Admin Console 查询用户。
当您创建 LDAP Federation 提供者时，Red Hat Single Sign-On 会自动为此提供程序提供一组 映射程序。用户可以更改此设置，也可以开发映射程序或更新/删除现有的项。
- 用户属性映射程序
-
此映射程序指定了哪些 LDAP 属性映射到 Red Hat Single Sign-On 用户的 属性。例如，您可以将
mailLDAP 属性配置为 Red Hat Single Sign-On 数据库中的电子邮件属性。对于这一映射程序实施，始终存在一对一的映射。 - FullName Mapper
-
此映射程序指定用户的全名。Red Hat Single Sign-On 将名称保存在 LDAP 属性中（通常为
cn），并将名称映射到 Red Hat Single Sign-On 数据库中的firstName和lastname属性。在 LDAP 部署中，使用cn使其包含用户的全名是通用的。
当您在 Red Hat Single Sign-On 和 Sync Registrations 中注册新用户时，对于 LDAP 供应商而言，fullName mapper 将允许回退到用户名。在使用 Microsoft Active Directory (MSAD)时，这个回退很有用。MSAD 的常见设置是将 cn LDAP 属性配置为 fullName，同时将 cn LDAP 属性用作 LDAP 提供程序配置中 RDN LDAP 属性。通过这个设置，Red Hat Single Sign-On 会回退到用户名。例如，如果您创建 Red Hat Single Sign-On 用户 "john123" 并保留 firstName 和 lastName 空，则 fullname mapper 会将 "john123" 保存为 LDAP 中的 cn 的值。当您为 firstName 和 lastName 输入 "John Doe" 时，全name mapper 会更新 LDAP cn 到 "John Doe" 值，因为回退到用户名是不必要的。
- 硬编码属性映射
-
此映射程序为与 LDAP 链接的每个 Red Hat Single Sign-On 用户添加了一个硬编码的属性值。此映射程序还可以强制
启用或电子邮件用户属性的值。 - 角色映射程序
-
这个映射程序配置从 LDAP 到 Red Hat Single Sign-On 角色映射的角色映射。单个角色映射映射 LDAP 角色（通常是来自 LDAP 树的特定分支的组）到与指定客户端的域角色或客户端角色对应的角色。您可以为同一 LDAP 供应商配置更多角色映射程序。例如，您可以指定
ou=main,dc=example,dc=orgmap 下的组到 realm 角色映射，以及来自ou=finance,dc=example,dc=org下的组的角色映射。 - 硬编码的角色映射程序
- 此映射程序为来自 LDAP 提供商的每个 Red Hat Single Sign-On 用户授予指定的红帽单点登录角色。
- 组群映射程序
- 此映射程序将 LDAP 组从 LDAP 树分支映射到 Red Hat Single Sign-On 中的组。此映射还会将用户组映射从 LDAP 传播到 Red Hat Single Sign-On 中的 user-group 映射。
- MSAD 用户帐户映射程序
-
此映射程序专用于 Microsoft Active Directory (MSAD)。它可以将 MSAD 用户帐户状态集成到 Red Hat Single Sign-On 帐户状态，如启用帐户或过期密码。这个映射程序使用
userAccountControl、pwdLastSetLDAP 属性（特定于 MSAD），且不是 LDAP 标准。例如，如果pwdLastSet的值为0，Red Hat Single Sign-On 用户必须更新其密码。其结果是添加至用户的 UPDATE_PASSWORD 必需操作。如果userAccountControl的值为514（禁用帐户），则代表红帽单点登录用户被禁用。 - 证书映射程序
-
这个映射映射 X.509 证书。Red Hat Single Sign-On 与其与 X.509 身份验证和完整
证书结合使用，采用 PEM 格式作为身份源。此映射的行为与用户属性映射程序类似，但红帽单点登录可以过滤存储 PEM 或 DER 格式的 LDAP 属性。启用Always Read Value from LDAPwith this mapper.
将基本红帽单点登录用户属性（如用户名、名字、姓氏和电子邮件）映射到对应的 LDAP 属性的用户属性。您可以扩展这些属性并提供自己的额外属性映射。Admin Console 提供工具提示，可帮助配置对应的映射程序。
4.3.8. 密码散列
当 Red Hat Single Sign-On 更新密码时，Red Hat Single Sign-On 以纯文本格式发送密码。此操作与更新内置 Red Hat Single Sign-On 数据库中的密码不同，其中 Red Hat Single Sign-On 哈希和 salt 在将密码发送到数据库之前。对于 LDAP，Red Hat Single Sign-On 依赖于 LDAP 服务器来哈希和 salt 密码。
默认情况下，LDAP 服务器（如 MSAD、RHDS 或 FreeIPA 哈希）和 salt 密码。其他 LDAP 服务器（如 OpenLDAP 或 ApacheDS）会以纯文本形式存储密码，除非您使用 LDAPv3 Password Modify Extended Operation，如 RFC3062 所述。在 LDAP 配置页面中启用 LDAPv3 Password Modify Extended Operation。如需了解更多详细信息，请参阅您的 LDAP 服务器文档。
始终通过在使用 ldapsearch 和 base64 解码 userPassword 属性值来检查更改的目录条目，来验证用户密码是否正确进行哈希存储，而不是以明文形式存储。
4.3.9. 故障排除
将类别 org.keycloak.storage.ldap 的日志级别增加到 TRACE。通过这个设置，许多日志消息发送到 TRACE 级别中的服务器日志，包括所有对 LDAP 服务器和参数（用于发送查询）的日志记录。当您在用户论坛或 JIRA 上创建任何 LDAP 问题时，请考虑将服务器日志与已启用 TRACE 日志记录连接。如果情况太大，则好的替代方案是将服务器日志中的代码片段包含在操作期间添加到日志中，这会导致问题所在。
创建 LDAP 供应商时，服务器日志中会出现从以下内容开始的信息：
When you create LDAP provider, message appear in the server log in the INFO level starting with:
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 日志记录。
-
要跟踪性能或连接池问题，请考虑设置属性
Pool Debug Level的值。
为跟踪性能或连接池问题，请考虑将 LDAP 提供商 的属性 Pool Debug Level 的值设置为 all。这将添加很多额外的信息，以便记录 LDAP 连接池包含的日志。这可用于跟踪与连接池或性能相关的问题。
更改连接池的配置后，您可能需要重启 Keycloak 服务器，以强制重新初始化 LDAP 供应商连接。
如果即使服务器重启后没有更多消息用于连接池，这可能表示连接池无法用于您的 LDAP 服务器。
-
如需报告 LDAP 问题，您可能会考虑为目标数据附加部分 LDAP 树，这会导致您的环境出现问题。例如，如果某些用户登录时需要很多时间，您可以考虑附加显示各种"group"条目
的成员属性计数的 LDAP 条目。在这种情况下，如果这些组条目映射到 Red Hat Single Sign-On 等某些组 LDAP 映射（或角色 LDAP 映射程序）时，添加可能很有用。
如需报告 LDAP 问题，您可能会考虑为目标数据附加部分 LDAP 树，这会导致您的环境出现问题。例如，如果某些用户登录时需要很多时间，您可以考虑附加显示各种"group"条目 的成员 属性计数的 LDAP 条目。在这种情况下，如果这些组条目映射到 Red Hat Single Sign-On 中的一些组 LDAP 映射（或角色 LDAP 映射程序），那么添加可能很有用。
