add pom.xml and README for PwdLockToEnabledMapper provider

- Add pom.xml with Keycloak 26.1.1 dependencies and maven.compiler.release=21 - Add provider usage documentation in README.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-20 15:05:38 +08:00
parent 0556b882ac
commit 870ebbf7d6
3 changed files with 134 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Keycloak OpenLDAP PPolicy Status Mapper
+
+将 OpenLDAP 的 `pwdAccountLockedTime` 属性映射为 Keycloak 的用户启用/禁用状态。
+
+## 背景
+
+OpenLDAP 使用 ppolicy overlay 管理密码策略，当账号被锁定时会设置 `pwdAccountLockedTime` 属性。Keycloak 默认无法识别该属性，导致 LDAP 中已锁定的用户在 Keycloak 中仍然显示为启用状态。
+
+本 provider 通过自定义 LDAP Storage Mapper 解决这一问题。
+
+## 工作原理
+
+1. **LDAP 查询阶段** — `beforeLDAPQuery` 中将 `pwdAccountLockedTime` 加入返回属性，确保 LDAP 查询结果包含该字段
+2. **用户导入阶段** — `onImportUserFromLDAP` 中读取 `pwdAccountLockedTime` 的值：
+   - 属性存在且非空 → 用户设置为 `enabled = false`
+   - 属性不存在或为空 → 用户设置为 `enabled = true`
+
+> **注意**：OpenLDAP 管理员主动禁用账号时，`pwdAccountLockedTime` 通常被设为 `000001010000Z`，该场景同样会被识别为锁定。
+
+## 构建
+
+```bash
+mvn clean package
+```
+
+构建产物位于 `providers/PwdLockToEnabledMapper/target/`。
+
+## 部署
+
+1. 将构建生成的 JAR 文件复制到 Keycloak 的 providers 目录：
+
+```bash
+cp providers/PwdLockToEnabledMapper/target/pwd-lock-to-enabled-mapper.jar \
+   <KEYCLOAK_HOME>/providers/
+```
+
+2. 重启 Keycloak 或执行一次构建：
+
+```bash
+<KEYCLOAK_HOME>/bin/kc.sh build
+```
+
+## 配置
+
+1. 登录 Keycloak Admin Console
+2. 进入目标 Realm → **User Federation** → 选择已配置的 LDAP provider
+3. 在 **Mappers** 标签页点击 **Add mapper**
+4. 填写配置：
+   - **Mapper Type**：选择 `OpenLDAP PPolicy Status Mapper`
+   - **Name**：自定义名称，如 `pwdLockStatus`
+5. 保存
+
+配置完成后，下次 LDAP 同步时将自动根据 `pwdAccountLockedTime` 更新用户启用状态。
+
+## 项目结构
+
+```
+providers/PwdLockToEnabledMapper/
+└── src/main/
+    ├── java/com/example/keycloak/
+    │   ├── PwdLockToEnabledMapper.java         # Mapper 实现
+    │   └── PwdLockToEnabledMapperFactory.java  # Factory，provider ID: openldap-ppolicy-mapper
+    └── resources/META-INF/services/
+        └── org.keycloak.storage.ldap.mappers.LDAPStorageMapperFactory  # SPI 注册
+```
+
+## 前提条件
+
+- Keycloak 版本需支持 `AbstractLDAPStorageMapper` / `AbstractLDAPStorageMapperFactory` API
+- OpenLDAP 需启用 ppolicy overlay
+- LDAP 用户条目需包含 `pwdAccountLockedTime` 属性（ppolicy overlay 自动管理）
+
+## 限制
+
+- 仅支持 LDAP → Keycloak 单向同步，Keycloak 中的禁用操作不会同步回 LDAP
+- `pwdAccountLockedTime` 属性必须可被 Keycloak 的 LDAP 服务账号读取
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.example.keycloak</groupId>
+    <artifactId>PwdLockToEnabledMapper</artifactId>
+    <version>1.0.0</version>
+    <packaging>jar</packaging>
+
+    <properties>
+        <maven.compiler.release>21</maven.compiler.release>
+        <keycloak.version>26.1.1</keycloak.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.keycloak</groupId>
+            <artifactId>keycloak-server-spi</artifactId>
+            <version>${keycloak.version}</version>
+            <scope>provided</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.keycloak</groupId>
+            <artifactId>keycloak-server-spi-private</artifactId>
+            <version>${keycloak.version}</version>
+            <scope>provided</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.keycloak</groupId>
+            <artifactId>keycloak-services</artifactId>
+            <version>${keycloak.version}</version>
+            <scope>provided</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.keycloak</groupId>
+            <artifactId>keycloak-ldap-federation</artifactId>
+            <version>${keycloak.version}</version>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <finalName>PwdLockToEnabledMapper</finalName>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.13.0</version>
+            </plugin>
+        </plugins>
+    </build>
+</project>