FIWARE-KeyPass 镜像文档

镜像概述

FIWARE-KeyPass是一款多租户XACML（可扩展访问控制标记语言）授权服务器，集成策略管理点（PAP）和策略决策点（PDP）能力。该镜像基于以下核心技术构建：

• Balana：完整实现XACML v2和v3规范的授权引擎
• Dropwizard：高性能RESTful Web服务开发框架

镜像状态：![Status]([***]
许可证：Apache 2.0
可用镜像：

• quay.io/fiware/keyspass
• docker.io/telefonicaiot/fiware-keypass

核心功能与特性

核心能力

• 多租户支持：可同时为多个租户提供独立的授权策略管理
• PAP功能：支持XACML策略的创建、检索、更新和删除
• PDP功能：接收XACML授权请求并返回决策结果（Permit/Deny等）
• XACML兼容性：全面支持XACML v2和v3规范

技术特性

• 基于Dropwizard框架，提供高吞吐量RESTful API
• 支持MySQL和PostgreSQL数据库存储策略数据
• 可从MySQL数据库迁移至PostgreSQL（v1.14.0及以上版本）
• 提供性能测试和行为测试支持

使用场景

• 多租户云平台：为SaaS应用提供租户隔离的访问控制策略管理
• FIWARE生态系统：作为FIWARE安全组件，为物联网平台提供细粒度授权
• 企业级应用：企业内部系统的统一授权策略管理，支持复杂访问规则定义
• API网关授权：与API网关集成，实现基于XACML的请求授权决策

使用方法

镜像获取

从Quay.io拉取镜像：

bash
docker pull quay.io/fiware/keyspass

或从Docker Hub拉取：

bash
docker pull telefonicaiot/fiware-keypass

基本运行示例

直接运行（使用默认配置）

bash
docker run -d -p 8080:8080 -p 8443:8443 --name keypass \
  quay.io/fiware/keyspass \
  server /app/conf/config.yml

挂载自定义配置文件

bash
docker run -d -p 8080:8080 -p 8443:8443 --name keypass \
  -v $(pwd)/conf:/app/conf \
  quay.io/fiware/keyspass \
  server /app/conf/custom-config.yml

配置文件示例可参考***配置模板，需根据实际数据库环境调整database配置段。

Docker Compose示例

yaml
version: '3'
services:
  keypass:
    image: quay.io/fiware/keyspass
    ports:
      - "8080:8080"  # HTTP API端口
      - "8443:8443"  # HTTPS API端口
    volumes:
      - ./conf:/app/conf  # 挂载本地配置目录
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_NAME=keypassDb
      - DB_USER=keypassUser
      - DB_PASSWORD=keypassPass
    depends_on:
      - postgres

  postgres:
    image: postgres:13
    environment:
      - POSTGRES_DB=keypassDb
      - POSTGRES_USER=keypassUser
      - POSTGRES_PASSWORD=keypassPass
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

API使用示例

创建策略

bash
curl -i -H "Accept: application/xml" -H "Content-type: application/xml" \
  -H "Fiware-Service: myTenant" \
  -X POST -d @policy01.xml \
  http://localhost:8080/pap/v1/subject/role***

检索策略

bash
curl -i -H "Fiware-Service: myTenant" \
  http://localhost:8080/pap/v1/subject/role***/policy/policy01

评估XACML授权请求

bash
curl -i -H "Accept: application/xml" -H "Content-type: application/xml" \
  -H "Fiware-Service: myTenant" \
  -X POST -d @policy01_request01.xml \
  http://localhost:8080/pdp/v3

从MySQL迁移到PostgreSQL

Keypass v1.14.0及以上版本支持从MySQL迁移至PostgreSQL，步骤如下：

前提条件

• MySQL需使用mysql_native_password认证插件（修改my.cnf配置并重启MySQL）：

  ini
  [mysqld]
  default-authentication-plugin=mysql_native_password
  

• 安装pgloader工具（用于数据迁移）

迁移步骤

1. 创建PostgreSQL数据库和用户：

   bash
   PGPASSWORD=postgresPass psql -h postgres-host -p 5432 -U postgres <<EOF
   CREATE DATABASE keypassDb;
   CREATE USER keypassUser WITH PASSWORD 'keypassPass';
   GRANT ALL PRIVILEGES ON DATABASE keypassDb TO keypassUser;
   ALTER DATABASE keypassDb OWNER TO keypassUser;
   EOF
   

2. 使用pgloader迁移数据：

   bash
   pgloader mysql://keypassUser:keypassPass@mysql-host:3360/keypassDb \
     postgresql://keypassUser:keypassPass@postgres-host:5432/keypassDb
   

3. 重命名表（修复大小写问题）：

   bash
   PGPASSWORD=keypassPass psql -h postgres-host -p 5432 -U keypassUser -d keypassDb <<EOF
   ALTER TABLE policy RENAME TO "Policy";
   EOF
   

4. 重启Keypass容器：

   bash
   docker restart keypass
   

更多资源

• API文档
• Docker配置详情
• 性能测试计划
• 行为测试