必码

Appearance

Keycloak Sandbox 双沙箱环境 ​

项目简介 ​

Keycloak 沙箱项目是面向开发者打造的一站式 Keycloak SPI 开发环境，支持快速开发、测试和部署 Keycloak 服务提供者接口（SPI）。本项目提供完整的开发基座、多版本支持和内置沙箱环境，旨在帮助开发者快速构建、定制和部署符合企业需求的 Keycloak 扩展。

项目基于 Maven 多模块架构，提供 Docker 版和 Release 版两种沙箱环境，支持任意 Keycloak 版本切换，同时内置多个 SPI 开发示例，大幅提升 Keycloak 扩展开发效率。

界面预览 ​

Keycloak Sandbox 界面

技术支持 ​

核心功能 ​

Keycloak-Sandbox 一站式构建 SPI 开发沙箱

Keycloak-Sandbox 沙箱项目专为企业级 Keycloak 扩展开发深度打造，开箱即用、零门槛适配多版本 Keycloak，完美支撑开发、调试、部署全流程需求，解决 Keycloak 版本切换繁琐、SPI 开发调试困难等核心痛点。

01：多版本 Keycloak 支持 全局仅需在一个地方配置 Keycloak 版本，实现全局版本控制，开发者可根据项目需求灵活选择目标版本，无需担心版本兼容性问题，大幅提升开发适配效率。

02：双沙箱环境集成 内置两个沙箱环境：Docker 镜像版沙箱（需本机安装 Docker 环境）和 Release 发行版沙箱，均支持启动类和停止类，可在 IDE 中直接运行 main 方法，快速启动和停止沙箱。

03：SPI 一键打包发布 提供 SPI 一键打包功能，支持打包类，可在 IDE 中直接运行 main 方法，自动将开发的 SPI 打包为 JAR 并发布到指定的沙箱环境，简化部署流程。

04：内置 SPI 开发示例 提供 3 个 SPI 开发示例：用户存储扩展、国密算法扩展和事件监听扩展，为开发者提供参考实现。

05：标准化项目结构 采用 Maven 多模块架构，清晰分离沙箱环境、打包模块和SPI扩展模块，便于项目管理和代码维护。

项目结构 ​

keycloak-sandbox/
├── keycloak-server-docker/       # Docker 版沙箱环境
│   ├── src/main/java/cc/bima/keycloak/server/docker/  # 启动停止类
│   ├── src/main/resources/docker-compose.yml          # Docker 配置
│   └── pom.xml                                        # Maven 配置
├── keycloak-server-extensions/   # SPI 打包发布模块
│   ├── src/main/java/cc/bima/keycloak/extension/packages/  # 打包发布实现
│   └── pom.xml                                        # Maven 配置
├── keycloak-server-release/      # Release 版沙箱环境
│   ├── src/main/java/cc/bima/keycloak/server/release/  # 启动停止类
│   └── pom.xml                                        # Maven 配置
├── spi-event-listener-extension/ # 事件监听器 SPI 示例
│   ├── src/main/java/cc/bima/keycloak/extension/event/  # 事件监听器实现
│   └── pom.xml                                        # Maven 配置
├── spi-sm-crypto-extension/      # 国密算法 SPI 示例
│   ├── src/main/java/cc/bima/keycloak/extension/sm/    # 国密算法实现
│   └── pom.xml                                        # Maven 配置
├── spi-user-storage-extension/   # 用户存储 SPI 示例
│   ├── src/main/java/cc/bima/keycloak/extension/storage/  # 用户存储实现
│   └── pom.xml                                        # Maven 配置
├── .gitignore                    # Git 忽略文件
├── README.md                     # 项目说明文档
└── pom.xml                       # 父 Maven 配置

技术栈 ​

  • 后端：Java 11+, Keycloak
  • 构建：Maven 3.9+
  • 容器化：Docker, Docker Compose
  • SPI 扩展：Keycloak SPI
  • 示例功能：事件监听器、国密算法、用户存储

环境要求 ​

  • JDK：11+（根据所选 Keycloak 需要适配版本）
  • Maven：3.9+
  • Docker：（仅 Docker 版沙箱需要）
  • Keycloak：任意版本（根据需要切换）

快速开始 ​

1. 配置 Keycloak 版本 ​

在父 pom.xml 文件中配置目标 Keycloak 版本：

xml
<properties>
    <keycloak.version>26.6.1</keycloak.version> <!-- 根据需要修改版本 -->
</properties>

2. 启动沙箱环境 ​

注意： 首次启动沙箱时，会根据在父 pom.xml 中选定的 Keycloak 版本自动下载对应版本的 Docker 镜像或 Release 发行包，可能需要一些时间，请耐心等待，控制台会显示下载进度。

方式一：Docker 版沙箱 ​

Maven 命令方式：

bash
# 进入 Docker 版沙箱目录
cd keycloak-server-docker

# 启动 Docker 容器（首次启动会下载对应版本的 Docker 镜像）
mvn clean compile exec:java -Dexec.mainClass="cc.bima.keycloak.server.docker.KeycloakServerStart"

# 停止 Docker 容器
mvn exec:java -Dexec.mainClass="cc.bima.keycloak.server.docker.KeycloakServerStop"

IDE 直接运行方式：

  1. 在 IDE 中找到 keycloak-server-docker/src/main/java/cc/bima/keycloak/server/docker/KeycloakServerStart.java 文件
  2. 右键点击该文件，选择 "Run As" -> "Java Application" 启动服务（首次启动会下载对应版本的 Keycloak Docker 镜像）
  3. 同样，可通过运行 KeycloakServerStop.java 停止服务

方式二：Release 版沙箱（推荐） ​

Maven 命令方式：

bash
# 进入 Release 版沙箱目录
cd keycloak-server-release

# 启动 Keycloak 服务器（首次启动会下载对应版本的 Release 包）
mvn clean compile exec:java -Dexec.mainClass="cc.bima.keycloak.server.release.KeycloakServerStart"

# 停止 Keycloak 服务器
mvn exec:java -Dexec.mainClass="cc.bima.keycloak.server.release.KeycloakServerStop"

IDE 直接运行方式：

  1. 在 IDE 中找到 keycloak-server-release/src/main/java/cc/bima/keycloak/server/release/KeycloakServerStart.java 文件
  2. 右键点击该文件，选择 "Run As" -> "Java Application" 启动服务（首次启动会下载对应版本的 Keycloak Release 发行包）
  3. 同样，可通过运行 KeycloakServerStop.java 停止服务

3. 开发 SPI 扩展 ​

  1. 选择 SPI 示例模块：根据需求选择对应的 SPI 示例模块（spi-event-listener-extension、spi-sm-crypto-extension 或 spi-user-storage-extension）

  2. 修改扩展代码：在对应模块中修改或添加 SPI 实现

  3. 打包发布 SPI：

Maven 命令方式：

bash
# 进入扩展打包模块目录
cd keycloak-server-extensions

# 打包并发布 SPI 到沙箱环境
mvn clean package exec:java -Dexec.mainClass="cc.bima.keycloak.extension.packages.ExtensionPackagesMain"

IDE 直接运行方式：

  1. 在 IDE 中找到 keycloak-server-extensions/src/main/java/cc/bima/keycloak/extension/packages/ExtensionPackagesMain.java 文件
  2. 右键点击该文件，选择 "Run As" -> "Java Application" 执行打包和发布操作，可选择发布到 Docker 或 Release 版沙箱环境。

4. 访问 Keycloak 服务 ​

  • Docker 版沙箱地址：http://localhost:8080
  • Release 版沙箱地址：http://localhost:8080

默认管理员账号：

  • 用户名：root
  • 密码：root

SPI 开发示例（仅为参考实现，演示沙箱环境） ​

1. 事件监听器扩展（spi-event-listener-extension） ​

功能说明：监听 Keycloak 事件并发送到消息队列（Kafka、RabbitMQ、RocketMQ）。

核心实现：

  • AuditEventListenerProvider：事件监听器实现
  • AuditEventListenerProviderFactory：事件监听器工厂
  • 支持多种消息通道：Kafka、RabbitMQ、RocketMQ

使用场景：审计日志、事件通知、实时监控等。

2. 国密算法扩展（spi-sm-crypto-extension） ​

功能说明：实现国家密码局规定的国密算法（SM2、SM3、SM4），为 Keycloak 提供国密算法支持。

核心实现：

  • SMContentEncryptionProvider：国密内容加密实现
  • SMHashProvider：国密哈希算法实现
  • SMKeyProvider：国密密钥提供者
  • SMSignatureProvider：国密签名实现

使用场景：需要符合国家密码标准的企业级应用、政务系统等。

3. 用户存储扩展（spi-user-storage-extension） ​

功能说明：自定义用户存储提供者，支持从自定义数据源加载用户信息。

核心实现：

  • CustomUserModel：自定义用户模型
  • CustomUserStorageProvider：用户存储提供者实现
  • CustomUserStorageProviderFactory：用户存储提供者工厂

使用场景：对接企业现有用户系统、自定义用户管理逻辑等。

扩展与定制 ​

1. 添加新的 SPI 扩展 ​

  1. 创建新模块：在项目根目录下创建新的 Maven 模块
  2. 实现 SPI 接口：根据 Keycloak SPI 文档实现相应接口
  3. 配置服务文件：在 META-INF/services/ 目录下创建服务文件
  4. 打包发布：使用 keycloak-server-extensions 模块打包发布

2. 切换 Keycloak 版本 ​

  1. 修改版本配置：在父 pom.xml 文件中修改 keycloak.version 属性
  2. 重新构建：执行 mvn clean compile 重新构建项目
  3. 启动沙箱：启动对应沙箱环境验证版本切换效果

3. 定制沙箱环境 ​

  • Docker 版沙箱：修改 keycloak-server-docker/src/main/resources/docker-compose.yml 文件
  • Release 版沙箱：修改 keycloak-server-release 模块的配置

测试（仅演示功能，不建议在生产环境中使用） ​

验证 SPI 功能 ​

  1. 启动沙箱环境：启动 Docker 版或 Release 版沙箱
  2. 登录管理控制台：访问 http://localhost:8080 并登录
  3. 配置 SPI：根据 SPI 类型在管理控制台中进行配置
  4. 测试功能：执行相应操作验证 SPI 功能是否正常

免责声明 ​

本项目基于 GitHub 开源软件进行定制化开发，旨在为企业和开发者提供更便捷的项目基座解决方案。使用本项目时，请务必了解以下免责声明：

  1. 开源基础：本项目基于 GitHub 开源软件构建，遵循原开源协议的相关规定。
  2. 定制开发：我们对原开源软件进行了定制和扩展，以提供更优质的开发体验和功能支持。
  3. 责任限制：对于使用本项目可能产生的任何直接或间接的经济损失、数据丢失或其他问题，北京必码科技工作室不承担任何责任。
  4. 使用建议：在生产环境中使用本项目前，请进行充分的测试和验证，确保其符合您的业务需求和安全要求。
  5. 技术支持：我们提供技术支持服务，但不保证解决所有可能出现的问题。
  6. 合规使用：用户应确保在使用本项目时遵守相关法律法规和行业规范，不得用于任何违法或违规用途。

© 2024-至今 北京必码科技工作室 bima.cc