IdP-in-a-Box Identity Sync 镜像文档

1. 镜像概述

本镜像为 IdP-in-a-Box（一体化身份提供商解决方案）的核心组件之一，专注于身份数据同步功能。其主要用途是在多个异构身份系统（如LDAP、OAuth 2.0服务、SAML IdP、企业HR系统等）之间实现用户身份数据的自动化同步，确保身份信息在分布式环境中的一致性和实时性。

2. 核心功能与特性

2.1 多源异构同步

• 支持多种身份数据源接入：LDAP目录服务、REST API接口、CSV文件、SQL数据库、SAML/OAuth身份提供商等。
• 支持多目标系统输出：同步至本地数据库、云身份服务（如Azure AD、Okta）、应用系统用户库等。

2.2 灵活的同步策略

• 实时同步：通过监听源系统事件（如WebHook、LDAP变更通知）触发即时数据同步。
• 定时同步：支持自定义Cron表达式配置周期性同步任务（如每小时、每日）。

2.3 数据处理与转换

• 内置数据映射引擎：支持用户属性（如用户名、***、角色、部门）的自定义映射与转换（格式转换、常量填充、条件过滤等）。
• 冲突解决机制：提供基于规则的冲突处理策略（如“源系统优先”“目标系统优先”“合并字段”）。

2.4 可观测性与审计

• 详细同步日志：记录同步过程、成功/失败状态及错误原因，支持日志分级（INFO/WARN/ERROR/DEBUG）。
• 同步状态监控：暴露健康检查接口，支持集成Prometheus等监控工具。

3. 使用场景与适用范围

3.1 企业多系统身份整合

• 场景：企业内部存在HR系统、OA系统、CRM系统等多套独立身份体系，需统一用户身份数据。
• 用途：通过本组件同步HR系统的员工入离职信息至其他业务系统，确保账号生命周期自动化管理。

3.2 混合云环境身份同步

• 场景：企业同时使用本地Active Directory（AD）和云服务（如Office 365、AWS IAM）。
• 用途：将AD中的用户身份数据同步至云服务，实现“一次身份验证，多系统访问”。

3.3 第三方应用身份供给

• 场景：企业采购SaaS应用（如Salesforce、Zoom），需为员工自动创建/更新应用账号。
• 用途：通过同步规则将企业主身份系统（如IdP）的用户数据推送至SaaS应用的用户管理接口。

3.4 身份数据备份与容灾

• 场景：核心身份系统需备份至备用数据库或异地灾备系统。
• 用途：定时将主身份库数据同步至备用存储，确保数据冗余与可恢复性。

4. 使用方法

4.1 前置条件

• 网络：确保容器可访问同步源系统、目标系统及依赖服务（如数据库）。
• 依赖：需提前部署关系型数据库（如PostgreSQL、MySQL）用于存储同步配置与状态数据（推荐PostgreSQL 13+）。
• 权限：同步源/目标系统需提供具备读（源）/写（目标）权限的访问凭证（如API密钥、账号密码）。

4.2 快速启动（docker run）

4.2.1 基础启动命令

bash
docker run -d \
  --name idp-identity-sync \
  -p 8080:8080 \  # 服务端口（健康检查、管理API）
  -e DB_HOST=postgres-host \
  -e DB_PORT=5432 \
  -e DB_NAME=identity_sync \
  -e DB_USER=sync_user \
  -e DB_PASSWORD=secure_password \
  -e LOG_LEVEL=INFO \
  -v /path/to/local/config:/app/config \  # 挂载自定义同步规则配置文件
  -v /path/to/logs:/app/logs \  # 持久化同步日志
  idp-in-a-box/identity-sync:latest

4.3 Docker Compose 部署

4.3.1 docker-compose.yml 示例

yaml
version: '3.8'

services:
  identity-sync:
    image: idp-in-a-box/identity-sync:latest
    container_name: idp-identity-sync
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      # 数据库配置
      - DB_TYPE=postgresql  # 支持 postgresql/mysql
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_NAME=identity_sync
      - DB_USER=sync_user
      - DB_PASSWORD=secure_password
      # 同步策略配置
      - SYNC_MODE=hybrid  # hybrid/realtime/scheduled；hybrid=实时+定时兜底
      - SCHEDULED_CRON=0 0 * * *  # 每日凌晨执行定时同步（Cron表达式）
      # 日志配置
      - LOG_LEVEL=INFO
      - LOG_FILE=/app/logs/sync.log
    volumes:
      - ./config:/app/config  # 存放同步规则配置文件（JSON/YAML格式）
      - ./logs:/app/logs
    depends_on:
      - postgres

  postgres:
    image: postgres:14-alpine
    container_name: identity-sync-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=identity_sync
      - POSTGRES_USER=sync_user
      - POSTGRES_PASSWORD=secure_password
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

5. 配置参数说明

5.1 核心环境变量

5.2 同步规则配置文件

同步规则需通过配置文件定义（推荐挂载至 /app/config/sync-rules.yaml），示例格式：

yaml
# /app/config/sync-rules.yaml
sync-jobs:
  - name: "hr-to-ad-sync"  # 同步任务名称（唯一）
    source:
      type: "rest-api"  # 源类型：rest-api/ldap/sql/csv
      config:
        url: "[***]"  # 源系统API地址
        method: "GET"
        auth:
          type: "basic"
          username: "hr-api-user"
          password: "hr-api-pass"
        pagination:
          enabled: true
          page-size: 100
    target:
      type: "ldap"  # 目标类型：ldap/rest-api/sql
      config:
        url: "ldap://ad.example.com:389"
        base-dn: "OU=Users,DC=example,DC=com"
        bind-dn: "CN=sync-user,OU=ServiceAccounts,DC=example,DC=com"
        bind-password: "ad-bind-pass"
    mapping:  # 字段映射规则
      - source-field: "employeeId"  # 源系统字段
        target-field: "uid"         # 目标系统字段
        transform: "lowercase"      # 转换函数（可选）
      - source-field: "email"
        target-field: "mail"
      - source-field: "department"
        target-field: "department"
        default-value: "Unknown"    # 源字段为空时的默认值
    conflict-resolution: "source-wins"  # 冲突解决策略：source-wins/target-wins/merge
    enabled: true  # 是否启用该任务

6. 数据持久化

需持久化的数据包括：

• 同步日志：挂载 /app/logs 目录至宿主机，避免容器重启后日志丢失。
• 数据库数据：通过独立的数据库容器（如示例中 postgres 服务）使用命名卷持久化数据。
• 配置文件：同步规则、证书等配置文件建议通过宿主机目录挂载，便于修改与版本控制。

7. 注意事项

• 网络安全：同步涉及敏感身份数据，建议通过TLS加密传输（配置源/目标系统HTTPS/LDAPS），并限制容器网络访问范围。
• 权限最小化：源/目标系统访问账号应遵循“最小权限原则”（如只读权限用于源，仅用户管理权限用于目标）。
• 版本兼容性：数据库需使用兼容版本（PostgreSQL ≥13，MySQL ≥8.0），避免因驱动不兼容导致连接失败。
• 性能优化：大规模同步（单次>1000用户）建议启用分页、增量同步（基于时间戳/版本号），减少资源占用。