#配置 LDAP / Active Directory 联合

本指南将引导你在 Keycloak 中设置 LDAP 或 Microsoft Active Directory 用户联合，使企业目录中的用户无需迁移凭证即可进行身份验证。

有关背景概念，请参阅 身份联合。

#先决条件

• 一个正在运行且具备管理员访问权限的 Keycloak 实例。
• 从 Keycloak Pods 到 LDAP/AD 服务器的网络连通性。
• 一个 LDAP bind 账户，具有对用户目录的读取权限（如果使用 WRITABLE 编辑模式，则还需要写入权限）。
• 适用于你的目录结构的 LDAP base DN 和用户搜索过滤器。

#步骤 1：添加 LDAP 提供程序

1. 在 Admin Console 中，选择目标 Realm。
2. 在左侧导航栏中进入 User federation。
3. 单击 Add LDAP provider。
4. 配置连接设置：

5. 单击 Test connection 以验证连通性。
6. 单击 Test authentication 以验证 bind 凭证。

#步骤 2：配置用户搜索

#编辑模式

#步骤 3：配置同步

同步会将 LDAP 中的用户数据导入到 Keycloak 的本地缓存中，以便更快地查找。

单击 Save，然后单击 Synchronize all users 执行初始导入。

前往 Users 并搜索 LDAP 用户，以验证导入是否成功。

#步骤 4：配置 LDAP Mapper

LDAP Mapper 定义了 LDAP 属性如何映射到 Keycloak 用户属性、组和角色。

#默认 Mapper

创建 LDAP 提供程序时，Keycloak 会自动创建多个默认 Mapper。请在 Mappers 选项卡中查看它们：

#添加组 Mapper

要将 LDAP 组同步到 Keycloak 组：

1. 在 LDAP provider 详情中，单击 Mappers 选项卡。
2. 单击 Add mapper。
3. 选择 group-ldap-mapper。
4. 配置：

5. 单击 Save，然后单击 Sync LDAP groups to Keycloak。

#添加角色 Mapper

要将 LDAP 组直接映射到 Keycloak Realm 角色：

1. 单击 Add mapper > role-ldap-mapper。
2. 配置 LDAP roles DN、role object classes 和 membership attributes（与 group mapper 类似）。
3. 将 Use Realm Roles Mapping 设置为 On。
4. 单击 Save 并同步。

#步骤 5：配置通过 TLS 的 LDAP

对于生产环境，请始终使用加密的 LDAP 连接。

#选项 A：LDAPS（推荐）

在 Connection URL 中使用 ldaps://（端口 636）：

ldaps://ldap.example.com:636

如果 LDAP 服务器使用由自定义 CA 签名的证书，请将 CA 证书导入 Keycloak truststore。在 Kubernetes 管理的部署中，挂载 CA 证书，并通过 Keycloak CR 配置 JVM truststore：

spec:
  additionalOptions:
    - name: spi-truststore-file-file
      value: /opt/keycloak/certs/truststore.jks
    - name: spi-truststore-file-password
      secret:
        name: keycloak-truststore-secret
        key: password
  unsupported:
    podTemplate:
      spec:
        containers:
          - volumeMounts:
              - name: truststore
                mountPath: /opt/keycloak/certs
        volumes:
          - name: truststore
            secret:
              secretName: keycloak-truststore

#选项 B：StartTLS

使用启用了 StartTLS 的 ldap://（端口 389）：

ldap://ldap.example.com:389

在 LDAP provider 配置中启用 StartTLS。同样适用 CA 证书 truststore 配置。

#故障排查