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 属性,否则您无法禁用 LDAP 映射的用户。
4.3.3. 编辑模式
用户和管理员可以通过 帐户控制台和管理员修改用户元数据、用户,并通过管理控制台 修改用户元数据。LDAP 配置页面上的 Edit Mode
配置定义了用户的 LDAP 更新特权。
- READONLY
- 您无法更改用户名、电子邮件、名字、姓氏和其他映射的属性。红帽构建的 Keycloak 会在用户尝试更新这些字段时显示错误。不支持密码更新。
- WRITABLE
- 您可以更改用户名、电子邮件、名字、姓氏和其他映射的属性和密码,并将它们与 LDAP 存储自动同步。
- UNSYNCED
- 红帽构建的 Keycloak 存储了红帽构建的 Keycloak 本地存储中的用户名、电子邮件、名字、姓氏和密码,因此管理员必须将此数据同步回 LDAP。在这个模式中,红帽构建的 Keycloak 部署可以在只读 LDAP 服务器中更新用户元数据。这个选项也适用于将用户从 LDAP 导入到 Keycloak 用户数据库的本地红帽构建。
当红帽构建的 Keycloak 创建 LDAP 供应商时,红帽构建的 Keycloak 还会创建一组初始 LDAP 映射器。红帽构建的 Keycloak 根据 Vendor、Edit Mode 和 Import Users 交换机的组合来配置这些映射程序。例如,当编辑模式是 UNSYNCED 时,红帽构建的 Keycloak 会将映射器配置为从数据库读取特定用户属性,而不是从 LDAP 服务器读取。但是,如果您稍后更改了编辑模式,则映射器的配置不会改变,因为无法检测配置是否在 UNSYNCED 模式中有所变化。决定 创建 LDAP 提供程序时的编辑模式。本文档也适用于 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 SPI 为红帽构建的 Keycloak 配置全局信任存储。有关配置全局信任存储的更多信息,请参阅配置 Truststore 章节。如果您没有配置 Truststore SPI,则信任存储会返回 Java 提供的默认机制,可以是 javax.net.ssl.trustStore
系统属性提供的文件,或者 JDK 中的 cacerts 文件(如果系统属性未设置)。
在 LDAP 联邦提供程序配置中,使用 Truststore SPI
配置属性控制信任存储 SPI。默认情况下,红帽构建的 Keycloak 将属性设为 Always
,这适用于大多数部署。如果将 URL 与 LDAP 的连接 URL 以 ldaps
开始,Red Hat build of Keycloak 将使用 Truststore SPI。
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 提供程序时单击 同步所有用户,然后设置更改用户的定期同步。
4.3.7. LDAP 映射程序
LDAP 映射程序
由 LDAP 提供程序触发。它们为 LDAP 集成提供了另一个扩展点。在以下情况下触发 LDAP 映射程序:
- 用户使用 LDAP 登录。
- 用户最初注册。
- 管理控制台查询用户。
当您创建 LDAP Federation 供应商时,红帽构建的 Keycloak 会自动为 此
供应商提供一组映射程序。这个集合可以被用户更改,用户也可以开发映射程序或更新/删除现有映射程序。
- 用户属性映射程序
-
这个映射程序指定将哪些 LDAP 属性映射到红帽构建的 Keycloak 用户的属性。例如,您可以将
mail
LDAP 属性配置为红帽构建的 Keycloak 数据库中的email
属性。对于此映射程序实现,始终存在一对一的映射。 - fullname 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 属性
。使用这个设置时,红帽构建的 Keycloak 会返回用户名。例如,如果您创建了红帽构建的 Keycloak 用户 "john123",并将 firstName 和 lastName 留空,那么 fullname 映射器会将 "john123" 保存为 LDAP 中的 cn
的值。当您为 firstName 和 lastName 输入 "John Doe" 时,全名称映射程序会将 LDAP cn
更新为 "John Doe" 值,因为回退到用户名是不需要的。
- 硬编码的属性映射程序
-
这个映射程序为与 LDAP 链接的每个红帽构建的 Keycloak 用户添加一个硬编码的属性值。此映射程序也可以强制
启用
或电子邮件用户
属性的值。 - 角色映射程序
-
这个映射程序配置从 LDAP 到红帽构建的 Keycloak 角色映射的角色映射。单个角色映射器可以将 LDAP 角色(通常是从 LDAP 树的特定分支的组)映射到与指定客户端的域角色或客户端角色对应的角色。您可以为同一 LDAP 供应商配置更多角色映射程序。例如,您可以指定从
ou=main,dc=example,dc=org
map 到 realm 角色映射下的组映射到 realm 角色映射,并从ou=39),dc=example,dc=org
下的组映射到客户端 的公共角色映射
。 - 硬编码角色映射程序
- 这个映射程序向来自 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 属性。使用这个映射程序启用始终读值 LDAP
。
将基本红帽构建的 Keycloak 用户属性(如用户名、名名、姓氏和电子邮件)映射到对应的 LDAP 属性的用户属性映射器。您可以扩展它们,并提供自己的额外属性映射。管理控制台提供了有助于配置对应的映射程序的工具。
4.3.8. 密码哈希
当红帽构建的 Keycloak 更新密码时,红帽构建的 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. 故障排除
对于类别 org.keycloak.storage.ldap
,将日志级别增加到 TRACE。使用这个设置时,许多日志消息都会发送到 TRACE
级别的服务器日志,包括记录所有查询到 LDAP 服务器和用于发送查询的参数。在 user forum 或 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 提供程序的属性
连接池
调试级别设置为值all
。这将在带有 LDAP 连接池的日志记录的服务器日志中添加大量额外的消息。这可用于跟踪与连接池或性能相关的问题。
更改连接池配置后,您可能需要重启 Keycloak 服务器来强制重新初始化 LDAP 供应商连接。
如果服务器重启后没有包括更多连接池的消息,这可能表示连接池无法使用您的 LDAP 服务器。
-
对于报告 LDAP 问题的情况,您可能会考虑将 LDAP 树的某些部分与目标数据附加,这会导致您的环境出现问题。例如,如果某些用户登录需要很多时间,您可以考虑附加其 LDAP 条目显示各种"组"条目的
成员属性
计数。在这种情况下,如果这些组条目在红帽构建的 Keycloak 中映射到某些组 LDAP 映射器(或 Role LDAP Mapper)时,添加这些组条目可能很有用。