cerberustesting/cerberus-as-tomcat-keycloak

Cerberus (Tomcat + Keycloak Adapter) 镜像文档

1. 镜像概述

1.1 镜像说明

本镜像基于 Tomcat 应用服务器构建，包含 Cerberus 实例及 Keycloak 适配器，提供集成化的身份验证与授权解决方案。Cerberus 作为权限管理组件，结合 Keycloak 的身份管理能力，可实现对应用资源的细粒度访问控制。

1.2 主要用途

• 为基于 Tomcat 的 Java 应用提供统一的身份验证与授权服务
• 集成 Keycloak 实现企业级身份管理（支持 OIDC/SAML 协议）
• 简化 Cerberus 与 Keycloak 的部署流程，降低配置复杂度

2. 核心功能与特性

3. 使用场景与适用范围

3.1 典型使用场景

• 企业内部应用的统一身份认证与权限控制
• 基于 Tomcat 的 Java 应用集成 Keycloak 实现单点登录（SSO）
• 需要细粒度权限管理的多租户系统
• 需符合 OAuth 2.0/OIDC 标准的合规性要求的应用

3.2 适用范围

• 开发环境：快速搭建带身份验证的 Cerberus 测试实例
• 生产环境：为企业级应用提供稳定的权限管理服务（需配合外部数据库与持久化配置）

4. 使用方法与配置说明

4.1 基本使用（docker run 命令）

通过以下命令启动 Cerberus 实例，默认映射 Tomcat 8080 端口，并配置 Keycloak 连接参数：

bash
docker run -d \
  --name cerberus-tomcat-keycloak \
  -p 8080:8080 \
  -e CERBERUS_KEYCLOAK_URL="https://keycloak.example.com/auth" \
  -e CERBERUS_KEYCLOAK_REALM="myrealm" \
  -e CERBERUS_KEYCLOAK_CLIENT_ID="cerberus-client" \
  -e CERBERUS_KEYCLOAK_CLIENT_SECRET="your-client-secret" \
  cerberus-tomcat-keycloak:latest

4.2 Docker Compose 配置示例

创建 docker-compose.yml 文件，集成 Cerberus 与 Keycloak 服务（需提前部署 Keycloak）：

yaml
version: '3.8'

services:
  cerberus:
    image: cerberus-tomcat-keycloak:latest
    container_name: cerberus
    ports:
      - "8080:8080"  # Tomcat 应用端口
      - "8443:8443"  # 可选：HTTPS 端口（需配置证书）
    environment:
      # Keycloak 连接配置
      - CERBERUS_KEYCLOAK_URL="https://keycloak:8443/auth"  # Keycloak 服务地址
      - CERBERUS_KEYCLOAK_REALM="myrealm"                  # Keycloak Realm 名称
      - CERBERUS_KEYCLOAK_CLIENT_ID="cerberus-client"       # Keycloak 客户端 ID
      - CERBERUS_KEYCLOAK_CLIENT_SECRET="your-client-secret"# Keycloak 客户端密钥
      # Cerberus 核心配置
      - CERBERUS_LOG_LEVEL="INFO"                          # 日志级别（DEBUG/INFO/WARN/ERROR）
      - CERBERUS_SESSION_TIMEOUT="3600"                    # 会话超时时间（秒）
    volumes:
      - cerberus-config:/usr/local/tomcat/conf              # 持久化 Tomcat 配置
      - cerberus-logs:/usr/local/tomcat/logs                # 持久化日志
    depends_on:
      - keycloak  # 若 Keycloak 作为 Compose 服务部署，需添加依赖
    networks:
      - cerberus-net

  keycloak:  # 可选：本地部署 Keycloak（生产环境建议独立部署）
    image: quay.io/keycloak/keycloak:22.0.1
    container_name: keycloak
    ports:
      - "8443:8443"
    environment:
      - KEYCLOAK_ADMIN="admin"
      - KEYCLOAK_ADMIN_PASSWORD="admin-password"
    command: ["start-dev"]  # 开发模式（生产环境需替换为 start --https-certificate-file=...）
    networks:
      - cerberus-net

volumes:
  cerberus-config:
  cerberus-logs:

networks:
  cerberus-net:
    driver: bridge

4.3 环境变量配置

4.4 持久化数据

为避免容器重启后配置丢失，需挂载以下目录：

4.5 网络配置

• 外部访问：通过 -p 8080:8080 映射端口，确保宿主机防火墙开放 8080 端口。
• 内部通信：若 Keycloak 与 Cerberus 部署在同一 Docker 网络（如示例中的 cerberus-net），可通过容器名（如 keycloak）访问 Keycloak 服务。
• HTTPS 配置：生产环境需通过挂载证书文件至 /usr/local/tomcat/conf/ssl，并修改 server.xml 启用 HTTPS。

5. 注意事项

1. Keycloak 前置准备：使用前需在 Keycloak 中创建对应 Realm、客户端，并配置客户端密钥（机密客户端）或公开客户端。
2. 版本兼容性：Keycloak 适配器版本需与 Keycloak 服务版本匹配（如 Keycloak 22.x 需使用 22.x 适配器）。
3. 安全加固：生产环境需禁用 Tomcat 管理界面（默认关闭），并通过环境变量设置强密钥与密码。
4. 资源限制：根据负载调整容器资源（--memory=2g --cpus=1），避免 OOM 错误。
5. 日志监控：建议通过 ELK Stack 或 Prometheus 监控 /usr/local/tomcat/logs 目录下的日志文件。